TypeScript icon, indicating that this package has built-in type declarations

0.6.0 • Public • Published

StackInsights NodeJS Agent

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

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

Install StackInsights NodeJS package from npmjs

$ npm install --save stackinsights-backend-js

Set up NodeJS Agent

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

import agent from 'stackinsights-backend-js';


This will use default configurations to start the StackInsights 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 Variable Description Default
SW_AGENT_NAME The name of the service your-nodejs-service
SW_AGENT_INSTANCE The name of the service instance Randomly generated
SW_AGENT_SECURE Whether to use secure connection to backend OAP server false
SW_AGENT_AUTHENTICATION The 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_LEVEL The logging level, could be one of error, warn, info, debug info
SW_AGENT_DISABLE_PLUGINS Comma-delimited list of plugins to disable in the plugins directory (e.g. "mysql", "express") ``
SW_COLD_ENDPOINT Cold start detection is as follows: First span to run is considered a cold start. This span gets the tag coldStart set to 'true'. This span also optionally gets the text '<cold>' appended to the endpoint name if SW_COLD_ENDPOINT is set to 'true'. false
SW_IGNORE_SUFFIX The 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_PATH The paths of endpoints that will be ignored (not traced), comma separated ``
SW_HTTP_IGNORE_METHOD Comma-delimited list of http methods to ignore (GET, POST, HEAD, OPTIONS, etc...) ``
SW_SQL_TRACE_PARAMETERS If set to 'true' then SQL query parameters will be included false
SW_SQL_PARAMETERS_MAX_LENGTH The maximum string length of SQL parameters to log 512
SW_MONGO_TRACE_PARAMETERS If set to 'true' then mongodb query parameters will be included false
SW_MONGO_PARAMETERS_MAX_LENGTH The maximum string length of mongodb parameters to log 512
SW_AWS_LAMBDA_FLUSH Maximum number of float seconds allowed to pass between invocations before consecutive Lambda function calls flush automatically upon exit, 0 means always flush, -1 means never. 2
SW_AWS_LAMBDA_CHAIN Pass trace ID to AWS Lambda function in its parameters (to allow linking). Only use if both caller and callee will be instrumented. false
SW_AWS_SQS_CHECK_BODY Incoming SQS messages check inside the body for trace ID in order to allow linking outgoing SNS messages to incoming SQS. false
SW_AGENT_MAX_BUFFER_SIZE The maximum buffer size before sending the segment data to backend '1000'

Note that the various ignore options like SW_IGNORE_SUFFIX, SW_TRACE_IGNORE_PATH and SW_HTTP_IGNORE_METHOD as well as endpoints which are not recorded due to exceeding SW_AGENT_MAX_BUFFER_SIZE all propagate their ignored status downstream to any other endpoints they may call. If that endpoint is running the Node Stackinsights agent then regardless of its ignore settings it will not be recorded since its upstream parent was not recorded. This allows the elimination of entire trees of endpoints you are not interested in as well as eliminating partial traces if a span in the chain is ignored but calls out to other endpoints which are recorded as children of ROOT instead of the actual parent.

Supported Libraries

Some built-in plugins support automatic instrumentation of NodeJS libraries, the complete list is as follows:

Library Plugin Name
built-in http and https module http / https
Express express
Axios axios
MySQL mysql
MySQL mysql2
PostgreSQL pg
pg-cursor pg-cursor
MongoDB mongodb
Mongoose mongoose
RabbitMQ amqplib
Redis ioredis
AWS2DynamoDB aws-sdk
AWS2Lambda aws-sdk
AWS2SNS aws-sdk
AWS2SQS aws-sdk

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:

Library Underlying Plugin Name
request http / https
request-promise http / https
koa http / https

Experimental Azure Functions Support

The plugin AzureHttpTriggerPlugin provides a wrapper function for an Azure Functions Javascript HttpTrigger endpoint. This is an http server endpoint and currently must be instrumented manually. So far all other plugins tested work within the HttpTrigger and so a trace can pass through the Function and onto other endpoints called by the function. How much sense it makes to instrument an Azure Function which already lives in the cloud and has robust monitoring incorporated is a good question, but at the least, this plugin will allow those endpoints to show up in a Stackinsights trace.


const {default: agent, AzureHttpTriggerPlugin} = require('stackinsights-backend-js');

agent.start({ ... });

module.exports = AzureHttpTriggerPlugin.wrap(async function (context, req) {

  /* contents of http trigger function */


All that needs to be done is the actual trigger function needs to be wrapped with azureHttpTriggerPlugin.wrap(), whether that function is a default export or an explicitly named entryPoint or run or index.

Experimental AWS Lambda Functions Support

The plugins AWSLambdaTriggerPlugin, AWSLambdaGatewayAPIHTTP and AWSLambdaGatewayAPIREST provide a wrapper functions for AWS Lambda Functions endpoints. AWSLambdaTriggerPlugin is a generic wrapper plugin which should work with any kind of Lambda trigger but also stores the least amount of information since it does not know anything about the incoming data format. For this reason, this type of trigger also can not link back to the caller, but it can create a new segment that will be propagated to all downstream children, thus starting its own trace. AWSLambdaGatewayAPIHTTP and AWSLambdaGatewayAPIREST are specific wrappers for Lambda functions triggered by the GatewayAPI HTTP or REST triggers. They have the advantage of knowing the incoming data format and can thus extract existing trace segment information from incoming requests and chain correctly from upstream to any downstream endpoints.


const {default: agent, AWSLambdaGatewayAPIHTTP} = require('stackinsights-backend-js');

agent.start({ ... });

exports.handler = AWSLambdaGatewayAPIHTTP.wrap(async function (event, context, callback) {

  /* contents of http trigger function */


This is similar to Azure Functions wrapping, just wrap your handler function with AWSLambdaTriggerPlugin.wrap() or AWSLambdaGatewayAPIHTTP.wrap() or AWSLambdaGatewayAPIREST.wrap(). One thing to note is that AWS freezes processes in between invocations of lambda functions so whether you are doing async or sync handler functions with callbacks, you should make sure everything you need to do finishes before returning control to AWS or calling the synchronous callback. These plugins take this into account and automatically flush the segment buffers before closing a trace span.

Experimental Webpack Support

Webpack requires that all imports be statically defined at compile-time and so was not compatible with the dynamic search and loading done by the standard PluginInstaller. This has been extended to attempt static imports if the application is determined to be running out of a webpack bundle. This requires that any new plugins be manually added to PluginInstaller.installBundled(). Only plugins which allow a require('module/package.json') will work with this method as package.json needs to be loaded to determine the version of the plugin module present. Some modules specifically disallow import of their package.json and so can not be loaded like this.

Upon compile with webpack it will complain about missing modules for which imports are attempted in the sw agent but which are not present. Simply add these modules to the list of modules to be ignored by webpack, for example by resolve: {alias: {'module': false}}.

Package Sidebar


npm i stackinsights-backend-js

Weekly Downloads






Unpacked Size

1.26 MB

Total Files


Last publish


  • vjykhade