Monitoring Node.js

You can use the Instana Node.js collector to monitor Node.js applications.

Instana Node.js collector

The Instana Node.js collector is an npm package that you add to the dependencies of your Node.js apps. It enables metrics collection and automatic tracing, in addition to reporting metrics and traces to Instana.

Restrictions

The Instana Node.js collector package is for monitoring Node.js server applications with Instana.

For monitoring JavaScript applications that run on the following platforms, see their corresponding page:

Installing the Instana Node.js collector

To install the Instana Node.js collector and enable Instana to monitor your Node.js applications, install the npm package @instana/collector by running the following command:

npm install --save @instana/collector

After the collector is installed, you need to activate it within the application. To activate the collector correctly, load and initialize it before any other files are loaded. To achieve that, add the following line as the first statement to your application code:

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 information, see Installing Node.js collector.

Kubernetes

If your Node.js applications are run exclusively on Kubernetes, you can use the Instana AutoTrace WebHook method instead, which require no modifications to your applications.

If you are using the Instana AutoTrace webhook and plan to use the Instana Node.js SDK, review the using the API together with the AutoTrace WebHook section.

Apigee Microgateway

For more information about how to use the Instana Node.js collector package with Apigee Microgateway (also known as edgemicro), see the Apigee Microgateway page.

Configuring the Node.js collector

For more information on how to configure the Instana Node.js collector, see Node.js collector configuration.

Kubernetes and Red Hat OpenShift

If your Node.js application and the Instana agent run in a Kubernetes cluster, you need to configure network access for monitored applications. For more information, see Kubernetes network access.

Cloud Foundry

Notes:

  • The Instana agent can run on the Diego cells of the Cloud Foundry foundation. Diego's cells are the fundamental units of execution within the Cloud Foundry Diego runtime. They provide the necessary infrastructure for running applications on Cloud Foundry. Each Diego cell is a virtual or physical machine that is responsible for managing and running application instances, including tasks such as scheduling, scaling, and health monitoring. Without an agent that is running on the underpinning Diego cell, monitoring Cloud Foundry applications is not supported.

  • For Tile 1.177.0 and later versions, the instana_buildpack automates the setup of Node.js applications on Cloud Foundry. For more information, see Instana buildpack.

For more information about how to set up Instana host agents and the related Cloud Foundry or Pivotal Platform functions, see Cloud Foundry and Pivotal Platform.

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.

API

The Instana Node.js collector package provides an API for custom tracing. For more information, see API page.

Supported Node.js versions

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

Node.js versions Collector versions
21.0.0 and later 3.0.0 - latest
20.3.0 and later 2.26.0 - latest
18.0.0 and later 2.4.0 - latest
16.0.0 and later 1.125.0 - latest
14.0.0 and later 1.97.0 - latest
12.0.0 and later 1.67.0 - latest
10.4.0 and later 1.38.0 - latest
8.2.1 and later 1.28.0 - 1.x
6.0.0 and later 1.0.0 - 1.x
4.5 and later 1.0.0 - 1.103.0
5.10 and later 1.0.0 - 1.103.0

Major collector versions

  • Current major version: Version 3
  • Previous major version: Version 2

For the previous major version, only high severity security and bug fixes are released. You must switch to the current major version.

Long-term support

Node.js monitoring support of Instana follows the official LTS and end-of-life (EOL) timeline from Node.js.

When a Node.js version reaches its EOL date, it is offered an extra support period that is ranging from one to two years. Update your Node.js version regularly to avoid problems.

The support for Node.js 10 and 12 is discontinued in the @instana/collector@3.x package. If you still prefer to use these Node.js versions, then use the @instana/collector@2 package.

The support for Node.js 6 and 8 is discontinued in the @instana/collector@2.x package. If you still prefer to use these Node.js versions, then use the @instana/collector@1 package.

Versioning

The Instana npm packages comply with the semver specification.

