Use skywalking-backend-js to report Node.js application data, Use skywalking-backend-js to report Node.js application data - Application Real-Time Monitoring Service

The SkyWalking Node.js agent (skywalking-backend-js) automatically instruments your Node.js application and reports trace data to Managed Service for OpenTelemetry. After setup, application topology, traces, abnormal and slow transactions, and SQL analysis are available in the console.

Prerequisites

Before you begin, make sure you have:

Node.js installed
An endpoint and authentication token from the Managed Service for OpenTelemetry console (see Get an endpoint below)

Get an endpoint

New console

Log on to the Managed Service for OpenTelemetry console. In the left-side navigation pane, click Integration Center.
On the Integration Center page, click the SkyWalking card in the Open Source Frameworks section.
In the SkyWalking panel, click the Start Integration tab, and then select the region where you want to report data.

Note
When you access a region for the first time, resources are automatically initialized there.
Configure the Connection Type parameter and copy the endpoint.
- If your service runs on Alibaba Cloud in the selected region, select Alibaba Cloud VPC Network.
- Otherwise, select Public Network.

Old console

Log on to the Managed Service for OpenTelemetry console.
In the left-side navigation pane, click Cluster Configurations. On the page that appears, click the Access point information tab.
In the top navigation bar, select the region where you want to report data. In the Cluster Information section, turn on Show Token.
Set the Client parameter to SkyWalking. In the Related Information column, copy the endpoint.

Note
If your application runs in an Alibaba Cloud production environment, use a VPC endpoint. Otherwise, use a public endpoint.

Step 1: Install the agent

In your Node.js project directory, run:

npm install --save skywalking-backend-js

Step 2: Initialize the agent

Import and start the agent at the very top of your application entry file, before any other require or import statements.

Note

The agent patches module loading to enable automatic instrumentation. If you import it after other modules, those modules will not be instrumented. This is the most common cause of missing trace data.

Two initialization options are available:

Environment variables (recommended) — keeps credentials out of source code. Use this for production.
Inline configuration — passes values directly in code. Simpler for local development.

Option 1: Environment variables (recommended)

Set these environment variables before starting your application:

export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-endpoint>
export SW_AGENT_AUTHENTICATION=<your-auth-token>
export SW_AGENT_NAME=<your-service-name>

Then start the agent with no inline configuration:

const { default: agent } = require("skywalking-backend-js");
agent.start({});

Each environment variable maps to a configuration parameter:

Environment variable	Configuration parameter	Description
`SW_AGENT_COLLECTOR_BACKEND_SERVICES`	`collectorAddress`	Endpoint of the collector
`SW_AGENT_AUTHENTICATION`	`authorization`	Authentication token
`SW_AGENT_NAME`	`serviceName`	Application name in the console

Option 2: Inline configuration

// MUST be the first import in your application
const { default: agent } = require("skywalking-backend-js");

agent.start({
  // Service name displayed in the Managed Service for OpenTelemetry console
  serviceName: "<your-service-name>",
  // Endpoint from the console (see Get an endpoint above)
  collectorAddress: "<your-collector-endpoint>",
  // Authentication token from the console
  authorization: "<your-auth-token>",
});

// All other imports go below
const express = require("express");
// ...

Replace the placeholders with your actual values:

Placeholder	Description	Example
`<your-service-name>`	Name that identifies your application in the console	`my-node-app`
`<your-collector-endpoint>`	Endpoint copied from the console	See Get an endpoint above
`<your-auth-token>`	Authentication token from the console	See Get an endpoint above

Step 3: Verify the setup

Restart your Node.js application.
Send a few requests to generate trace data.
Open the Managed Service for OpenTelemetry console and check for your service name in the application list.

Trace data typically appears within a few minutes. If your service does not appear, check that:

The agent import is the first require statement in your entry file
The endpoint and token values are correct
Your application can reach the collector endpoint over the network

Automatically instrumented libraries

The agent instruments the following libraries without additional configuration:

Library	Plug-in name
Built-in HTTP and HTTPS module	http / https
Express	express
Axios	axios
MySQL	mysql
MySQL2	mysql2
PostgreSQL	pg
pg-cursor	pg-cursor
MongoDB	mongodb
Mongoose	mongoose
RabbitMQ	amqplib
Redis	ioredis
AWS DynamoDB	aws-sdk
AWS Lambda	aws-sdk
AWS SNS	aws-sdk
AWS SQS	aws-sdk

Sample code

For a complete working example, see the skywalking-demo repository on GitHub.

About SkyWalking

SkyWalking is an open-source application performance monitoring (APM) and distributed tracing system originally developed in China, designed for microservices, cloud-native, and container-based environments (Docker, Kubernetes, Mesos).

skywalking-backend-js is the current official SkyWalking Node.js agent. It replaces the discontinued skyapm-nodejs package.