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.
To install the Instana Node.js collector and have your Node.js app monitored by Instana, install the npm package
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:
require('@instana/collector')(); // 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.
For information on how to configure the Instana Node.js collector, refer to the configuration page.
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.
The Instana Node.js collector package provides an API for custom tracing and more. See the API page for more information.
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|
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
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).
|Express error handling & path templates||1.32.0, 1.43.0|
|Fastify 1.x path templates||1.44.0|
|hapi path templates||1.68.0|
|koa-router path templates||1.56.0|
|NATS streaming1 2||1.72.0|
The “Since” column denotes the minimum version of
@instana/collector that is required for a given feature. Check the changelog for details.
|Runtime Versions||GC Activity|
|Deployed Apps||Memory Usage|
|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)|
- Garbage Collection Activity
- Failing health checks (see Health Check Support below)
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 checks listed in the Node.js dashboard.
Issue raised about failing health checks.
- Automatic tracing of all requests (after installation of the ‘@instana/collector’ npm package). Please see Supported Libraries and Supported Technologies for more details.
- Optional manual tracing (in addition to automatic tracing) via custom trace SDK.
- Cross host and cross language tracing.
- Supports OpenTracing, see OpenTracing API for more information.
- Node.js Collector Installation
- Node.js Collector Configuration
- Node.js Collector API
- Node.js Collector Github Repository
To capture subsequent calls correctly after consuming/receiving a message with↩
amqplib, NATS or NATS streaming you need to use
span.end(), see ending spans manually.
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-nodeto 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.)