Notes:

  • npm install @instana/collector@latest always installs the latest major version.

  • You can pin the version of the collector in your package.json file, for example by using a version range like @instana/collector: ^3.x.y. That means you automatically receive new features (minor releases) and bug fixes (patch releases), but a major version update, such as version 2 to 3, requires a manual configuration. For more information, see the list of breaking changes.

For more information about the versioning scheme for AWS Fargate and Google Cloud Run container base images, see the respective sections:

Breaking changes

You can also find a detailed list of changes for each version (including breaking changes for major versions) in the GitHub changelog.

Upgrade from version 2 to 3

The support for the following technologies is discontinued. For more information about version 3 breaking changes, see GitHub changelog.

  • The support for Node.js 10 and 12 is discontinued. Upgrade to Node.js 14.0.0 or later.

  • The support for the Elasticsearch library is removed.

    Important: Before you update to version 3, you must migrate to @elastic/elasticsearch.

  • The support for the gRPC library is removed.

    Important: Before you update to version 3, you must migrate to @grpc/grpc-js.

  • The support for node-redis 0 is discontinued. For more information, see node-redis.

  • The support for MSSQL 8 is discontinued. For more information, see node-mssql.

  • The support for GraphQL 14 is discontinued. For more information, see graphql-js.

  • The kafka-node library is officially deprecated.

  • The support for fastify 1 is discontinued.

Upgrade from version 1 to 2

For more information about version 2 breaking changes, see GitHub changelog.

  • The support for Node 6 and 8 is dropped with version 2.0.0 of all Instana npm packages (@instana/collector, @instana/aws-fargate, @instana/aws-lambda, and @instana/google-cloud-run). Upgrade your Node.js version to at least 10.4.0.

  • The support for reportUncaughtException is removed. This feature is deprecated since version 1.112.0. If you used this feature previously, you can rely on the abnormal process termination detection feature instead. Abnormal process termination detection is on by default.

  • The configuration option timeBetweenHealthcheckCalls is moved from instana({ tracing: { timeBetweenHealthcheckCalls: Boolean }}) to instana({ tracing: { metrics: { timeBetweenHealthcheckCalls }}}). For more information, see full configuration reference.

  • The configuration option for logger is removed. You can no longer use instana({logger: logger}). Use instana.setLogger(logger) instead. For more information, see setting the logger after initialization.

  • The configuration option disableAutomaticTracing is removed. You can no longer use instana({ tracing: { disableAutomaticTracing: Boolean }}). Use instana({ tracing: { automaticTracingEnabled: Boolean }}) instead. For more information, see disabling automatic tracing.

Supported libraries

HTTP

The Collector version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Collector version
Express error handling and path templates 1.32.0, 1.43.0
Fastify path templates 1.44.0
HTTP(s) clients 1.10.0
HTTP(s) servers 1.10.0
HTTP/2 clients 1.103.0
HTTP/2 servers 1.103.0
hapi path templates 1.68.0
koa-router path templates 1.56.0
request-promise[1] 1.10.0
request[2] 1.10.0
superagent 1.102.0
fetch v2.15.0
tsoa 1.140.0

RPC

The Collector version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Collector version
Apollo Federation[3] 1.87.0
Apollo Subgraph 3.1.2
JavaScript gRPC 1.5.7
GraphQL 1.69.0

Databases

The Collector version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Collector version
AWS SDK v2 S3 1.115.0
AWS SDK v3 S3 1.129.0
AWS SDK v2 DynamoDB, 1.116.0
AWS SDK v3 DynamoDB, 1.127.0
Elasticsearch Client (@elastic/elasticsearch) 1.96.0
Memcached (memcached) (>= 2.2.2) 1.126.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
Prisma 2.11.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 the specific version of a driver[4]
IBM Db2 2.2.0
Couchbase 2.21.0

Messaging

