Instana Node.js Monorepo

Changelog | Contributing | @instana/collector

• Instana npm Packages
• Breaking Changes
• Filing Issues
• Documentation

Instana npm packages

This repository hosts all Instana's Node.js tracer packages.

Traditional server-based environments

• @instana/collector

Serverless environments

• @instana/aws-fargate
• @instana/aws-lambda
• @instana/google-cloud-run
• @instana/azure-container-services

Please use our @instana/serverless-collector for any other serverless environment.

Breaking Changes

The current major release is 4.x.y.

Checkout our breaking changes documentation.

Filing Issues

If something is not working as expected or you have a question, instead of opening an issue in this repository, please open a ticket at https://www.ibm.com/mysupport instead. Please refrain from filing issues or tickets if your audit tool (npm audit, Snyk, etc.) reported a CVE for a dependency or a transitive dependency of @instana/collector -- we run these audits with every build and take appropriate action automatically.

Documentation

The documentation for Instana's Node.js support is available on Node.js page of the Instana documentation portal.

Here are a few more quick links:

• Installation
• Native Addons: Profiling, Garbage Collection and Event Loop Information
• API

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

4.15.0 (2025-05-27)

Features

• added support for redis sentinel (#1737) (2f791c1)
• added support for redis v5 (#1710) (1bd7a14)

4.14.0 (2025-05-13)

Features

• added support for sqs-consumer v12 (#1731) (af01af8)

4.13.0 (2025-05-08)

Features

• added support for node v24 (#1694) (5071bac)

4.12.0 (2025-05-06)

Features

• added support for @apollo/server (#1675) (e136380)
• added support for @elastic/elasticsearch v9 (#1691) (e4d164e)

4.11.1 (2025-04-24)

Note: Version bump only for package @instana/collector

4.11.0 (2025-04-22)

Features

• kafka: added option to disable downstream suppression for ignored endpoints (#1652) (2aa720d)

4.10.0 (2025-04-01)

Features

• added support for express v5 (#1654) (8576291)

4.9.0 (2025-03-20)

Features

• kafka: added support for ignore endpoints (#1616) (c8d8e47)

4.8.0 (2025-03-19)

Note: Version bump only for package @instana/collector

4.7.0 (2025-03-11)

Features

• added INSTANA_IGNORE_ENDPOINTS_PATH for external YAML config (#1605) (58312fa)

4.6.3 (2025-03-05)

Bug Fixes

• resolved calling callback twice in agent connection (#1600) (dfeab1c)
• resolved calling callback twice in agent lookup (e74c150)
• resolved Instana log calls being traced with custom logger setup (#1562) (63aa2a7)

4.6.2 (2025-02-24)

Bug Fixes

• ensure the logger always applies the correct log level (#1565) (90af990), closes #1556

4.6.1 (2025-01-29)

Bug Fixes

• resolved tracing for deferred exit spans in http2 (#1531) (2e5c912)

4.6.0 (2025-01-18)

Bug Fixes

• changed internal logger timestamp to ISO string (#1518) (0a6af07)
• resolved issue in setLogger function with winston logger (#1522) (52f102e)

Features

• added support for graphql-ws v6 (#1516) (1da50b8)

4.5.3 (2025-01-14)

Bug Fixes

• resolved more logging objects structure (#1510) (bd4c9bb)

4.5.2 (2025-01-13)

Bug Fixes

• pino agent stream messages were undefined (9472c5c)
• resolved logging objects being undefined or missing (#1509) (7715fed)

4.5.1 (2025-01-13)

Bug Fixes

• resolved bunyan npm installation warning (#1447) (c4abc75)

4.5.0 (2024-12-16)

Features

• dynamodb: added endpoint filtering (#1484) (93e4023)

4.4.0 (2024-12-12)

Features

• added support for couchbase v4.4.4 (#1466) (fb06bdc)

4.3.0 (2024-12-10)

Features

• added support for mysql2 v3.11.5 (#1467) (45414f5)
• redis: added endpoint filtering (#1448) (2f45ff7)

4.2.0 (2024-11-22)

Note: Version bump only for package @instana/collector

4.1.0 (2024-11-19)

Features

• added support for graphql-subscriptions v3 (#1446) (e4a978c)

4.0.1 (2024-10-28)

Note: Version bump only for package @instana/collector

4.0.0 (2024-10-23)

Bug Fixes

• dropped support for node v14 and v16 (#1348) (aaa9ad4)
• dropped support for x-instana-service header (#1355) (7aa5f4b)
• kafka: enforced string format for Kafka trace headers and dropped binary support (#1296) (2c822d3)
• shared-metrics: replaced fs-extra with fs promises (#1362) (35ec19c)

Features

• added support for root exit spans (#1297) (f1e1f30)

BREAKING CHANGES

• • Migration: Please configure the Instana agent to capture the X-Instana-Service header in the agent's configuration file.

• For details, see: https://www.ibm.com/docs/en/instana-observability/current?topic=applications-services#specify-the-x-instana-service-http-header.

• • Dropped support for Node.js versions 14 and 16.

• Reason: These versions have reached their end of life.

• More info: https://github.com/nodejs/Release?tab=readme-ov-file#end-of-life-releases

• kafka: - Removed the ability to configure the header format; headers will always be sent in 'string' format.

• Removed support for 'binary' format and code related to sending headers in 'binary' or 'both' formats. refs INSTA-809

3.21.0 (2024-10-17)

Features

• added v23 support (#1385) (34b990f)
• sdk: added SpanHandle & NoopSpanHandle types (#1374) (5e762a3)

3.20.2 (2024-10-09)

Bug Fixes

• enhanced typescript support for currentSpan().span (#1370) (762af17)

3.20.1 (2024-10-04)

Bug Fixes

• resolved ts error "instana.currentSpan is not a type" (#1357) (f32b3c1)

3.20.0 (2024-10-01)

Bug Fixes

• connected deferred exit span with original entry span (#1346) (98f99e1), closes #1297

Features

• extended typescript support (#1349) (3b8abea)

3.19.0 (2024-09-25)

Features

• added support for fastify v5 (#1336) (a646a14)

3.18.2 (2024-09-17)

Bug Fixes

• ioredis: repaired cluster functionality (#1334) (ca5bd24), closes #1327

3.18.1 (2024-09-12)

Bug Fixes

• ioredis: reverted multi/pipeline handling from #1292 (#1328) (09fc2f7)

3.18.0 (2024-09-06)

Features

• added support for ioredis cluster (#1292) (0318eac)

3.17.1 (2024-09-03)

Bug Fixes

• resolved mongoose error ".make is not a function" (#1304) (728f7a4)

3.17.0 (2024-09-02)

Features

• added support for tedious v19 (#1295) (6f61f9e)

3.16.0 (2024-08-28)

Features

• added support for redis cluster (#1270) (4d1dc72)
• added support for tedious v18 (#1289) (e2990c1)

3.15.2 (2024-08-27)

Bug Fixes

• deprecated q library (#1282) (d86f939)

3.15.1 (2024-08-19)

Note: Version bump only for package @instana/collector

3.15.0 (2024-08-13)

Bug Fixes

• improved debug logs in agent sending spans (#1259) (55ee69e)

Features

• added support for express v5 beta-3 (#1261) (bf471ed)

3.14.4 (2024-07-22)

Bug Fixes

• core: avoided creating standalone exit spans when using the sdk (#1234) (9a0d8fc)

3.14.3 (2024-07-11)

Note: Version bump only for package @instana/collector

3.14.2 (2024-07-09)

Reverts

• Revert "test: skip the s3 tests due to s3 bucket limit" (622101b)

3.14.1 (2024-06-26)

Note: Version bump only for package @instana/collector

3.14.0 (2024-06-26)

Features

• added native esm support (#1159) (8bfef61)

3.13.0 (2024-06-24)

Features

• couchbase: added support for raw sql queries (#1187) (660795e)

3.12.0 (2024-06-21)

Features

• added support for mssql v11 (#1195) (d9dd2ac)

3.11.0 (2024-06-13)

Note: Version bump only for package @instana/collector

3.10.0 (2024-06-13)

Note: Version bump only for package @instana/collector

3.9.0 (2024-05-28)

Features

• added support for got v12, v13, v14 (#1157) (1333a3c)
• added support for node-fetch v3 (#1160) (b96f30c)

3.8.1 (2024-05-17)

Note: Version bump only for package @instana/collector

3.8.0 (2024-05-06)

Features

• added support for restify v9, v10, v11 (#1140) (fb132d2)

3.7.0 (2024-05-03)

Features

• autoprofile: added prebuilds for darwin/arm64 linux/arm64 linux/arm (#1135) (26f85b0)

3.6.0 (2024-04-29)

Features

• added support for node-rdkafka v3 (#1123) (a519d75)
• added support for pino v9 (#1130) (6a6565c)

3.5.0 (2024-04-24)

Features

• added support for prisma v5 (#1114) (7cf8d90)

3.4.0 (2024-04-16)

Features

• added azure blob instrumentation (#967) (8b3264a)

3.3.1 (2024-04-11)

Bug Fixes

• resolved esm loader issue for manual instrumentation node v18.19.0 and above (#1063) (d69aff8)
• security: resolved security vulnerability in the tar package. (#1106) (d863aa8)

3.3.0 (2024-03-22)

Bug Fixes

• resolved relative URL issue in sanitizeUrl method (a2fac29)

Features

• added support for mongoose v8 (#1083) (3996301)

3.2.1 (2024-03-18)

Bug Fixes

• collector: gracefully shutdown if core module process is not ava… (#1070) (3d8196d)
• matrix parameters included in URLs (#1069) (f1d2862)

3.2.0 (2024-02-27)

Bug Fixes

• depreacted request-promise module (#1017) (6bb88dd)

Features

• added otel instrumentation for tedious (#1030) (87de73d)
• added support for ibm_db v3 (5d1b9fe)

3.1.3 (2024-01-31)

Note: Version bump only for package @instana/collector

3.1.2 (2024-01-29)

Bug Fixes

• deprecated request module (#1004) (8bd41a9)
• deprecated request-promise-native (#1016) (34fa412)

3.1.1 (2024-01-10)

Note: Version bump only for package @instana/collector

3.1.0 (2024-01-04)

Bug Fixes

• updated code formats (#971) (0e24014)

3.0.0 (2023-12-12)

Bug Fixes

• dropped node v10 and v12 (#933) (7e3ee32)

Build System

• deprecated kafka-node (1274419)
• dropped elasticsearch library (e1f480d)
• dropped fastify v1 (fe247b3)
• dropped graphql v14 (c4b3366)
• dropped gRPC library (acbfa27)
• dropped mssql v8 (6c58f51)
• dropped redis v0 (e4db474)

Features

• node-v21: added support for node v21 (#947) (64cc797)

BREAKING CHANGES

• Dropped support for fastify v1.
• Deprecated kafka-node library. Support will be removed in the next major release.
• Dropped support for node-redis v0 (https://github.com/redis/node-redis)
• Dropped support for mssql v8 (https://github.com/tediousjs/node-mssql)
• Dropped support for graphql v14 (https://github.com/graphql/graphql-js)
• Dropped elasticsearch lib support (https://www.npmjs.com/package/elasticsearch)
• Dropped support for gRPC lib (https://www.npmjs.com/package/grpc)
• Dropped Node v10 & v12 support.

2.36.1 (2023-12-04)

Note: Version bump only for package @instana/collector

2.36.0 (2023-11-29)

Bug Fixes

• fetch: fix header handling for native fetch for Node.js >= 20.10.0 (ece1a9a)

Features

• sqs-consumer: added v7 support for sqs-consumer (#941) (5394726)

2.35.0 (2023-11-14)

Bug Fixes

• couchbase: added missing bucket type and name for bucket.query (#922) (fc2a9c0)

Features

• fastify: added support for fastify v4 (#920) (fb22cb7)
• google cloud storage: added support for google cloud storage v7 (#913) (33be8da)

2.34.1 (2023-10-23)

Note: Version bump only for package @instana/collector

2.34.0 (2023-10-10)

Features

• added support for aws sdk v3 lambda (#871) (eb85c91)

Reverts

• Revert "chore: migrated to npm workspaces and lerna v7 (#876)" (763ac7e), closes #876

2.33.1 (2023-09-26)

Note: Version bump only for package @instana/collector

2.33.0 (2023-09-18)

Features

• aws: added support for sns v3 (#860) (bd3e755)

2.32.0 (2023-09-11)

Note: Version bump only for package @instana/collector

2.31.0 (2023-09-04)

Features

• added support for batch write dynamodb (#858) (a276b84)

2.30.2 (2023-08-28)

Bug Fixes

• dynamodb: resolved all operation names (#853) (c7b17eb)

2.30.1 (2023-08-25)

Bug Fixes

• core: resolved missing dynamodb spans (#851) (7444a90)

2.30.0 (2023-08-16)

Features

• aws sdk v3 kinesis instrumentation (#838) (eae677c)

2.29.0 (2023-07-31)

Bug Fixes

• tracing: normalize incoming trace/span IDs from upstream tracers (01e26d1), closes #833

2.28.0 (2023-07-27)

Note: Version bump only for package @instana/collector

2.27.0 (2023-07-24)

Note: Version bump only for package @instana/collector

2.26.3 (2023-07-20)

Note: Version bump only for package @instana/collector

2.26.2 (2023-07-17)

Note: Version bump only for package @instana/collector

2.26.1 (2023-07-10)

Note: Version bump only for package @instana/collector

2.26.0 (2023-07-04)

Features

• added support for Node v20 (ESM not working yet) (#805) (830259f)

2.25.3 (2023-06-27)

Note: Version bump only for package @instana/collector

2.25.2 (2023-06-22)

Bug Fixes

• sdk: do not overwrite span.ec after it has been set via the SDK (4283cdf)

2.25.1 (2023-06-19)

Note: Version bump only for package @instana/collector

2.25.0 (2023-06-16)

Features

• sdk: add method to mark the current span as erroneous (2cfcc7b)

2.24.0 (2023-06-13)

Bug Fixes

• announce: verify connection to Instana host agent via payload check (ae1b41c)

Features

• collector: added node:fs, restify and socket.io support (OpenTelemetry integration) (#715) (60f3bb9), closes #109122

2.23.0 (2023-06-06)

Note: Version bump only for package @instana/collector

2.22.1 (2023-05-15)

Bug Fixes

• db2: ensure span is correctly processed as an IBM DB2 span (de3a8b4)
• sqs: fix missing async context in recent aws-sdk/client-sqs version (6ae90e7)

2.22.0 (2023-05-09)

Bug Fixes

• announce: remove obsolete check for Server header (7d6a05b)
• collector: keep EOL events open instead of recreating them (6de9965)

Features

• mongodb: add support for mongodb v4, v5 & mongoose v6 & v7 (4e80a26)
• w3c: support W3C trace context level 2 (62e0f99)

2.21.1 (2023-05-02)

Bug Fixes

• announce: fix timeout for host agent lookup (d4e440f)
• db2: capture the correct destination dsn per client (9529690)
• elasticsearch: capture the correct destination host per client (cc23d05)
• nats: capture the correct destination nats address per client (59e5ddf)
• nats-streaming: capture correct destination address per client (678d702)

2.21.0 (2023-04-21)

Features

• collector: added support for couchbase (#737) (3239b19)

2.20.2 (2023-04-06)

Note: Version bump only for package @instana/collector

2.20.1 (2023-03-30)

Bug Fixes

• amqp: publish span not being transmitted when confirm cb is missing (#745) (6dce419)

2.20.0 (2023-03-24)

Features

• collector: added support for amqplib 0.10.x (b56a827)

2.19.0 (2023-03-17)

Features

• collector: added support for @google-cloud/storage@6 (#727) (efcd4f1)

2.18.1 (2023-03-06)

Bug Fixes

• grpc-js: capture the correct destination host per grpc-js client (5bc3188)
• grpc-js: do not mark cancelled calls as erroneous (fea8b80)

2.18.0 (2023-02-28)

Features

• collector: added support for @elastic/elasticsearch v8 (#707) (dae00bb)
• tracing: improve robustness of custom service naming (aadcbff)

2.17.0 (2023-02-20)

Features

• collector: added support for nats 2.x including trace correlation (#702) (86a2685)

2.16.0 (2023-02-13)

Features

• collector: added support for sqs-consumer@6.2.0 (#691) (f8bf9e7)

2.15.0 (2023-01-27)

Features

• tracing, fetch: instrument native fetch (1a48168)

2.14.2 (2023-01-16)

Note: Version bump only for package @instana/collector

2.14.1 (2023-01-12)

Note: Version bump only for package @instana/collector

2.14.0 (2023-01-02)

Features

• collector: tracing all spans when client app is using ES modules (#672) (7d471ff)

2.13.2 (2022-12-14)

Note: Version bump only for package @instana/collector

2.13.1 (2022-12-12)

Note: Version bump only for package @instana/collector

2.13.0 (2022-12-07)

Bug Fixes

• collector: improved capturing object logging via bunyan (#664) (d0f16d1)

2.12.0 (2022-11-22)

Note: Version bump only for package @instana/collector

2.11.1 (2022-11-09)

Note: Version bump only for package @instana/collector

2.11.0 (2022-11-04)

Features

• tracing: instrument prisma (ORM) (ec760f7)

2.10.0 (2022-10-06)

Features

• collector: added support for redis v4 (#627) (ad00255)
• kafka: use kafka header format 'both' by default (b2585cf)

2.9.0 (2022-09-26)

Note: Version bump only for package @instana/collector

2.8.1 (2022-09-21)

Note: Version bump only for package @instana/collector

2.8.0 (2022-09-20)

Features

• dynamodb: capture region as annotation (4ba64f4)

2.7.1 (2022-09-05)

Bug Fixes

• sqs, sns: do not add message attributes if that would violate limit (23c8ca1)

2.7.0 (2022-08-31)

Features

• aws-lambda: added support for arm64 architecture (#605) (03dd47a), closes #596

2.6.2 (2022-08-17)

Note: Version bump only for package @instana/collector

2.6.1 (2022-08-09)

Note: Version bump only for package @instana/collector

2.6.0 (2022-06-28)

Note: Version bump only for package @instana/collector

2.5.0 (2022-06-23)

Features

• core: added ability to complete specific intermediate spans (#564) (480ee46), closes #561
• sdk: add methods to set the EUM correlation ID/type on the span (727916c)

2.4.0 (2022-05-25)

Features

• added node 18 support (#529) (b355a7c)

2.3.0 (2022-05-24)

Bug Fixes

• http: only capture response status/headers when they have been sent (850b8e4), closes #548
• rdkafka: use long trace IDs with new Kafka message headers (9c47349)

Features

• kafkajs: remove Instana headers on arrival (f65bc75)

2.2.0 (2022-05-18)

Bug Fixes

• agent: reduce log level for sending data from debug to trace (8b57a71)

Features

• agent: read span batching option also from tracing section (1f776d4)
• tracing: added instrumentation for ibm db2 (#532) (0d0b1e0)

2.1.0 (2022-04-28)

Bug Fixes

• tracing: cancel sqs entry span sync when no messages are available (8a66277)
• fix duplicated logger names and prevent them (9d576c5)

Features

• tracing: use new common tracing config from from agent response (7f8825f)

2.0.0 (2022-04-04)

Bug Fixes

• dropped Node 6/8 (0e6fd0e)
• remove npm package instana-nodejs-sensor (5fb9f18)
• removed disableAutomaticTracing legacy config (#432) (922d168)
• removed legacy support for config.timeBetweenHealthcheckCalls (#476) (66eff69)
• removed support for passing parent logger during initialisation (bd96791)
• removed uncaught exception config (fb6570a)
• self-disable if detected Node.js runtime version is too old (cfe4248)

BREAKING CHANGES

• Removed support for legacy config instana({ timeBetweenHealthcheckCalls: ... }). Use instana({ metrics: { timeBetweenHealthcheckCalls: ...}}).
• Starting with version 2.0.0, consumers of the package who still use the deprecated package name instana-nodejs-sensor will need to follow https://www.ibm.com/docs/en/obi/current?topic=nodejs-collector-installation#change-of-package-name to receive updates in the future.
• Removed "disableAutomaticTracing" config option. Use instana({ automaticTracingEnabled: Boolean }).
• Removed "reportUncaughtException" config option. The feature was completely removed.
• Removed support for passing logger to instana initialisation. Use instana.setLogger(logger)".
• v2 has dropped support for Node 6/8.

1.140.1 (2022-04-04)

Bug Fixes

• metrics: do not report metrics from worker threads (#517) (bdf7869), closes #500

1.140.0 (2022-03-24)

Bug Fixes

• collector: fix export returned from init (3cc709c)
• collector: work around Bazel's node-patches module (d06e9be)

Features

• collector: added instrumentation for @grpc/grpc-js (d12e386), closes #87653
• tracing: added instrumentation for node-rdfafka/kafka-avro (7cb7aa4)

Reverts

• Revert "test: added tsoa framework to integration tests (#492)" (479a3f6), closes #492

1.139.0 (2022-03-09)

Bug Fixes

• collector: fix export returned from init (3cc709c)

Features

• tracing: added instrumentation for node-rdfafka/kafka-avro (7cb7aa4)

1.138.0 (2022-02-08)

Bug Fixes

• tracing: fix version constraint for http2 instrumentation (50f380f), closes /github.com/nodejs/node/blob/master/doc/changelogs/CHANGELOG_V8.md#8 /github.com/nodejs/node/blob/master/doc/changelogs/CHANGELOG_V8.md#8

1.137.5 (2022-01-25)

Note: Version bump only for package @instana/collector

1.137.4 (2022-01-11)

Note: Version bump only for package @instana/collector

1.137.3 (2021-12-16)

Bug Fixes

• tracing: fix context loss when cls-hooked#bindEmitter is used (2743047), closes #438

1.137.2 (2021-11-30)

Bug Fixes

• collector: prevent initializing @instana/collector multiple times (b3261b7)

1.137.1 (2021-11-23)

Bug Fixes

• dependency: pinned semver to 7.3.3 (d32f23e)
• dependency: updated tar to 6.x in shared-metrics (#415) (5288ba5)