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

Kubernetes

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

Note: 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

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, check the documentation on Kubernetes 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 Collector Versions
20.3.0 and above 2.26.0 - latest
18.0.0 and above 2.4.0 - latest
16.0.0 and above 1.125.0 - latest
14.0.0 and above 1.97.0 - latest
12.0.0 and above 1.67.0 - latest
10.4.0 and above 1.38.0 - latest
8.2.1 and above 1.28.0 - 1.x
6.0.0 and above 1.0.0 - 1.x
4.5 and above 1.0.0 - 1.103.0
5.10 and above 1.0.0 - 1.103.0

Major Collector Versions

  • Current major version: v2
  • Previous major version: v1

Note: For the previous major version only high severity security and bug fixes are released. It is recommended to switch to the current major version as soon as possible.

Long-Term Support

The official LTS & end-of-life (EOL) timeline from Node.js is followed.

As soon as a Node.js version has reached its EOL date, at least one year and at most two years support on top is offered. Update your Node.js version regularly to avoid problems.

Note: Node v6 & v8 support has been dropped in @instana/collector@2.x. Use @instana/collector@1 if you would like to stick with v6 or v8.

Versioning

The semver specification is followed.

Note: Be aware that npm install @instana/collector@latest always installs the latest major version.

Note: The collector version in your package.json should be pinned to e.g. @instana/collector: ^2.x.y. That means you will automatically receive new features (minor releases) and bug fixes (patch releases), but a major version update (e.g. from v1 to v2) requires a manual step. It is always recommend reading through our list of breaking changes.

For details on the versioning scheme for AWS Fargate and Google Cloud Run container base images, see the respective sections:

Breaking Changes

You can find all changes in the Github changelog.

Upgrade from v1 to v2

See v2 breaking changes here.

  • Support for Node v6 and v8 has been 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 v10.4.0.
  • The support for reportUncaughtException has been removed. This (opt-in) feature has been deprecated since version 1.112.0. If you have used this previously, you can rely on the abnormal process termination detection feature instead. Abnormal process termination detection is on by default.
  • The configuration option timeBetweenHealthcheckCalls has moved from instana({ tracing: { timeBetweenHealthcheckCalls: Boolean }}) to instana({ tracing: { metrics: { timeBetweenHealthcheckCalls }}}). For more information, see full configuration reference.
  • The configuration option for logger has been 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 has been 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 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.

Library 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
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.10.0
request 1.10.0
superagent 1.102.0

RPC

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.

Library Since Collector Version
Apollo Federation 1.87.0
gRPC 1.63.1 [^10]
JavaScript gRPC 1.5.7
GraphQL 1.69.0

Note: As of April 2021 the native gRPC library is deprecated. It's recommended to use @grpc/grpc-js.

Databases

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.

Library Since 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 Legacy Client (elasticsearch)) 1.10.0
Elasticsearch Modern 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 driver[1] [^10]
IBM DB2 2.2.0
Couchbase 2.21.0

Messaging

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.

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

Cloud Services

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.

Library Since Collector Version
AWS SDK v2 SQS[2:11] [3:3] 1.114.0
AWS SDK v3 SQS[2:12] [3: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
Google Cloud Storage 1.105.0
Google Cloud PubSub[2:13] (>= 1.2.0) 1.107.0

Logging

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.

Library Since Collector Version
Bunyan 1.54.0
express-winston[7] 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 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.

Library 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

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.

Library Since Collector Version Comment
Apigee Microgateway/edgemicro (2.4, 2.5, >= 3.x) 1.89.0 Requires additional installation steps.[8]

OpenTelemetry instrumentations

Instana uses certain OpenTelemetry instrumentations to increase the library coverage.

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

Library Since collector version
socket.io [^11] 2.24.0
socket.io-client 2.24.0
restify[9] 2.24.0
fs 2.24.0

Note: 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.

[^10] The library is currently incompatible with Node.js v20.

[^11] Read through this section.

Metrics collection

To view the metrics, select Infrastructure in the sidebar of the Instana User interface, click a specific monitored host, and then 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 (via admin-plugin-healthcheck)

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

Health Signatures

  • Garbage Collection Activity
  • Latency
  • Calls
  • Errors
  • Failing health checks (see Health Check Support as follows)

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.

Node.js EOL Version Warning

Starting at version 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

It's important to notice that despite the recommendation to use actively maintained runtimes, Instana supports older versions of Node.js.

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.

Monitoring Issues

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, the package @instana/collector is probably 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.

If your Node.js application runs in Kubernetes, you should 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 (refer to the previous section), and you see the following message in your 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 is that, 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, open a Support Ticket.

Collector Initialized Too Late

Monitoring issue type: nodejs_collector_initialized_too_late

To ensure 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 has been initialized too late. In case this warning is displayed on your Node.js dashboard, this detection mechanism has determined that other packages have been loaded before its initialization. Please refer to the installation documentation and in particular to the Common Pitfalls section for more details on this.

Often, using the approach outlined in Installation Without Modifying the Source Code can also help to resolve this issue in advanced build and deployment scenarios, in particular when using a bundler (like Webpack) or a transpiler (Babel, 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 feature, but the package @instana/autoprofile could not be loaded. As a result, you will 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.

A common reason for this (in particular for containerized applications) is that required operating system packages for building C++ code are missing on the target machine or in the target container image.

Another possible root cause is the way in which 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 will not work; this step needs to happen inside the target image.

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

For more information on the subject, see the section on Native Add-ons.

Missing Calls Due To Unsupported Triggers

As a general rule, Instana tracers only capture outgoing calls when there is an active entry span. In some edge cases, this can lead to calls not being captured that you would expect to be captured; for example when work is triggered by a mechanism that is not supported by our automatic instrumentation. The solution for these use cases is to create an entry span via custom tracing using Instana's Node.js SDK. Refer to this section in the Node.js SDK documentation for more details.

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 AWS SQS, kafkajs, kafka-node, node-rdkafka, kafka-avro, RabbitMQ/amqplib, NATS, NATS streaming, or Google Cloud PubSub, you need to use span.disableAutoEnd() and span.end(). For more information, see ending spans manually. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  3. To support AWS SDK v2 SQS, you need to restore the async context manually when promises with the async or await function are used. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  4. 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.
    • when using node-rdkafka or kafka-avro to produce messages as streams where the objectMode option is not set to true.
    • when using node-rdkafka or kafka-avro to produce messages where the collector's headerFormat option is set to binary, due to an issue in node-rdkafka's header support of Buffer types. Note that the problem will be gone when the fix is approved and landed in the next version of node-rdkafka.
    ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  5. If the option dr_cb is set to true when initializing the Producer, the instrumentation can detect if a message has actually been sent and will only create a corresponding span in that case. If dr_cb is false or unset, the instrumentation will assume that a message has been sent (and create a corresponding span) as soon as the Producer.produce method has terminated. In rare cases, spans might be produced although calling Producer.produce did not actually result in a message being sent. ↩︎

  6. Bull repeatable jobs that are part of a bulk will not be properly instrumented due to not being expected by the API. They are expected to be forbidden in newest versions of Bull ↩︎

  7. Requires express-winston to be configured with statusLevels: true, as Instana only captures log messages of severity warn or higher. ↩︎

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

  9. OpenTelemetry supports restify only up to major version 8. For more information, see this GitHub issue. ↩︎