The Collector version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Collector version
AWS SNS SDK v2[5] [6] 1.136.0
AWS SQS SDK v2[5:1] [6:1] 1.114.0
AWS SQS SDK v3[5:2] [6:2] 1.132.0
AWS SDK v2 Kinesis 1.120.0
AWS SDK v3 Kinesis 2.30.0
AWS SDK v2 Lambda 1.122.0
AWS SDK v3 Lambda 2.34.0
Google Cloud PubSub[5:3] (>= 1.2.0) 1.107.0
NATS streaming[5:4] [7] 1.72.0
NATS[5:5] [7:1] 1.72.0
RabbitMQ/amqplib[5:6] 1.51.0
kafka-node [5:7] [7:2] [8] 1.20.0
kafkajs[5:8] 1.83.0
node-rdkafka[5:9] [7:3] [9] 1.139.0
kafka-avro[5:10] [7:4] 1.139.0
Bull[10] 1.119.0
SQS Consumer 1.119.3

Cloud Services

The Collector version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Since Collector Version
AWS SDK v2 SQS[5:11] [6:3] 1.114.0
AWS SDK v3 SQS[5:12] [6:4] 1.132.0
AWS SDK v2 S3 1.115.0
AWS SDK v3 S3 1.129.0
AWS SDK v2 DynamoDB 1.116.0
AWS SDK v3 DynamoDB 1.127.0
AWS SDK v2 SNS 1.136.0
AWS SDK v2 Kinesis 1.120.0
AWS SDK v3 Kinesis 2.30.0
AWS SDK v2 Lambda 1.122.0
AWS SDK v3 Lambda 2.34.0
Google Cloud Storage 1.105.0
Google Cloud PubSub[5:13] (>= 1.2.0) 1.107.0
SQS Consumer 1.119.3

Logging

The Collector Version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Collector version
Bunyan 1.54.0
express-winston[11] 1.88.0
log4js 1.84.0
Pino 1.52.0
Winston (>= 3.x) 1.53.0
Winston (<= 2.x) 1.88.0

Async

The Collector version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Collector version
async 1.10.0
Bluebird 1.35.0
Native Promises 1.10.0
q 1.10.0
Timers 1.10.0

Other

The column Collector version column indicates the minimum version of the @instana/collector package that is required for a particular feature. For more information, see the GitHub changelog.

Library Collector version Comment
Apigee Microgateway/edgemicro (2.4, 2.5, >= 3.x) 1.89.0 Requires extra installation steps.[12]

OpenTelemetry instrumentations

Instana uses certain OpenTelemetry instrumentations to increase the library coverage.

The Collector version column in the following table indicates the minimum version of the Instana Node.js collector that is required for a feature. For more information, see the GitHub changelog.

Library Since collector version
socket.io 2.24.0
socket.io-client 2.24.0
restify[13] 2.24.0
fs 2.24.0
tedious[14] 3.2.0

If you encounter issues with the OpenTelemetry integration, you can disable it. For more information about how to disable the integration, see Disabling OpenTelemetry integration.

Viewing metrics

To view the metrics, complete the following steps:

  1. From the sidebar of the Instana UI, select Infrastructure.
  2. Click a specific monitored host.

You can see a host dashboard with all the collected metrics and monitored processes.

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 (through admin-plugin-healthcheck)

The dependencies of a Node.js process can also be retrieved from the software versions API endpoint.

Health Signatures

Health check support

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

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

Health check

Health checks are listed in the Node.js dashboard. Then, an issue about failing health checks is raised.

Issue

Node.js EOL version warning

Starting from 1.136.0, the collector sends an issue event when applications are running under an EOL (end of life) version of Node.js.

EOL Node.js versions no longer receive updates, which leaves applications vulnerable to security issues and miss important runtime improvements, like CPU and memory consumption optimization.

Customers relying on these versions are encouraged to update to active versions of Node.js.

Important: Despite the recommendation to use actively maintained runtimes, Instana supports older versions of Node.js.

Tracing support

Instana supports the following tracing:

