Fetching contributors…
Cannot retrieve contributors at this time
114 lines (78 sloc) 6.13 KB

instana-nodejs-sensor   Build Status NSP Status OpenTracing Badge

Monitor your Node.js applications with Instana!

Installation | OpenTracing | Configuration | Changelog

Installation and Usage

The installation of the Instana Node.js sensor is a simple two step process. First, install the instana-nodejs-sensor package in your application via:

npm install --save instana-nodejs-sensor

Now that the sensor is installed, it needs to be activated from within the application. Do this by requiring and initializing it as the first statement in your application. Please take care that this is the first statement as the sensor will otherwise not be able to access certain information.


// All other require statements must be done after the sensor is initialized.
// Note the () after the require statement of the sensor which initializes it.
// const express = require('redis');

The code shown above initializes the sensor with default configuration options. Refer to the file for a list of valid configuration options.

Garbage Collection and Event Loop Information

Some information is not available to Node.js programs without the help of native addons. Specifically, the Instana Node.js sensor uses these addons to retrieve information about garbage collection and event loop activity. While the sensor works fine without these native addons (technically, they are marked as optional dependencies), we strongly recommend you to support native addon compilation.

Native addons are compiled automatically for your system and Node.js version when the Instana Node.js sensor dependency is installed (as part of the npm install step). In order for the compilation to work, the system needs to have tools like make and g++ installed. These tools can often be installed via a bundle called build-essential or similar (depending on your package manager and registry). The following example shows how to do this for a typical Ubuntu setup.

apt-get install build-essential
# -or-
yum groupinstall "Development Tools"

It is important that the installation of the dependencies is happening on the machine which will run the application. This needs to be ensured, because otherwise native addons may be incompatible with the target machine's system architecture or the Node.js version in use. It is therefore a bad practice to npm install dependencies on a build server and to copy the application (including the dependencies) to the target machine.


This sensor automatically instruments widely used APIs to add tracing support, e.g. HTTP server / client of the Node.js core API. Sometimes you may find that this is not enough or you may already have invested in OpenTracing. The OpenTracing API is implemented by this Node.js sensor. This API can be used to provide insights into areas of your applications, e.g. custom libraries and frameworks, which would otherwise go unnoticed.

In order to use OpenTracing for Node.js with Instana, you need to enable tracing and use the Instana OpenTracing API implementation. The following sample project shows how this is done.

const instana = require('instana-nodejs-sensor');

// Always initialize the sensor as the first module inside the application.
  tracing: {
    enabled: true

const opentracing = require('opentracing');

// optionally use the opentracing provided singleton tracer wrapper

// retrieve the tracer instance from the opentracing tracer wrapper
const tracer = opentracing.globalTracer();

// start a new trace with an operation name
const span = tracer.startSpan('auth');

// mark operation as failed
span.setTag(opentracing.Tags.ERROR, true);

// finish the span and schedule it for transmission to instana


The Instana Node.js sensor does not yet have support for OpenTracing binary carriers. This OpenTracing implementation will silently ignore OpenTracing binary carrier objects.

Care should also be taken with OpenTracing baggage items. Baggage items are meta data which is transported via carrier objects across network boundaries. Furthermore, this meta data is inherited by child spans (and their child spans…). This can produce some overhead. We recommend to completely avoid the OpenTracing baggage API.


How can the Node.js sensor be disabled for (local) development?

The easiest way to disable the Node.js sensor for development is to use environment variables. The Express framework popularized the environment variable NODE_ENV for this purpose, which we recommend to use for this purpose. Load the Node.js sensor in the following way:

if (process.env.NODE_ENV !== 'development') {

Next, start your application locally with the NODE_ENV variable set to development. Example:

export NODE_ENV=development
# -or-
NODE_ENV=development node myApp.js