| title | tags | metaDescription | redirects | freshnessValidatedDate | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Update the Node.js agent |
|
How to update your APM Node.js agent, and notes on EOL support for early agent versions. |
|
never |
To take full advantage of New Relic's latest features, enhancements, and important security patches, we recommend you update your Node.js agent to the latest version. For additional information about specific agent updates, refer to the Node.js agent release notes. The release notes include a download link when applicable, plus instructions to download and install the latest version.
- If the
newrelicmodule is listed in yourpackage.json, runnpm install. - If you want to target just the
newrelicmodule, runnpm update newrelic.
Recommendation: Test your updated version before moving it into production. If you have problems, follow the Node.js agent troubleshooting procedures.
Before upgrading to Node.js version 11, review this information for major changes.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
<td/>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Dropped Node.js 14 support.
</td>
<td>
* For further information see our [support policy](/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent).
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Updated ESM loader to support Node.js 20.
</td>
<td>
* You must now use both the `--experimental-loader` and `-r` args when running an application.
* `node --experimental-loader newrelic/esm-loader.mjs -r newrelic path/to/app.js`
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Updated the default context manager to be AsyncLocalContextManager.
</td>
<td>
* The previous default LegacyContextManager can be restored by setting the feature flag of `config.feature_flag.legacy_context_manager` to `true`.
* If you prefer environment variables you can set `NEW_RELIC_FEATURE_FLAG_LEGACY_CONTEXT_MANAGER` to `true`.
* Please note this context manager will be removed in future versions. If you find you must revert to using this legacy context manager, please raise this with [New Relic Support](https://support.newrelic.com/s/) or a [GitHub issue](https://github.com/newrelic/node-newrelic/issues/new?assignees=&labels=bug%2C+needs-triage&projects=&template=bug_report.md&title=).
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Renamed `shim.handleCATHeaders` to `shim.handleMqTracingHeaders`.
</td>
<td/>
</tr>
<tr>
<td>
Update New Relic dependencies to versions with updated Node.js version support
</td>
<td>
* @newrelic/aws-sdk v7.0.0
* @newrelic/koa v8.0.0
* @newrelic/native-metrics v10.0.0
* @newrelic/superagent v7.0.0
* @newrelic/test-utilities v8.0.0
</td>
</tr>
| **Major changes with Node.js agent v11** |
|---|
| Added official parity support for Node.js 20. |
Node.js 16 is the earliest version supported by the New Relic Node.js v11 agent. Node.js 14 and 15 are not supported by v11. Customers running Node.js 15 and earlier have two options:
- Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v11 agent's new features.
- Remain on New Relic Node.js v10 agent without the ability to use new features only available with update agent versions.
Before upgrading to Node.js version 10, review this information for major changes.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
<td>
* This has been a limitation of the agent from the beginning.
* If you used the api to instrument api.instrument, api.instrumentDatastore, api.instrumentWebframework, api.instrumentMessages, or api.instrumentConglomerate, it would override existing instrumentation hooks.
* The effect was that the Node.js agent would not function as designed.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Updated the default of `config.transaction_tracer.record_sql` from off to obfuscated. This means that sql statements will be captured but obfuscated.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Route (URL) parameters are now stored as `request.parameters.route.*` attributes on Transactions, root Segments and Spans.
</td>
<td>
* Query parameters will be available as attributes prefixed with request.parameters.\* on Transactions and Spans.
* Route parameters will be available as attributes prefixed with request.parameters.route.\* on Transactions and Spans.
* Route parameters (aka url parameters) are a common feature of various web frameworks, where you can create a placeholder as part of an API route definition.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Removed captureUrlParams from WebFrameworkShim class.
</td>
</tr>
<tr>
<td>
<DNT>**DEPRECATION NOTICE**</DNT>: shim.unwrap and shim.unwrapOnce will no longer function if you attempt to unwrap an item that has been wrapped multiple times.
</td>
<td>
* This is because since we now allow instrumenting the same module more than once, you cannot safely unwrap without breaking all registered instrumentation. We plan to remove shim.unwrap and shim.unwrapOnce in the next major release.
</td>
</tr>
<tr>
<td>
Update New Relic dependencies to versions with updated Node.js version support
</td>
<td>
* @newrelic/aws-sdk v7.0.0
* @newrelic/koa v8.0.0
* @newrelic/native-metrics v10.0.0
* @newrelic/superagent v7.0.0
* @newrelic/test-utilities v8.0.0
</td>
</tr>
| **Major changes with Node.js agent v11** |
|---|
| * Added the ability to register instrumentation multiple hooks (onRequire, onResolved) for the same resolved moduleName. |
Node.js 14 is the earliest version supported by the New Relic Node.js v10 agent. Node.js 12 and 13 are not supported by v10. Customers running Node.js 13 and earlier have two options:
- Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v10 agent's new features.
- Remain on New Relic Node.js v8 agent without the ability to use new features only available with update agent versions.
Before upgrading to Node.js version 9, review this information for major changes.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
<td/>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Dropped Node.js 12 support.
</td>
<td>
* For further information see our [support policy](/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent).
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: The agent no longer includes the New Relic certificate bundle automatically when using the 'certificates' configuration (commonly with proxies).
</td>
<td>
* The agent no longer includes the New Relic certificate bundle when using the 'certificates' configuration (commonly with proxies). If you find this breaking your current environment, we recommend getting a CA bundle such as the one from Mozilla.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: The agent now excludes port when making external HTTPS requests to port 443 to be in compliance with the spec and other agents
</td>
<td>
* Previous external segments would be named `External/example.com:443` when using default HTTPS port.
* The external segment will now be named `External/example.com`.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Removed ability to disable async hooks based promise context tracking via the `await_support` feature flag. This also removes the legacy Promise instrumentation.
</td>
<td>
* Released the `await_support` feature flag. The agent now relies on async_hooks to track async promise propagation. The net result is the if you had `feature_flag.await_support` set to false, the legacy instrumentation tracked every function in a promise chain as a separate segment.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Removed instrumentation for the obsolete [oracle](https://www.npmjs.com/package/oracle) npm package.
</td>
<td/>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Updated the minimum version of `pg` to be 8.2.x. This is the earliest support version that runs on Node.js 14+.
</td>
<td/>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Updated the minimum supported version of hapi to be v20.0.0.
</td>
<td>
* All versions lower than v20.0.0 are deprecated by hapi for security reasons. See [their support policy](https://hapi.dev/policies/support/).
</td>
</tr>
<tr>
<td>
Update New Relic dependencies to versions with updated Node.js version support
</td>
<td>
* @newrelic/aws-sdk v5.0.0
* @newrelic/koa v7.0.0
* @newrelic/native-metrics v9.0.0
* @newrelic/superagent v6.0.0
* @newrelic/test-utilities v7.0.0
</td>
</tr>
| **Major changes with Node.js agent v9** |
|---|
| Added official parity support for Node.js 18. |
Node.js 14 is the earliest version supported by the New Relic Node.js v9 agent. Node.js 12 and 13 are not supported by v9. Customers running Node.js 13 and earlier have two options:
- Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v9 agent's new features.
- Remain on New Relic Node.js v8 agent without the ability to use new features only available with update agent versions.
Before upgrading to Node.js version 8, review this information for major changes.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
<td/>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Dropped Node.js v10.x support.
</td>
<td>
* For further information see our [support policy](/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent).
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: Removed `serverless_mode` as a feature flag.
</td>
<td>
* The standard `serverless_mode` configuration still exists.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT>: The agent no-longer includes the New Relic certificate bundle automatically when using the 'certificates' configuration (commonly with proxies).
</td>
<td>
* If you find this breaking your current environment, you may leverage a feature-flag to temporarily restore this functionality. Example configuration: `feature_flag: { certificate_bundle: true }`. In this case, we recommend getting a certificate bundle for your environment such as the one from Mozilla. The New Relic bundle and feature flag will be fully removed in next major release.
* Defaulted config.feature_flags.certificate_bundle to false.
</td>
</tr>
<tr>
<td>
Update New Relic Dependencies to versions with updated Node.js version support
</td>
<td>
* @newrelic/aws-sdk v4.0.1
* @newrelic/koa v6.0.1
* @newrelic/native-metrics v7.0.1
* @newrelic/superagent v5.0.1
* @newrelic/test-utilities v6.0.0
</td>
</tr>
| **Major changes with Node.js agent v8** |
|---|
| Added official parity support for Node.js 16. |
Node.js v12 is the earliest version supported by the New Relic Node.js v8 agent. Node.js 10 and 11 are not supported by v8. Customers running Node.js 11 and earlier have two options:
- Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v8 agent's new features.
- Remain on New Relic Node.js v7 agent without the ability to use new features only available with update agent versions.
Before upgrading to Node.js version 7, review this information for major changes.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
<td>
* <DNT>**v6.4.2-v6.14.0:**</DNT> Starting in agent v6.4.2, these attributes were marked as deprecated but left in to give a transition period for the new attributes.
* <DNT>**v7:**</DNT> When http response attribute reporting is enabled, `http.statusCode` and `http.statusText` will be reported.
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT> Removed deprecated `setIgnoreTransaction` API method
</td>
<td>
* <DNT>**v5 - v6:**</DNT> Starting in agent v5.0.0, this method was marked as deprecated but left in to give a transition period for the new methods.
* <DNT>**v7:**</DNT> Applications must use the API method [`transactionHandle.ignore()`](https://newrelic.github.io/node-newrelic/TransactionHandle.html#ignore).
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT> Removed the `api.custom_parameters_enabled` configuration item and associated environment variable `NEW_RELIC_API_CUSTOM_PARAMETERS`.
</td>
<td>
* To enable [`newrelic.addCustomAttribute`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttribute) and [`newrelic.addCustomAttributes`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttributes), applications must use the configuration [`api.custom_attributes_enabled` or the associated environment variable `NEW_RELIC_API_CUSTOM_ATTRIBUTES`](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration/#custom-attributes).
</td>
</tr>
<tr>
<td>
<DNT>**BREAKING**</DNT> Removed deprecated Distributed Tracing API methods, `createDistributedTracePayload()` and `acceptDistributedTracePayload()`
</td>
<td>
* <DNT>**v6.4.0-v6.14.0:**</DNT> Starting in agent v6.4.0, these method were marked as deprecated but left in to give a transition period for the new methods.
* <DNT>**v7:**</DNT> Applications must use the API methods [`transactionHandle.insertDistributedTraceHeaders(headers)`](https://newrelic.github.io/node-newrelic/TransactionHandle.html#insertDistributedTraceHeaders) and [`transactionHandle.acceptDistributedTraceHeaders(transportType, headers)
`](https://newrelic.github.io/node-newrelic/TransactionHandle.html#acceptDistributedTraceHeaders). With these methods, the Node.js agent will now accept W3C's `traceparent` and `tracestate` headers when calling `transactionHandle.acceptDistributedTraceHeaders(headers)` and include the W3C headers along with the New Relic distributed tracing header when calling `transactionHandle.insertDistributedTraceHeaders(headers)`, unless the New Relic trace header format is disabled using [`distributed_tracing.exclude_newrelic_header:true`.](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration/#dt-exclude-newrelic-header)
</td>
</tr>
<tr>
<td>
Update New Relic Dependencies to versions with updated Node.js version support
</td>
<td>
* @newrelic/aws-sdk v3.0.0
* @newrelic/koa v5.0.0
* @newrelic/native-metrics v6.0.0
* @newrelic/superagent v4.0.0
* @newrelic/test-utilities v5.0.0
</td>
</tr>
| **Major changes with Node.js agent v7** |
|---|
| **BREAKING** Removed deprecated `httpResponseCode`, `response.status` and `httpResponseMessage` http response attributes |
Node.js v10 is the earliest version supported by the New Relic Node.js v7 agent. Node.js 8 and 9 are not supported by v7. Customers running Node.js 9 and earlier have two options:
- Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v7 agent's new features.
- Remain on New Relic Node.js v6 agent without the ability to use new features only available with update agent versions.
Node.js 10 does not receive updates. Upgrade to a newer version of Node.js as soon as possible. Support for Node.js 10 has been discontinued with the New Relic Node.js agent v8.
Before upgrading to Node.js agent version 6, review this information for major changes.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
<td>
* <DNT>**v6:**</DNT> Added support for @koa/router up to v8.0.2. @koa/router v8.0.3 and greater are currently unsupported.
* <DNT>**v6:**</DNT> Added support for Node.js v12 and removed support for Node.js v6, 7, and 9. The minimum supported version is Node.js v8.
* Also see New Relic's [Koa Release Notes on Github.](https://github.com/newrelic/node-newrelic-koa/blob/master/NEWS.md).
</td>
</tr>
<tr>
<td>
Removed deprecated `max_samples_per_minute` configuration parameter, which is replaced by `max_samples_stored` behavior
</td>
<td>
* <DNT>**v1 - v5:**</DNT> `max_samples_per_minute` defined the maximum number of events the agent collects per minute. If your application previously used `max_samples_per_minute` as an upper bound, you may need to lower the threshold to a valid maximum to avoid data being dropped on the server. We recommend less than 10k.
* <DNT>**v5:**</DNT> In agent v5 and lower, `max_samples_stored` defined the maximum number of events the agent stores if it's unable to communicate with the [New Relic collector](/docs/accounts-partnerships/education/getting-started-new-relic/glossary#collector).
* <DNT>**v6:**</DNT> The new behavior of `max_samples_stored` defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling. This usage of the configuration is consistent with the other APM agents.
* <DNT>**Troubleshooting tips:**</DNT> If you're missing event data, increase the value of `max_samples_stored` or revert to the default value. The value of `max_samples_stored` should not be over 10,000.
</td>
</tr>
| **Major changes with Node.js agent v6** |
|---|
| Upgraded official Koa framework instrumentation module to v3.0.0 |
Node.js 8 is the earliest version supported by the New Relic Node.js v6 agent. Node.js 6, 7 and 9 are not supported by v6. Customers running Node.js 6, 7 and 9 have two options:
- Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v6 agent's new features.
- Remain on New Relic Node.js v5 agent without the ability to use new features only available with update agent versions.
Node.js 8 no longer receive updates, but New Relic will continue to support these versions of Node.js for the time being.
Upgrade to a newer version of Node.js as soon as possible. The next major version of the New Relic Node.js agent will likely remove support for Node.js 8.Before upgrading to Node.js agent v5, review this information for major changes. Also see New Relic's Node.js v5 migration guide on GitHub.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
<td>
* <DNT>**v2 - v4:**</DNT> Starting in agent v2.7.0, these methods were marked as deprecated but left in to give a transition period for the new methods.
* <DNT>**v5:**</DNT> Applications must use the API methods [`newrelic.addCustomAttribute()`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttribute) and [`newrelic.addCustomAttributes()`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttributes). These are drop-in replacements for the old methods.
</td>
</tr>
<tr>
<td>
Removed deprecated `create*Transaction` methods.
</td>
<td>
* <DNT>**v2 - v4:**</DNT> Starting in agent v2.0.2, these methods were marked as deprecated but left in to give a transition period to the new methods.
* <DNT>**v5:**</DNT> Applications must update to the API methods [`newrelic.startWebTransaction()`](https://newrelic.github.io/node-newrelic/API.html#startWebTransaction) and [`newrelic.startBackgroundTransaction()`](https://newrelic.github.io/node-newrelic/API.html#startBackgroundTransaction).
* <DNT>**Troubleshooting tips:**</DNT> These new methods are **not** drop-in replacements for the old ones. Before moving to these new methods, review our [custom instrumentation guide](/docs/agents/nodejs-agent/supported-features/nodejs-custom-instrumentation#web-txn).
</td>
</tr>
<tr>
<td>
Removed deprecated `createTracer` method.
</td>
<td>
* <DNT>**v3 - v4:**</DNT> Starting in agent v3.3.0, this method was marked as deprecated in favor of `newrelic.startSegment()`.
* <DNT>**v5:**</DNT> Applications must update to [`newrelic.startSegment()`](https://newrelic.github.io/node-newrelic/API.html#startSegment).
</td>
</tr>
<tr>
<td>
Removed `node-cassandra-cql` instrumentation.
</td>
<td>
* <DNT>**v4:**</DNT> Applications using the npm package [`node-cassandra-cql`](https://www.npmjs.com/package/node-cassandra-cql) would get datastore metrics for Cassandra.
* <DNT>**v5:**</DNT> Applications must migrate to the [`cassandra-driver`](https://www.npmjs.com/package/cassandra-driver) package to get Cassandra datastore metrics. This module is actively maintained by the same developers. The `node-cassandra-cql` package was abandoned in February of 2014 in favor of the `cassandra-driver` package.
</td>
</tr>
<tr>
<td>
Removed deprecated `capture_params` and `ignored_params` configurations.
</td>
<td>
* <DNT>**v2 - v4:**</DNT> Starting in agent v2.7.0, these configuration parameters caused a warning to be logged, and the values were automatically upgraded to the new attributes configurations.
* <DNT>**v5:**</DNT> A warning will still be logged but the configuration is ignored, and no automatic upgrading happens any more.
* <DNT>**Troubleshooting tips:**</DNT> If your application had parameters listed in the `ignored_params` configuration, you will need to move them to [`attributes.exclude`](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration#attributes_exclude).
</td>
</tr>
| **Major changes with Node.js v5 agent** |
|---|
| Removed deprecated `addCustomParameter` methods. |
Node.js 6 is the earliest version supported by the New Relic Node.js v5 agent. Node.js 4 and 5 are not supported by v5. Customers running Node.js 4 or 5 have two options:
- Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v5 agent's new features.
- Remain on New Relic Node.js v4 agent without the ability to use new features only available with update agent versions.
Node.js 7 and 9 no longer receive updates, but New Relic will continue to support these versions of Node.js for the time being.
Upgrade to a newer version of Node.js as soon as possible. The next major version of the New Relic Node.js agent will likely remove support for Node.js 6 and 7.As of New Relic for Node.js v5:
custom_instrumentation: This feature is no longer configurable.custom_metrics: This feature is no longer configurable.synthetics: This feature is no longer configurable.native_metrics: This feature is now controlled by theplugins.native_metrics.enabledconfiguration value.
Before upgrading to Node.js agent v4, review this information for major changes. Also see New Relic's Node.js v4 migration guide on GitHub.
Major changes with Node.js v4 agent include an upgrade of the `https-proxy-agent` from v0 to v2. This dependency has been updated due to a [security issue](/docs/using-new-relic/new-relic-security/security-bulletins/security-bulletin-nr18-08) in the `https-proxy-agent` that the New Relic Node.js agent used. Because `https-proxy` v2 is incompatible with node v0.10 and v0.12, New Relic has deprecated those agent versions. There is no required action to migrate from v3 to v4 of New Relic's Node.js agent.<Collapser id="v4-node-version" title="Node.js version support"
Node.js 4 is the earliest version supported by the New Relic Node.js v4 agent. Node.js 0.10 and 0.12 are not supported by v4. Customers running Node.js 0.10 or 0.12 have two options:
* Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v4 agent's new features.
* Remain on the New Relic Node.js v3 agent without the ability to use new features only available with updated agent versions.
[Node.js 4, 5, and 7 also no longer receive updates](https://github.com/nodejs/Release/tree/1d8fca#end-of-life-releases), but New Relic will continue to support these versions of Node.js for the time being.
<Callout variant="tip">
Upgrade to a newer version of Node.js as soon as possible. The next major version of the New Relic Node.js agent will likely remove support for Node.js 4 and 5.
</Callout>
Before upgrading to Node.js agent agent v3, review this information for major changes. Also see New Relic's Node.js v3 migration guide on GitHub.
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Removed SSL configuration
</td>
<td>
* <DNT>**v2:**</DNT> With the v2 agent, it was possible to configure the agent to connect to New Relic without encryption.
* <DNT>**v3:**</DNT> Node.js agent v3 always connects to New Relic servers using TLS encryption to protect communications. If the agent is configured to disable this, a warning is logged and the setting is ignored.
</td>
</tr>
<tr>
<td>
Request parameters now prefixed with `request.parameters.`
</td>
<td>
* <DNT>**v2:**</DNT> The v2 agent collects request parameters, such as route parameters (`/users/:userId`) and query parameters (`/users?userId=123`), as the parameter name (`userId`).
* <DNT>**v3:**</DNT> The v3 agent prefixes all request parameters with the string `request.parameters.`. For example,`userId` appears as `request.parameters.userId`.
* <DNT>**Troubleshooting tips:**</DNT> If you have dashboards, alert policies, or other NRQL queries based on request parameters, update them with the new parameter names.
</td>
</tr>
</tbody>
</table>
<Collapser id="v3-feature-flags" title="Feature flags as of v3"
As of New Relic Node.js agent v3, the `send_request_uri_attribute` feature is no longer configurable.
Before upgrading to Node.js agent v2, review this information for major changes. Also see New Relic's Node.js v2 migration guide on GitHub.
| **Major changes with Node.js v3 agent** |
|---|
<th>
<DNT>
**Comments**
</DNT>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Reversed naming and ignore rules
</td>
<td>
* <DNT>**v1:**</DNT> With the v1 agent, rules defined in the config properties `rules.name` and `rules.ignore` were applied in reverse order; the first rule in the list was applied last.
* <DNT>**v2:**</DNT> Node.js agent v2 applies rules in the order they are defined, so the first rule in the list is applied first.
* <DNT>**Troubleshooting tips:**</DNT> If you used naming rules in the v1 agent and notice problems, reverse the order of your rules in your configuration.
</td>
</tr>
<tr>
<td>
De-duplicated HTTP request transactions
</td>
<td>
* <DNT>**v1:**</DNT> The v1 agent started a new transaction for each listener on an HTTP server's `request` event. In applications with multiple listeners on the `request` event, this resulted in extraneous transactions being created that almost always did not get named correctly.
* <DNT>**v2:**</DNT> The v2 agent only creates a single transaction for each `request` event emitted.
* <DNT>**Troubleshooting tips:**</DNT> If you used multiple `request` event listeners and added a call to `newrelic.ignoreTransaction()` to remove the extra transactions, remove those calls.
</td>
</tr>
<tr>
<td>
Stopped swallowing outbound request errors
</td>
<td>
* <DNT>**v1:**</DNT> The v1 agent swallowed unhandled `error` events emitted by outbound HTTP request objects.
* <DNT>**v2:**</DNT> The v2 agent removes this behavior. Instead, the v2 agent does not change normal Node.js execution. This means the `error` event will always be emitted.
* <DNT>**Troubleshooting tips:**</DNT> If you are making outbound requests and currently do not listen for the `error` event, add a listener and handle the error as appropriate for your application.
</td>
</tr>
</tbody>
</table>
<Collapser id="config-options" title="Updated configuration options as of v2"
In `newrelic.js`, edit the [Node.js agent configuration](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration) properties you use for compatiblity with the latest versions:
<table>
<thead>
<tr>
<th width={200}>
<DNT>
**Deprecated property**
</DNT>
</th>
<th>
<DNT>
**New property**
</DNT>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
`capture_params`
</td>
<td>
`attributes.enabled: false`
By default, request attributes are not sent to New Relic. Set `attributes.enabled: true` to include agent-defined or custom attributes in traces. The `capture_params` property has been deprecated.
</td>
</tr>
<tr>
<td>
`ignored_params`
</td>
<td>
`attributes.exclude: []`
Add any request attribute keys to the `attributes.exclude` list. Now, instead of having to be an exact match, wildcards (`*`) may be appended to each item for broader filtering. The `ignored_params` property has been deprecated.
</td>
</tr>
</tbody>
</table>
These [Node.js agent configuration](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration) properties also have overrides for specific destinations, including:
* `transaction_tracer`
* `transaction_events`
* `error_collector`
* `browser_monitoring`
For example, if the root `attributes.enabled` is `true` and you set `transaction_tracer.attributes.enabled: false`, this will restrict attributes from being collected in transaction traces, while still allowing them for all others.
<Collapser id="deprecated-apis" title="Deprecated API methods as of v2"
The following methods from the Node.js agent have been deprecated, and New Relic has deleted them in v5 of the agent. Each has an easy replacement that accomplishes the same task in a more flexible and reliable way.
<CollapserGroup>
<Collapser
id="newrelic_createWebTransaction"
title={<InlineCode>newrelic.createWebTransaction()</InlineCode>}
>
Replace with [`newrelic.startWebTransaction()`](#newrelic_start_transaction) and [`newrelic.getTransaction()`](#newrelic_getTransaction).
</Collapser>
<Collapser
id="newrelic_createBackgroundTransaction"
title={<InlineCode>newrelic.createBackgroundTransaction()</InlineCode>}
>
Replace with [`newrelic.startBackgroundTransaction()`](#newrelic_start_transaction) and [`newrelic.getTransaction()`](#newrelic_getTransaction).
</Collapser>
<Collapser
id="newrelic_addCustomParameter"
title={<InlineCode>newrelic.addCustomParameter()</InlineCode>}
>
Replace with [`newrelic.addCustomAttribute()`](#newrelic_add_custom_attribute).
</Collapser>
<Collapser
id="newrelic_addCustomParameter"
title={<InlineCode>newrelic.addCustomParameters()</InlineCode>}
>
Replace with [`newrelic.addCustomAttributes()`](#newrelic_add_custom_attributes).
</Collapser>
</CollapserGroup>
<Collapser id="api-methods" title="New v2 agent API methods"
The following API methods are new with the New Relic Node.js v2 agent.
<CollapserGroup>
<Collapser
id="newrelic_getTransaction"
title={<InlineCode>newrelic.getTransaction()</InlineCode>}
>
This method gets a reference to the currently running transaction. Use in conjunction with:
* `newrelic.startWebTransaction`
* `newrelic.startBackgroundTransaction`
* Callback-based message consumer services for [troubleshooting message consumers](/docs/agents/nodejs-agent/troubleshooting/troubleshoot-message-consumers)
</Collapser>
<Collapser
id="newrelic_start_transaction"
title={<><InlineCode>newrelic.startWebTransaction()</InlineCode><InlineCode>newrelic.startBackgroundTransaction()</InlineCode></>}
>
These new API methods replace the older `create*Transaction` methods. They are easier to use and seamlessly work with promises. Unlike the v1 method, the provided callback is invoked immediately.
</Collapser>
<Collapser
id="newrelic_instrument"
title={<><InlineCode>newrelic.instrument()</InlineCode><InlineCode>newrelic.instrumentDatastore()</InlineCode><InlineCode>newrelic.instrumentWebframework()</InlineCode><InlineCode>newrelic.instrumentMessages()</InlineCode></>}
>
Use these methods to add custom instrumentation for third party modules, including those already instrumented by the New Relic Node.js agent. For more information, see New Relic's [Node.js instrumentation example application on GitHub](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/custom-instrumentation/instrument).
</Collapser>
<Collapser
id="newrelic_add_custom_attribute"
title={<InlineCode>newrelic.addCustomAttribute()</InlineCode>}
>
Use this method to add a custom trace attribute.
</Collapser>
<Collapser
id="newrelic_add_custom_attributes"
title={<InlineCode>newrelic.addCustomAttributes()</InlineCode>}
>
Use this method to add multiple custom trace attributes.
</Collapser>
</CollapserGroup>
<Collapser id="node-support" title="Node.js version support for v2"
The earliest version of Node.js supported by the New Relic Node.js v2 agent is 0.10. Node.js 0.8, which has not been updated since July of 2014, is not supported by v2. Customers running Node.js 0.8 have two options:
* Upgrade to a supported version of Node.js and take advantage of the New Relic Node.js v2 agent's new features.
* Remain on New Relic Node.js v1 agent without the ability to use new features only available with updated agent versions.
[Node.js 0.10 also no longer receives updates](https://github.com/nodejs/LTS/tree/2b4253#lts-schedule1), but New Relic will continue to support this version of Node.js for the time being.
Recommendation: Upgrade to a newer version of Node.js as soon as possible.
<Collapser id="npm-versions" title="npm version support as of v2"
The New Relic Node.js agent now requires npm version 2.0.0 or higher. This version of npm comes packaged with Node.js 0.10.44 or higher.
If you are using an earlier version of Node.js 0.10 you will need to first install npm 2.0.0 or higher, or upgrade to a newer version of Node. To install npm version 2:
```
$ npm install --global npm@2
```
<Collapser id="v2-feature-flags" title="Feature flags as of v2"
As of New Relic Node.js agent v2:
* `express_segments`: This feature is no longer configurable.
* `cat`: This feature is now controlled by the `cross_application_tracer.enabled` configuration value.
<Collapser id="framework-minimum" title="Framework minimum versions as of v2"
As of New Relic Node.js agent v2:
<table>
<thead>
<tr>
<th style={{ width: "150px" }}>
<DNT>
**Module**
</DNT>
</th>
<th style={{ width: "175px" }}>
<DNT>
**V2 minimum**
</DNT>
</th>
<th style={{ width: "175px" }}>
<DNT>
**Minimum before v2**
</DNT>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
express
</td>
<td>
4.6.0
</td>
<td>
2.0.0
</td>
</tr>
<tr>
<td>
mysql
</td>
<td>
2.0.0
</td>
<td>
0.9.0
</td>
</tr>
</tbody>
</table>
| **Major changes with Node.js v2 agent** |
|---|