The Instana Node.js Collector

The Instana Node.js collector is an npm package that you add to the dependencies of your Node.js apps to enable metrics collection and automatic tracing, as well as reporting metrics and traces to Instana.

Server Only

This package is for monitoring Node.js server applications with Instana. If you want to monitor JavaScript applications running in a browser, check out our docs on website monitoring.


To install the Instana Node.js collector and have your Node.js app monitored by Instana, install the npm package @instana/collector 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:


// All other require statements must be done after the collector is initialized.
// Note the () after the require statement of the collector which initializes it.

// const express = require('express');

For more in-depth information, refer to the installation page.

Apigee Microgateway

Please refer to the Apigee Microgateway page for information on how to use the Instana Node.js collector package with Apigee Microgateway (also known as edgemicro).


For information on how to configure the Instana Node.js collector, refer to the configuration page.

Kubernetes & OpenShift

If your Node.js application and the Instana agent run in a Kubernetes cluster, please check the documentation on Kubernets network access for information about the required configuration in this setup.

Cloud Foundry

Note: This section assumes that the Instana agent is currently running on the Diego cells of the Cloud Foundry foundation. Without an agent running on the underpinning Diego cell, monitoring Cloud Foundry applications is not supported.

For information on how to setup Instana agents and the related Cloud Foundry or Pivotal Platform functionality, see our Cloud Foundry and Pivotal Platform documentation.

On Cloud Foundry, a configuration is not required at the level of cf push and the application manifest. The only necessary step is to add the @instana/collector package to the Cloud Foundry Node.js application as described above.


The Instana Node.js collector package provides an API for custom tracing and more. See the API page for more information.

Supported Node.js Versions

The Instana Node.js collector supports the following Node.js versions:

Node.js Version Supported Since Collector 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
13.0.0 and above Yes 1.78.0

This means that the collector supports Node.js 4.x beginning with version 4.5.0, but not versions 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; but releases 10.0.0 - 10.3.x are not supported. These constraints mostly relate to automatic tracing. Metrics collection and manual tracing (via the SDK or OpenTracing) is supported in Node.js version 4.0.0 and higher.

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.

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).

Supported Libraries

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

HTTP Since Collector Version
Express error handling & path templates 1.32.0, 1.43.0
Fastify 1.x path templates 1.44.0
HTTP(s) clients 1.10.0
HTTP(s) servers 1.10.0
hapi path templates 1.68.0
koa-router path templates 1.56.0
request-promise 1.10.0
request 1.10.0
RPC Since Collector Version
Apollo Federation 1.87.0
GRPC 1.63.1
GraphQL 1.69.0
Databases Since Collector Version
Elasticsearch (elasticsearch)) 1.10.0
MongoDB (mongodb) 1.13.0
Mongoose (mongoose) 1.13.0
MySQL (mysql) 1.29.0
MySQL (mysql2) 1.37.1
MSSQL (mssql) 1.47.0
Postgres (pg) 1.44.2
Postgres (pg-native) 1.86.0
Redis (redis) 1.31.0
Redis (ioredis) 1.33.0
Sequelize depends on driver1
Messaging Since Collector Version
NATS streaming2 3 1.72.0
NATS2 3 1.72.0
RabbitMQ/amqplib2 1.51.0
kafka-node2 3 1.20.0
kafkajs2 1.83.0
Logging Since Collector Version
Bunyan 1.54.0
express-winston4 1.88.0
log4js 1.84.0
Pino 1.52.0
Winston (>= 3.x) 1.53.0
Winston (<= 2.x) 1.88.0
Async Since Collector Version
Bluebird 1.35.0
Native Promises 1.10.0
Timers 1.10.0
Other Since Collector Version Comment
Apigee Microgateway/edgemicro (2.4, 2.5, >= 3.x) 1.89.0 Requires additional installation steps.5

The column labeled “Since Collector Version” denotes the minimum version of @instana/collector that is required for a given feature. Please 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.

Tracing Support

See Also

  1. Instana does not instrument Sequelize directly, but rather the underlying database drivers. Visibilty into what sequelize does thus depends on the database library you are using together with Sequelize (mysql, mysql2, mssql, pg, ´pg-native`, etc.).

  2. To capture subsequent calls correctly after consuming/receiving a message with kafkajs, kafka-node, RabbitMQ/amqplib, NATS or NATS streaming you need to use span.disableAutoEnd() and span.end(), see ending spans manually.

  3. Trace continuity is not supported

    • for NATS (because NATS has no message headers, see NATS tracing docs),
    • for NATS streaming (because NATS streaming has no message headers, see NATS tracing docs), and
    • when using the npm package kafka-node to send or consume messages, because that package does not support Kafka record headers: See kafka-node#763 and kafka-node#1309). Trace continuity is supported for Kafka in general starting with Kafka version 0.11 for other runtimes and also when using the package kafkajs. We therefore strongly recommend to use kafkajs instead of kafka-node when using Kafka as well as Instana in your Node.js application.
  4. Requires express-winston to be configured with statusLevels: true, as Instana only captures log messages of severity warn or higher.

  5. Using Apigee Microgateway/edgemicro with @instana/collector requires additional installation steps. Please refer to the installation instructions for this use case.