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.

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

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.

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. Additionally, since the Tile version 1.177.0, the instana_buildpack automates the setup of Node.js applications on Cloud Foundry. For more information, refer to the Instana Buildpack documentation.

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.

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
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/[email protected].

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 Legacy Client (elasticsearch)) 1.10.0
Elasticsearch Modern Client (@elastic/elasticsearch)) 1.96.0
MongoDB (mongodb) (>= 2.2) 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
async 1.10.0
Bluebird 1.35.0
Native Promises 1.10.0
q 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
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

OpenCensus Instana Trace Exporter

Instana provides an OpenCensus Trace Exporter for applications written in Node.js. Using the Instana agent processes as proxy, Instana forwards traces that are exported by applications instrumented with Census to its backend.

For more information, see the OpenCensus Exporters website.

AutoProfile™

Note: This feature is currently in beta-testing.

AutoProfile™ generates and reports process profiles to Instana automatically and continuously. Learn more about profiles in Analyze Profiles section.

To enable AutoProfile™, see Node.js Collector Configuration.

Troubleshooting

Node.js Collector not installed

Monitoring issue type: nodejs_collector_not_installed

The Node.js process has not connected with the agent to send traces and metrics. This may be due to one of the following reasons:

  1. The @instana/collector package has not been installed correctly in the Node.js application.
  2. The Node.js process cannot report to the host agent on the same host due to network connectivity issues

Verify the process is instrumented

If the @instana/collector package has been added to your application and correctly activated, you will see entries like the following in your application logs:

Attempting agent communication via <hostname>:<port>

If you do not see any such message in your application log, probably the @instana/collector is not installed and initialized correctly. The installation documentation provides an overview of the steps to perform depending on your application, and the Common Pitfalls documentation provides an overview of the gotchas we have seen over time.

Networking issues

If the Node.js collector is installed (refer to the previous section), and you see the following application logs, the @instana/collector package cannot communicate with the host agent, and it is likely a networking issue:

Announce attempt failed: <error>. Will retry in <seconds>s.

Verify that the Node.js process can connect to the host agent on the same host on port 42699. For more information on the required network visibility, refer to the Network requirements documentation for the Instana host agent.

What we see increasingly often, is that in containerized platforms either there are network visibility issues between the container with the application to be traced and the container of the Instana host agent; another issue of the same kind, due to some overlay network setup, the container of the application to be traced does not connect to the Instana agent container on the same host.

Often the problem is that the Node.js collector is using the wrong ip address or DNS name to talk to the Instana agent. You can instruct the Node.js collector to user a specific network address via the INSTANA_AGENT_HOST environment-variable.

In very few cases, we have seen customers that set up their networking so that the problem was not the network address, but the port the collector uses. In case you need a port remapping, because the host agent does not listen on port 42699 but something else, you can instruct the collector to use a different port via the INSTANA_AGENT_PORT environment variable.

In case none of the above helps you troubleshoot the issue, please open a Support Ticket.

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.