Instrument a Node.js application with SkyWalking to report trace data to the Managed Service for OpenTelemetry console. After setup, you can monitor application topology, traces, abnormal and slow transactions, and SQL analysis.
SkyWalking Node.js agent
skywalking-backend-js is the official SkyWalking Node.js agent. It automatically instruments supported third-party libraries without code changes.
skyapm-nodejs is a discontinued earlier version. Use skywalking-backend-js instead.
Get the endpoint and token
Get an endpoint and authentication token from the Managed Service for OpenTelemetry console:
Log on to the ARMS console. In the left-side navigation pane, click Integration Center.
On the Integration Center page, click the SkyWalking card in the Server-side Applications section.
In the SkyWalking panel, click the Start Integration tab, and then select a region.
NoteWhen 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.
Install and configure the agent
Step 1: Install the agent
Run the following command to install skywalking-backend-js:
npm install --save skywalking-backend-jsStep 2: Initialize the agent
Add the following code at the top of your application entry file, before importing any other modules. The agent must load first to properly instrument third-party libraries.
const {default: agent} = require("skywalking-backend-js");
agent.start({});Step 3: Configure the agent
Configure the agent with your endpoint, authentication token, and service name. Choose one of the following methods.
Option 1: Environment variables (recommended)
Set the following environment variables before starting your application:
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<endpoint>
export SW_AGENT_AUTHENTICATION=<token>
export SW_AGENT_NAME=<service-name>| Variable | Description |
|---|---|
SW_AGENT_COLLECTOR_BACKEND_SERVICES | The endpoint copied from the ARMS console |
SW_AGENT_AUTHENTICATION | The authentication token from the endpoint panel |
SW_AGENT_NAME | A name to identify your application |
With environment variables, the initialization code from Step 2 is sufficient. No additional configuration is needed in the code.
Option 2: In-code configuration
Pass configuration directly in the agent.start() call:
const {default: agent} = require("skywalking-backend-js");
agent.start({
serviceName: "<your-service-name>", // Identifies the application in the console
collectorAddress: "<collector-backend-address>", // The endpoint obtained from the ARMS console
authorization: "<collector-token>" // The authentication token from the endpoint panel
});Replace the following placeholders with actual values:
| Placeholder | Description | Example |
|---|---|---|
<your-service-name> | A name to identify your application | my-nodejs-app |
<collector-backend-address> | The endpoint copied from the ARMS console | tracing-analysis-dc-sg.aliyuncs.com:8000 |
<collector-token> | The authentication token from the endpoint panel | abc123xxx |
Step 4: Restart the application
Restart the application for the changes to take effect.
Verify the result
After the application restarts, check the Managed Service for OpenTelemetry console for incoming trace data. It may take 2 to 3 minutes for the first traces to appear. Verify that the following monitoring data is available:
Application topology
Traces
Abnormal transactions
Slow transactions
SQL analysis
Sample code
For a complete working example, see the skywalking-demo repository on GitHub.