OpenCensus Instana Trace Exporter

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

For more information, see the OpenCensus Exporters website.

AutoProfile™

This feature is in beta.

AutoProfile™ generates and reports process profiles to Instana automatically and continuously. For more information about profiles, see Analyze profiles.

To enable AutoProfile™, see Node.js collector configuration.

Monitoring issues

Node.js collector not installed

Monitoring issue type: nodejs_collector_not_installed

The Node.js process does not connect with the agent to send traces and metrics due to one of the following reasons:

  1. The @instana/collector package is not 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 that the process is instrumented

If the @instana/collector package is added to your application and correctly activated, you can see following entries in your application logs:

Attempting agent communication via <hostname>:<port>

If you do not see any such message in your application log, the package @instana/collector is probably not installed and initialized correctly. For an overview of the steps to install depending on your application, see installation. For an overview of the pitfalls that you can encounter over time, see the Common pitfalls.

If your Node.js application runs in Kubernetes, try out the Instana AutoTrace WebHook, which automatically and transparently adds the Node.js instrumentation to your pods.

Networking issues

If the Node.js collector is installed, and you see the following message in your application logs, the @instana/collector package cannot communicate with the host agent due to 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 about the required network visibility, see Network requirements for the Instana host agent.

In containerized platforms, network visibility issues occur between the container with the application to be traced and the container of the Instana host agent. Another related issue is when the application container to be traced cannot connect to the Instana agent container on the same host due to some overlay network setup.

Often the problem is that the Node.js collector uses the wrong IP address or DNS name to communicate to the Instana agent. You can instruct the Node.js collector to use a specific network address by using the INSTANA_AGENT_HOST environment variable.

In rare cases, customers set up their networking so that the problem is not the network address, but the port the collector uses.

If 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 by using the INSTANA_AGENT_PORT environment variable.

If none of the preceding solutions help you troubleshoot the issue, open a Support ticket.

Collector initialized too late

Monitoring issue type: nodejs_collector_initialized_too_late

To ensure that tracing works correctly, the package @instana/collector needs to be required and initialized before any other Node.js packages are required. However, the package can heuristically detect that it is initialized too late. If this warning is displayed on your Node.js dashboard, this detection mechanism determines that other packages were loaded before its initialization. For more information, see Installation and Common Pitfalls.

Often, the approach that is outlined in Installation without modifying the source code can also help to resolve this issue in advanced build and deployment scenarios, in particular when you use a bundler (like Webpack) or a transpiler (Babel and TypeScript).

AutoProfile package not available

Monitoring issue type: nodejs_collector_native_addon_autoprofile_missing

You configured the Node.js process to use Instana's AutoProfile feature, but the package @instana/autoprofile might not be loaded. As a result, you do not get profiling information for this Node.js app in Instana. The package @instana/autoprofile is an optional dependency of @instana/collector, and it is automatically installed when possible. But because it is a native add-on, its installation can fail.

One common reason for the installation failure of @instana/autoprofile (in particular for containerized applications) is the absence of necessary operating system packages for building C++ code. This issue occurs when these packages are missing on the target machine or within the target container image.

Another possible root cause is how the container image is built. Node.js packages need to be installed on in the target image. Running npm install or yarn on a build system and then copying the entire node_modules folder to a container image with a potentially different architecture or operating system does not work. This step needs to happen inside the target image.

Finally, if the commands npm install --no-optional or yarn --ignore-optional are used to install dependencies, the package can also be missing.

For more information, see Native add-ons.

Missing calls due to unsupported triggers

Usually, Instana tracers capture only outgoing calls when an active entry span exists. In some edge cases, this rule can lead to calls that you expect to be captured are not captured. For example, when work is triggered by a mechanism that is not supported by Instana automatic instrumentation. The solution for these use cases is to create an entry span through custom tracing by using the Instana Node.js SDK. For more information about the Node.js SDK, see Tracing is inactive when no active entry span exists.