Support information

Edit online

To make sure that the Instana Node.js collector is compatible with your current setup, check the following support information sections.

For more information, see Instana Node.js collector.

For more information about monitoring Node.js applications, see Monitoring Node.js.

Supported processor architectures and operating systems

Edit online

The following table outlines the supported environments for the Node.js collector:

Architecture Operating systems
x86_64 (AMD64) Linux (including Red Hat), macOS, Windows, and FreeBSD
AArch64 (ARM64) Linux (including Red Hat), macOS, Windows, and FreeBSD
IBM Z (s390x) LinuxONE (Linux on IBM Z) and z/OS
IBM Power (ppc64) AIX
IBM Power (ppc64le) pLinux (Linux on Power)
Power ISA (IBM i) IBM i (on Power Systems)
Note: Prebuilt binaries are provided for only mainstream architectures and Long-term support (LTS) versions of Node.js. For more information, see the native add-ons section.

Major Node.js collector versions

Edit online

The major releases of the Instana Node.js collector are as follows:

  • Current major version: Version 4
  • Previous major version: Version 3
Note: For the previous major version, only high severity security and bug fixes are released. Update to the current major version for full support.

For more information, see Node.js collector versioning and Breaking changes in Node.js collector upgrade.

Supported Node.js versions

Edit online

The following table outlines the Node.js versions that the Instana Node.js collector supports:

Node.js versions Collector versions
25.0.0 and later 4.27.0 - latest
24.0.0 and later 4.13.0 - latest
23.0.0 and later 3.21.0 - latest
22.0.0 and later 3.7.0 - latest
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 - 3.21.1
14.0.0 and later 1.97.0 - 3.21.1
12.0.0 and later 1.67.0 - 2.36.1
10.4.0 and later 1.38.0 - 2.36.1
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

Support for Node.js LTS and EOL versions

Edit online

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

When a Node.js version reaches its EOL date, it is offered to receive at least one year of additional support. To avoid potential issues, update your Node.js version regularly.

The following table outlines the EOL Node.js versions that the Node.js collector supports on older major versions. These versions are no longer maintained and do not receive updates.

EOL Node.js versions Supported collector versions
< Node.js 18 @instana/collector@3
< Node.js 14 @instana/collector@2
< Node.js 10 @instana/collector@1

Node.js EOL version warning

Edit online

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

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

If you rely on these versions, update to active versions of Node.js for full support.

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

Node.js collector versioning

Edit online

The Instana npm packages comply with the semver specification.

Note: 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 by using a version range, for example, @instana/collector: ^4.x.y. By pinning the collector version, you automatically receive new features (minor releases) and bug fixes (patch releases). But for a major version update, such as version 3 to 4, you need 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 in Node.js collector upgrade

Edit online
Note: 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 3 to 4

Edit online

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

  • The support for Node.js 14 and 16 is discontinued. You must upgrade to Node.js 18.0.0 or later.

  • The support for Node.js Lambda runtimes v14 and v16 is discontinued.

  • The option to configure the Kafka header format is removed, and headers are now sent in the string format, which eliminates support for the binary format. Remove any references to the environment variable INSTANA_KAFKA_HEADER_FORMAT or the in-code configuration option for tracing: { kafka: { headerFormat: .... }}}. For more information about Kafka migration, see kafka-header-migration phase 2.

  • The support for the X-Instana-Service header is discontinued. To capture the X-Instana-Service header, you must configure it in the Instana agent configuration file configuration.yaml. For more information, see Capturing custom HTTP headers.

  • The environment variables INSTANA_URL and INSTANA_KEY is removed. Replace any references to these with INSTANA_ENDPOINT_URL and INSTANA_AGENT_KEY .

  • The support for disabling AWS SDK instrumentation through aws-sdk/v2/index is dropped; instead, use aws-sdk/v2. For more information, see disabling tracer.

  • The support for the q package is discontinued. For more information, see q .

  • The support for the kafka-avro package is deprecated. For more information, see kafka-avro .

Upgrade from version 2 to 3

Edit online

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 /opt/instana/instrumentation/nodejs/runtime-version-switch internal script is removed from the Instana AutoTrace webhook. If you get the runtime-version-switch module not found error message, see Troubleshooting.

  • The support for the Elasticsearch library is removed.

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

  • The support for the gRPC library is removed.

    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

Edit online

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.