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 8
Before upgrading to Node.js version 8, review this information for major changes.
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 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 version support
Node v12 is the earliest version supported by the New Relic Node.js v8 agent. Node 10 and 11 are not supported by v8. Customers running Node 11 and earlier have two options:
Upgrade to a supported version of Node 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 as soon as possible. The next major version of the New Relic Node.js agent will likely remove support for Node 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.
Update New Relic Dependencies to versions with updated Node 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 version support
Node v10 is the earliest version supported by the New Relic Node.js v7 agent. Node 8 and 9 are not supported by v7. Customers running Node 9 and earlier have two options:
Upgrade to a supported version of Node 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 10 does not receive updates. Upgrade to a newer version of Node as soon as possible. Support for Node 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 v12 and removed support for Node v6, 7, and 9. The minimum supported version is Node v8.
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 version support
Node 8 is the earliest version supported by the New Relic Node.js v6 agent. Node 6, 7 and 9 are not supported by v6. Customers running Node 6, 7 and 9 have two options:
Upgrade to a supported version of Node 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.
Troubleshooting tips: These new methods are not drop-in replacements for the old ones. Before moving to these new methods, review our custom instrumentation guide.
Removed deprecated createTracer method.
v3 - v4: Starting in agent v3.3.0, this method was marked as deprecated in favor of newrelic.startSegment().
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 version support
Node 6 is the earliest version supported by the New Relic Node.js v5 agent. Node 4 and 5 are not supported by v5. Customers running Node 4 or 5 have two options:
Upgrade to a supported version of Node 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.
Upgrade to a newer version of Node as soon as possible. The next major version of the New Relic Node.js agent will likely remove support for Node 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.
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 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.
Node 4 is the earliest version supported by the New Relic Node.js v4 agent. Node 0.10 and 0.12 are not supported by v4. Customers running Node 0.10 or 0.12 have two options:
Upgrade to a supported version of Node 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.
Upgrade to a newer version of Node as soon as possible. The next major version of the New Relic Node.js agent will likely remove support for Node 4 and 5.
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.
Major changes with Node.js v3 agent
Comments
Removed SSL configuration
v2: With the v2 agent, it was possible to configure the agent to connect to New Relic without encryption.
v3: 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.
Request parameters now prefixed with request.parameters.
v2: The v2 agent collects request parameters, such as route parameters (/users/:userId) and query parameters (/users?userId=123), as the parameter name (userId).
v3: The v3 agent prefixes all request parameters with the string request.parameters.. For example,userId appears as request.parameters.userId.
Troubleshooting tips: If you have dashboards, alert policies, or other NRQL queries based on request parameters, update them with the new parameter names.
As of New Relic Node.js agent v3, the send_request_uri_attribute feature is no longer configurable.
v1: 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.
v2: Node.js agent v2 applies rules in the order they are defined, so the first rule in the list is applied first.
Troubleshooting tips: If you used naming rules in the v1 agent and notice problems, reverse the order of your rules in your configuration.
De-duplicated HTTP request transactions
v1: 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.
v2: The v2 agent only creates a single transaction for each request event emitted.
Troubleshooting tips: If you used multiple request event listeners and added a call to newrelic.ignoreTransaction() to remove the extra transactions, remove those calls.
Stopped swallowing outbound request errors
v1: The v1 agent swallowed unhandled error events emitted by outbound HTTP request objects.
v2: The v2 agent removes this behavior. Instead, the v2 agent does not change normal Node execution. This means the error event will always be emitted.
Troubleshooting tips: 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.
In newrelic.js, edit the Node.js agent configuration properties you use for compatiblity with the latest versions:
Deprecated property
New property
capture_params
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.
ignored_params
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.
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.
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.
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.
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 tutorials on GitHub.
Use this method to add a custom trace attribute.
Use this method to add multiple custom trace attributes.
The earliest version of Node supported by the New Relic Node.js v2 agent is 0.10. Node 0.8, which has not been updated since July of 2014, is not supported by v2. Customers running Node 0.8 have two options:
Upgrade to a supported version of Node 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.
Recommendation: Upgrade to a newer version of Node as soon as possible.
The New Relic Node.js agent now requires npm version 2.0.0 or higher. This version of npm comes packaged with Node 0.10.44 or higher.
If you are using an earlier version of Node 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
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.