Supported Node.js Versions

Automatic tracing is supported in the following Node.js versions:

Node.js Version Support Required Version
4.5 and above Yes 1.0.0
5.10 and above Yes 1.0.0
6.0.0 and above Yes 1.0.0
7.0.0 and above Yes 1.23.1
8.2.1 and above Yes 1.28.0
9.1.0 and above Yes 1.37.0
10.4.0 and above Yes 1.38.0
11.0.0 and above Yes 1.58.0
12.0.0 and above Yes 1.67.0

This means that automatic tracing works for example for all 4.x versions beginning with 4.5, but not for 4.0.0 - 4.4.x. Similar version ranges are given for the other Node.js release lines, for example Node.js 10.x is supported beginning with 10.4.0; automated tracing is not supported for Node.js releases 10.0.0 - 10.3.x. Note that newer Node.js versions typically require an up to date version of @instana/collector. For example, to have automatic tracing in Node.js 12.x, you need to use at least @instana/collector@1.67.0.

Metrics, configuration data and manual tracing via the OpenTracing API is supported in versions 4.0.0 and above.

We usually support LTS versions of Node.js (those with even major version numbers, that is, Node.js 8, 10, 12, …) for about one year after their official end of life. Non-LTS versions (those with odd major version numbers) are supported until their EOL. You can find out about Node.js releases and their lifecycle on this page (or here for older releases).


The installation of the Instana Node.js collector is a simple two step process. First, install the npm package @instana/collector in your application via:

npm install --save @instana/collector

Now that the collector 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 collector will otherwise not be able to access certain information.


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

Change of Package Name

Up to release 1.64.0, our npm package was called instana-nodejs-sensor. Beginning with version 1.65.0 the name has changed to @instana/collector. To prevent breaking changes, we are keeping instana-nodejs-sensor as an alias for @instana/collector, so you can continue updating your Node.js applications and enjoy the latest Instana Node.js sensor without further changes.

In the future, we might make new use-cases and functionality available only with the new package structure. Please refer to our migration guide for details.

Common Pitfalls

Incorrectly integrating the collector will usually lead to a loss of observability. Your Node.js application will still be shown in Instana but tracing will only work partially. Some calls will be traced but others will be missing.

Important: It is not enough to only have the require statement as the first statement in your application and calling the function exported by require('@instana/collector') later. That is, the following is not supported:

const instana = require('@instana/collector');


instana(); // TOO LATE!

Instead, the function exported by require('@instana/collector') must be called right away, before any other require or import statements. This can either be done in one statement as shown above (note the second pair of parantheses in require('@instana/collector')()) or in two consecutive statements:

// Correct:
const instana = require('@instana/collector');
instana(); // this is fine

// Now all other modules can be required:

The same constraint applies if you are using ES6 module syntax. The following is not supported:

import instana from '@instana/collector';

import { something, else } from 'some-module';
import anotherThing from 'another-module';

instana(); // TOO LATE!

Instead, do this:

import instana from '@instana/collector';
// You need to call the exported function *immediately*, before importing anything else.

// Now all other modules can be imported:
import { something, else } from 'some-module';
import anotherThing from 'another-module';

Updating the @instana/collector Package

We continuously improve the Instana Node.js support and recommend to always use the latest available version of the @instana/collector package to benefit from the these improvements. Updating the package to its latest version everytime you build/roll out your app is a good practice. Updating works just like with any other npm package.

After the initial npm install --save @instana/collector (see above), your package.json will contain a dependency declaration like "@instana/collector": "^1.55.1". The caret (^) denotes a SemVer version range (in this example ^1.55.1 stands for >= 1.55.1 && < 2.0.0). The version ranges dictates the behaviour of the npm install and npm update commands.

Specifiying the version as "@instana/collector": "1.55.1" (without the caret or more generally, without using a version range) would pin that exact version, that is, npm install and npm update would always use version 1.55.1. This is not recommended. Check out the npm docs on version ranges for more details.

  • Executing npm update @instana/collector in your project will install the latest version that matches the version range in your package.json file. It will also update the version range string in package.json. If a lockfile (package-lock.json) is present, it too will be updated accordingly. See the docs for npm update.
  • Executing npm install in your project will also install the latest version that matches the version range in your package.json file, but only if

    1. the node_modules folder does not already contain a version of @instana/collector that matches the version range, and
    2. no package-lock.json file is present that locks the version of the package.

In conclusion, if you build your app on CI and do a fresh npm install every time (you don’t keep the node_modules folder between builds), and if you do not commit package-lock.json to version control, running npm install as a build step is sufficient to get the latest version. In all other cases (keeping node_modules between builds and/or having package-lock.json in version control), it is recommended to run npm update @instana/collector as part of your build.

If you use yarn instead of npm, please refer to the yarn documentation, in particular yarn update for details, but basically the recommendations and procedures are the same.

Supported Libraries

HTTP Since
HTTP(s) servers 1.10.0
HTTP(s) clients 1.10.0
Express error handling & path templates 1.32.0, 1.43.0
Fastify 1.x path templates 1.44.0
koa-router path templates 1.56.0
RPC Since
GRPC 1.63.1
GraphQL 1.69.0
Databases Since
Elasticsearch 1.10.0
MongoDB 1.13.0
Mongoose 1.13.0
MySQL 1.29.0
MySQL 1.37.1
MSSQL 1.47.0
Postgres 1.44.2
Redis 1.31.0
ioredis 1.33.0
Messaging Since
kafka-node 1.20.0
RabbitMQ/amqplib 1.51.0
Logging Since
Bunyan 1.54.0
Pino 1.52.0
Winston 1.53.0
Async Since
Timers 1.10.0
Native Promises 1.10.0
Bluebird Promises 1.35.0

The “Since” column denotes the minimum version of @instana/collector that is required for a given feature. Check the changelog for details.

Metrics Collection

Tracked Configuration Metrics
Runtime Versions GC Activity
Deployed Apps Memory Usage
Name Heap Spaces
Version Event Loop
Description HTTP Servers - Request/Response Times
Arguments Health check status and time of last status change
HTTP Servers Config
Health checks (via admin-plugin-healthcheck)  

Health Signatures

  • Garbage Collection Activity
  • Latency
  • Calls
  • Errors
  • Failing health checks (see Health Check Support below)

Health check support

The Instana Node.js collector will conduct custom health checks and execute them every ten seconds. If the checks fail for at least 30 seconds, an issue will be raised to inform the user.

Health checks are gathered from installed admin-plugin-healthcheck modules.

health check

Health checks listed in the Node.js dashboard.


Issue raised about failing health checks.




To instantiate the Node.js OpenTracing tracer:

const instana = require('@instana/collector');

// Always initialize the collector 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();

See for details.