Node.js

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.

Installation

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:

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.

Configuration

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.

API

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

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

HTTP Since
HTTP(s) servers 1.10.0
HTTP(s) clients 1.10.0
request 1.10.0
request-promise 1.10.0
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
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-node1 2 1.20.0
RabbitMQ/amqplib1 1.51.0
NATS1 2 1.72.0
NATS streaming1 2 1.72.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
Dependencies
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

Issue raised about failing health checks.

Tracing Support

See Also


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

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