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 your
- If you want to target just the
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 v5
Before upgrading to Node.js 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|
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.
Node 7 and 9 no longer receive updates, but New Relic will continue to support these versions of Node for the time being.
Recommendation: 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
Node.js agent versions not supported
End of life notification: As of January 26, 2015, New Relic will no longer accept data from Node.js agent versions earlier than 1.14.1.
These agent versions use an out-of-date protocol when communicating with New Relic's data collection services. In addition, many of these versions contain a potential security issue where they may incorrectly send sensitive data to the New Relic collector.
Upgrade to Node.js agent version 4
Before upgrading to Node.js v4, review this information for major changes. Also see New Relic's Node.js v4 migration guide on GitHub.
- Upgrade https-proxy-agent from v0 to v2
Major changes with Node.js v4 agent include an upgrade of the
https-proxy-agentfrom v0 to v2. This dependency has been updated due to a security issue in the
https-proxy-agentthat the New Relic Node.js agent used. Because
https-proxyv2 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 version support
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.
Node 4, 5, and 7 also no longer receive updates, but New Relic will continue to support these versions of Node for the time being.
Recommendation: 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 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
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
- v2: The v2 agent collects request parameters, such as route parameters (
/users/:userId) and query parameters (
/users?userId=123), as the parameter name (
v3: The v3 agent prefixes all request parameters with the string
request.parameters.. For example,
- Troubleshooting tips: If you have Insights dashboards, alert policies, or other NRQL queries based on request parameters, update them with the new parameter names.
- Feature flags as of v3
As of New Relic Node.js agent v3, the
send_request_uri_attributefeature is no longer configurable.
Upgrade to Node.js agent version 2
Before upgrading to Node.js v2, review this information for major changes. Also see New Relic's Node.js v2 migration guide on GitHub.
- Major changes with Node.js v2 agent
Major changes with Node.js v2 agent Comments Reversed naming and ignore rules
- v1: With the v1 agent, rules defined in the config properties
rules.ignorewere 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
requestevent. In applications with multiple listeners on the
requestevent, 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
- Troubleshooting tips: If you used multiple
requestevent 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
errorevents 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
errorevent will always be emitted.
- Troubleshooting tips: If you are making outbound requests and currently do not listen for the
errorevent, add a listener and handle the error as appropriate for your application.
- v1: With the v1 agent, rules defined in the config properties
- Updated configuration options as of v2
newrelic.js, edit the Node.js agent configuration properties you use for compatiblity with the latest versions:
Deprecated property New property
By default, request attributes are not sent to New Relic. Set
attributes.enabled: trueto include agent-defined or custom attributes in traces. The
capture_paramsproperty has been deprecated.
Add any request attribute keys to the
attributes.excludelist. Now, instead of having to be an exact match, wildcards (
*) may be appended to each item for broader filtering. The
ignored_paramsproperty has been deprecated.
These Node.js agent configuration properties also have overrides for specific destinations, including:
For example, if the root
trueand you set
transaction_tracer.attributes.enabled: false, this will restrict attributes from being collected in transaction traces, while still allowing them for all others.
- 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.
- New v2 agent API methods
The following API methods are new with the New Relic Node.js v2 agent.
This method gets a reference to the currently running transaction. Use in conjunction with:
- Callback-based message consumer services for troubleshooting message consumers
These new API methods replace the older
create*Transactionmethods. 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.
- Node version support for v2
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.
Node 0.10 also no longer receives updates, but New Relic will continue to support this version of Node for the time being.
Recommendation: Upgrade to a newer version of Node as soon as possible.
- 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 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
- 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
- Framework minimum versions as of v2
As of New Relic Node.js agent v2:
Module V2 minimum Minimum before v2 express 4.6.0 2.0.0 mysql 2.0.0 0.9.0