Node.js Agent version 4.x | APM Node.js Agent Reference [master]

You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.

›

« Release notes Node.js Agent version 3.x »

Node.js Agent version 4.xedit

See the Upgrade to v4.x guide.

4.5.3 - 2024/04/23edit

Bug fixesedit

Fix message handling for tombstone messages in kafkajs instrumentation. (#3985)

4.5.2 - 2024/04/12edit

Bug fixesedit

Fix path resolution for requests that contain invalid characters in its host header. (#3923)
Fix span names for getMore command of mongodb. (#3919)
Fix undici instrumentation to cope with a bug in undici@6.11.0 where request.addHeader() was accidentally removed. (It was re-added in undici@6.11.1.) (#3963)
Update undici instrumentation to avoid possibly adding a second traceparent header to outgoing HTTP requests, because this can break Elasticsearch requests. (#3964)

4.5.0 - 2024/03/13edit

Featuresedit

Update OpenTelemetry bridge support to @opentelemetry/api version 1.8.0.
Update tedious instrumentation to support versions 17 and 18. (#3901, #3911)
Add new kafkajs instrumentation. (#2905)

Bug fixesedit

Fix instrumentation of mongodb to not break mongodb@6.4.0. Mongodb v6.4.0 included changes that resulted in the APM agent’s instrumentation breaking it. (#3897)
Fix hostname detection on Windows in some cases (where a powershell profile could break collection). (#3899)
Fix a path normalization issue that broke (or partially broke) instrumentation of some modules on Windows: Next.js, redis v4+, mongodb. (#3905)

4.4.1 - 2024/02/06edit

Bug fixesedit

Add support for instrumentation of ES module-using (ESM) code with Node.js versions matching ^18.19.0 || >=20.2.0. Before this version of the APM agent, ESM instrumentation was only supported for some earlier Node.js versions. Changes in Node.js’s ESM loader in v18.19.0 and v20 broke earlier ESM support. (#3784, #3844)

4.4.0 - 2024/01/12edit

Known issue: Using the APM agent’s ECMAScript module support with Node.js v18.19.0 is not supported in this version. Upgrade to APM agent version v4.5.0 or later, or use Node.js v18.18.1 or earlier. See https://github.com/elastic/apm-agent-nodejs/issues/3784 for details.

Featuresedit

Support ELASTIC_APM_ACTIVATION_METHOD=K8S_ATTACH (in addition to the current K8S value) to indicate the agent is being started by apm-k8s-attacher. Newer releases of apm-k8s-attacher will be using this value (to have a common value used between APM agents).

Bug fixesedit

Fix bug where NODE_ENV environment value was not used as a default for the environment config setting. The bug was introduced in v4.2.0. (#3807)
Improve Fastify instrumentation to no longer cause the FSTDEP017 and FSTDEP018 deprecation warnings. (#3814)

4.3.0 - 2023/12/05edit

Featuresedit

Add the apmClientHeaders config option, to allow adding custom headers to HTTP requests made to APM server by the APM agent. (#3759)

Bug fixesedit

Fix the dependency version range for @elastic/ecs-pino-format. (#3774)

Choresedit

Skip undici tests for undici >=5.28.0 and NodeJS <14.18.0. (#3755)
Change the log level of Sending error to Elastic APM: ... from info to debug. There is no need to clutter the log output with this message. (#3748)
Explicitly mark this package as being of type="commonjs". The experimental node --experimental-default-type=module ... option added in Node.js v20.10.0 means that a default to "commonjs" isn’t guaranteed.

4.2.0 - 2023/11/23edit

Breaking changesedit

Drop support for next@11. Next.js instrumentation support is currently in technical preview, so it is not considered a semver-major change to drop support for this old version of next. (#3664)

Featuresedit

Add apm.getServiceVersion(), apm.getServiceEnvironment(), and apm.getServiceNodeName(). These are intended for use by ecs-logging-nodejs formatting packages. See https://github.com/elastic/ecs-logging-nodejs/pull/152. (#3195)
Add knex@3 instrumentation. (#3659)
Update OpenTelemetry bridge support to @opentelemetry/api version 1.7.0.

Bug fixesedit

Fix mongodb instrumentation to avoid loosing context when multiple cursors are running concurrently. (#3161)
Set mongodb span’s outcome according to the result of the command being traced. (#3695)
Fix @aws-sdk/client-sqs instrumentation which was failing for SendMessageBatch command when any of the entities does not contain MessageAttributes. (#3746)

4.1.0 - 2023/10/09edit

Featuresedit

Update OpenTelemetry bridge support to @opentelemetry/api version 1.6.0. #3622
Add support for @aws-sdk/client-dynamodb, one of the AWS SDK v3 clients. (#2958)
Add support for @aws-sdk/client-sns, one of the AWS SDK v3 clients. (#2956)
Add support for @aws-sdk/client-sqs, one of the AWS SDK v3 clients. (#2957)
Fixes for some values of the disableInstrumentations config setting. "redis" will now properly disable instrumentation for redis@4. "next" will propertly disable all Next.js instrumentation. (#3658)

Bug fixesedit

Changes to cloud metadata collection for Google Cloud (GCP). Most notably the cloud.project.id field is now the project-id from https://cloud.google.com/compute/docs/metadata/default-metadata-values#project_metadata rather than the numeric-project-id. This matches the value produced by Elastic Beats (like filebeat). #3614

4.0.0 - 2023/09/07edit

See the Upgrade to v4.x guide.

Breaking changesedit

Set the new minimum supported Node.js to version 14.17.0. Users of earlier Node.js versions can use elastic-apm-node v3.x, which supports back to Node.js v8.6.
Ignore a timer option passed to startTransaction() and startSpan() APIs. This option was never documented. It would be surprising if any user is impacted by this.
Remove long deprecated support for the ELASTIC_APM_-prefixed environment variables for the Kubernetes config options. For example, one must use KUBERNETES_POD_NAME and not ELASTIC_APM_KUBERNETES_POD_NAME. (#2661)
The config option filterHttpHeaders is now removed. (#3539)
Remove the deprecated span.toString() and transaction.toString() APIs. See the upgrading doc for details. (#2348)
Remove instrumentation support for the old hapi package — the current @hapi/hapi package is still instrumented. (#2691)
Change apm.startTransaction() api to return a noop transaction instead of null, if the agent is not yet started. (#2429)
Drop support for the obsolete "patch" context manager, i.e. the contextManager: "patch" config option. This was a limited async context management that predated the preferred AsyncLocalStorage core Node.js mechanism for context tracking. It was deprecated in v3.37.0. As well, the related and deprecated asyncHooks config option has been removed. (#3529)
Remove the logUncaughtExceptions config option. See Upgrading to v4 for details. (#2412)
Remove transaction.subtype and transaction.action properties from API. This also impacts apm.startTransaction([name][, type][, options]) and transaction.setType(...), both of which now no longer accept subtype and action parameters. These two properties were deprecated in v3.25.0. (#3557)
Remove support for the erroneous ELASTIC_SANITIZE_FIELD_NAMES and ELASTIC_IGNORE_MESSAGE_QUEUES config environment variables. The correct env vars are ELASTIC_APM_SANITIZE_FIELD_NAMES and ELASTIC_APM_IGNORE_MESSAGE_QUEUES, respectively, and were supported starting in v3.36.0.

Featuresedit

The apm.destroy() method is now async. Almost no users should need to use this method. However, if used, to be sure to wait for APM agent shutdown to be complete, one can now await apm.destroy(). (#3222)
Support instrumenting mongodb v6. (#3596)

Bug fixesedit

Fix instrumentation of mongodb to avoid multiple command handler registrations when client is created via MongoClient.connect static method. (#3586)

Choresedit

Add a warning message when a duration or size config option is provided without units. (#2121)
Change default value of useElasticTraceparentHeader config option to false. This means that for outgoing HTTP requests, the APM agent will no longer add the elastic-apm-traceparent header. This vendor-specific header was used in the past while the W3C trace-context spec was still in development. Now that it is in wide use, the elastic-apm-traceparent header is only useful for interaction with very old Elastic APM agents.
Add default ports into context.service.target.name for HTTP spans conforming to the spec update done in https://github.com/elastic/apm/pull/700 (#3590)

« Release notes Node.js Agent version 3.x »