• English日本語한국어
  • Log inStart now

Update the Node.js agent

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 newrelic module is listed in your package.json, run npm install.
  • If you want to target just the newrelic module, run npm update newrelic.

Recommendation: Test your updated version before moving it into production. If you have problems, follow the Node.js agent troubleshooting procedures.

Upgrade to Node.js agent version 11

Before upgrading to Node.js version 11, review this information for major changes.

Major changes with Node.js agent v11

Comments

Added official parity support for Node.js 20.

BREAKING: Dropped Node.js 14 support.

BREAKING: Updated ESM loader to support Node.js 20.

  • 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

BREAKING: Updated the default context manager to be AsyncLocalContextManager.

BREAKING: Renamed shim.handleCATHeaders to shim.handleMqTracingHeaders.

Update New Relic dependencies to versions with updated Node.js version support

  • @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

Node.js version support

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.

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 16.

Upgrade to Node.js agent version 10

Before upgrading to Node.js version 10, review this information for major changes.

Major changes with Node.js agent v11

Comments

  • Added the ability to register instrumentation multiple hooks (onRequire, onResolved) for the same resolved moduleName.
  • 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.

BREAKING: Updated the default of config.transaction_tracer.record_sql from off to obfuscated. This means that sql statements will be captured but obfuscated.

BREAKING: Route (URL) parameters are now stored as request.parameters.route.* attributes on Transactions, root Segments and Spans.

  • 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.

BREAKING: Removed captureUrlParams from WebFrameworkShim class.

DEPRECATION NOTICE: shim.unwrap and shim.unwrapOnce will no longer function if you attempt to unwrap an item that has been wrapped multiple times.

  • 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.

Update New Relic dependencies to versions with updated Node.js version support

  • @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

Node.js version support

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.

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 14.

Upgrade to Node.js agent version 9

Before upgrading to Node.js version 9, review this information for major changes.

Major changes with Node.js agent v9

Comments

Added official parity support for Node.js 18.

BREAKING: Dropped Node.js 12 support.

BREAKING: The agent no longer includes the New Relic certificate bundle automatically when using the 'certificates' configuration (commonly with proxies).

  • 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.

BREAKING: The agent now excludes port when making external HTTPS requests to port 443 to be in compliance with the spec and other agents

  • 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.

BREAKING: Removed ability to disable async hooks based promise context tracking via the await_support feature flag. This also removes the legacy Promise instrumentation.

  • 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.

BREAKING: Removed instrumentation for the obsolete oracle npm package.

BREAKING: Updated the minimum version of pg to be 8.2.x. This is the earliest support version that runs on Node.js 14+.

BREAKING: Updated the minimum supported version of hapi to be v20.0.0.

  • All versions lower than v20.0.0 are deprecated by hapi for security reasons. See their support policy.

Update New Relic dependencies to versions with updated Node.js version support

  • @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

Node.js version support

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.

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 14.

Upgrade to Node.js agent version 8

Before upgrading to Node.js version 8, review this information for major changes.

Major changes with Node.js agent v8

Comments

Added official parity support for Node.js 16.

BREAKING: Dropped Node.js v10.x support.

BREAKING: Removed serverless_mode as a feature flag.

  • The standard serverless_mode configuration still exists.

BREAKING: The agent no-longer includes the New Relic certificate bundle automatically when using the 'certificates' configuration (commonly with proxies).

  • 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.

Update New Relic Dependencies to versions with updated Node.js version support

  • @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

Node.js version support

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.

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 12.

Upgrade to Node.js agent version 7

Before upgrading to Node.js version 7, review this information for major changes.

Major changes with Node.js agent v7

Comments

BREAKING Removed deprecated httpResponseCode, response.status and httpResponseMessage http response attributes

  • v6.4.2-v6.14.0: Starting in agent v6.4.2, these attributes were marked as deprecated but left in to give a transition period for the new attributes.
  • v7: When http response attribute reporting is enabled, http.statusCode and http.statusText will be reported.

BREAKING Removed deprecated setIgnoreTransaction API method

  • v5 - v6: Starting in agent v5.0.0, this method was marked as deprecated but left in to give a transition period for the new methods.
  • v7: Applications must use the API method transactionHandle.ignore().

BREAKING Removed the api.custom_parameters_enabled configuration item and associated environment variable NEW_RELIC_API_CUSTOM_PARAMETERS.

BREAKING Removed deprecated Distributed Tracing API methods, createDistributedTracePayload() and acceptDistributedTracePayload()

Update New Relic Dependencies to versions with updated Node.js version support

  • @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

Node.js version support

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.

Upgrade to Node.js agent version 6

Before upgrading to Node.js agent version 6, review this information for major changes.

Major changes with Node.js agent v6

Comments

Upgraded official Koa framework instrumentation module to v3.0.0

  • v6: Added support for @koa/router up to v8.0.2. @koa/router v8.0.3 and greater are currently unsupported.
  • v6: 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..

Removed deprecated max_samples_per_minute configuration parameter, which is replaced by max_samples_stored behavior

  • v1 - v5: 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.
  • v5: 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.
  • v6: 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.
  • Troubleshooting tips: 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.

Node.js version support

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.

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 8.

Upgrade to Node.js agent version 5

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.

Major changes with Node.js v5 agent

Comments

Removed deprecated addCustomParameter methods.

Removed deprecated create*Transaction methods.

Removed deprecated createTracer method.

  • v3 - v4: Starting in agent v3.3.0, this method was marked as deprecated in favor of newrelic.startSegment().
  • v5: Applications must update to newrelic.startSegment().

Removed node-cassandra-cql instrumentation.

  • v4: Applications using the npm package node-cassandra-cql would get datastore metrics for Cassandra.
  • v5: Applications must migrate to the 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.

Removed deprecated capture_params and ignored_params configurations.

  • v2 - v4: 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.
  • v5: A warning will still be logged but the configuration is ignored, and no automatic upgrading happens any more.
  • Troubleshooting tips: If your application had parameters listed in the ignored_params configuration, you will need to move them to attributes.exclude.

Node.js version support

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.

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 6 and 7.

Feature flags as of v5

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 the plugins.native_metrics.enabled configuration value.

Upgrade to Node.js agent version 4

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.

Upgrade to Node.js agent version 3

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.

Upgrade to Node.js agent version 2

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.