The NodeJS agent for Apache SkyWalking

Clone this repo:
  1. 4011a53 Added http ignore by method (#49) by Tomasz Pytel · 13 hours ago master
  2. 7a5c054 added secure connection option (#48) by Tomasz Pytel · 8 days ago
  3. 8f19bea Update NOTICE (#47) by Zhenxu Ke · 3 weeks ago
  4. 912ad72 BugFix: wrong context during many async spans (#46) by Tomasz Pytel · 3 weeks ago
  5. 4670a45 Node Mongoose Plugin (#44) by Tomasz Pytel · 3 weeks ago

SkyWalking NodeJS Agent

SkyWalking-NodeJS: The NodeJS Agent for Apache SkyWalking, which provides the native tracing abilities for NodeJS backend project.

SkyWalking: an APM(application performance monitor) system, especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.

GitHub stars Twitter Follow

Build npm version

Install SkyWalking NodeJS package from npmjs

$ npm install --save skywalking-backend-js

Set up NodeJS Agent

SkyWalking NodeJS SDK requires SkyWalking backend (OAP) 8.0+ and NodeJS >= 10.

import agent from 'skywalking-backend-js';


This will use default configurations to start the SkyWalking agent above, if you want to specify your own configurations, here are two methods.

  • Pass those values to agent.start method, such as:
  serviceName: 'my-service-name',
  serviceInstance: 'my-service-instance-name',
  collectorAddress: 'my.collector.address:port',

note that all options given (including empty/null values) will override the corresponding default values, e.g. agent.start({ collectorAddress: '' }) will override the default value of collectorAddress to empty string, causing errors like DNS resolution failed.

  • Use environment variables.

The supported environment variables are as follows:

Environment VariableDescriptionDefault
SW_AGENT_NAMEThe name of the serviceyour-nodejs-service
SW_AGENT_INSTANCEThe name of the service instanceRandomly generated
SW_AGENT_COLLECTOR_BACKEND_SERVICESThe backend OAP server address127.0.0.1:11800
SW_AGENT_SECUREWhether to use secure connection to backend OAP serverfalse
SW_AGENT_AUTHENTICATIONThe authentication token to verify that the agent is trusted by the backend OAP, as for how to configure the backend, refer to the yaml.not set
SW_AGENT_LOGGING_LEVELThe logging level, could be one of error, warn, info, debuginfo
SW_AGENT_DISABLE_PLUGINSComma-delimited list of plugins to disable in the plugins directory (e.g. “mysql”, “express”).``
SW_IGNORE_SUFFIXThe suffices of endpoints that will be ignored (not traced), comma separated.jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg
SW_TRACE_IGNORE_PATHThe paths of endpoints that will be ignored (not traced), comma separated``
SW_HTTP_IGNORE_METHODComma-delimited list of http methods to ignore (GET, POST, HEAD, OPTIONS, etc...)``
SW_SQL_TRACE_PARAMETERSIf set to ‘true’ then SQL query parameters will be includedfalse
SW_SQL_PARAMETERS_MAX_LENGTHThe maximum string length of SQL parameters to log512
SW_MONGO_TRACE_PARAMETERSIf set to ‘true’ then mongodb query parameters will be includedfalse
SW_MONGO_PARAMETERS_MAX_LENGTHThe maximum string length of mongodb parameters to log512
SW_AGENT_MAX_BUFFER_SIZEThe maximum buffer size before sending the segment data to backend'1000'

Supported Libraries

There are some built-in plugins that support automatic instrumentation of NodeJS libraries, the complete lists are as follows:

LibraryPlugin Name
built-in http and https modulehttp / https

Compatible Libraries

The following are packages that have been tested to some extent and are compatible because they work through the instrumentation of an underlying package:

LibraryUnderlying Plugin Name
requesthttp / https
request-promisehttp / https
koahttp / https

Contact Us


Apache 2.0