Upgrade to v2.x
Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability This functionality is generally available and ready for production usage. The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. The Elastic APM Node.js agent enables you to trace the execution of operations in your Node.js applications, sending performance metrics and errors to the Elastic APM Server. Availability This functionality is generally available and ready for production usage. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
Serverless Observability
Generally available
Stack
Generally available
APM Agent Node.js
Generally available
The following is a guide on upgrading your Node.js agent from version 1.x to version 2.x.
Version 2.0.0 of the Node.js agent requires version 6.5 of the APM Server or higher and makes use of the new HTTP intake API.
The new agent supports Node.js 6, 8, and 10+.
The format of the error ID’s have changed from a UUID4 to a hex formatted random 128 bit number. Likewise, the format of the transaction ID’s have changed from a UUID4 to a hex formatted random 64 bit number.
The Node.js agent can be configured using a combination of inline config options, environment variables, and a config file. Many config options also have default values. The order in which these are applied has changed in 2.0.0.
In 1.x the order in which config options overruled each other was (higher overwrites lower):
- Inline options given to
.start() - Agent config file
- Environment variables
- Default values
The new order in 2.0.0 is (higher overwrites lower):
- Environment variables
- Inline options given to
.start() - Agent config file
- Default values
In 1.x, the config option abortedErrorThreshold expected a millisecond value. In 2.0.0 the default time unit is seconds. If you’d like to keep using milliseconds, you need to specify the unit, e.g: 1500ms.
In 1.x, all boolean config options could be configured using the strings on, yes, 1, etc., to mean true with similar values representing false. In 2.0.0 this has been restricted, and only the strings true and false will be interpreted as the boolean equivalent.
The following config options have been removed in version 2.0.0:
| Name | Note |
flushInterval |
Use apiRequestTime instead. Note that this option has a slightly different meaning as the intake API has changed. |
maxQueueSize |
Use apiRequestSize instead. Note that this option has a slightly different meaning as the intake API has changed. |
The agent.addFilter() callback is called with a different payload in 2.0.0 (see docs for details).
While the addFilter() function is still called for all types of data sent to the APM Server, three new filter functions have been added in 2.0.0 as well: agent.addErrorFilter(), agent.addTransactionFilter(), and agent.addSpanFilter(), called only for errors, transactions, and spans respectively.
The previously undocumented method span.offsetTime() has been removed in 2.0.0.
The previously undocumented transaction.buildSpan() method has been replaced with transaction.startSpan(name, type) in 2.0.0.
The agent.buildSpan(name, type) and span.start(name, type) methods have been removed in 2.0.0. They have been replaced by agent.startSpan(name, type).