Upgrade the Node.js agent

To ensure that you have the most up-to-date version of New Relic, 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.

New Relic recommends testing 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 4

Review this information to help you upgrade to New Relic's Node.js v4 agent, or refer to New Relic's Node.js v4 migration guide on GitHub. Here is a summary of major changes.

Major changes with Node.js v4 agent Comments
Upgraded https-proxy-agent from v0 to v2
  • This dependency has been updated due to a security issue in the version of https-proxy-agent the New Relic Node.js agent used. https-proxy v2 is incompatible with node v0.10 and v0.12, requiring deprecation of those versions for the agent. There is no required action to migrate from v3 to v4 of New Relic's Node.js agent.

Upgrade to Node.js agent version 3

Review this information to help you upgrade to New Relic's Node.js v3 agent, or refer to New Relic's Node.js v3 migration guide on GitHub. Here is a summary of major changes.

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 now 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 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:

  • send_request_uri_attribute: This feature is no longer configurable.

Upgrade to Node.js agent version 2

Review this information to help you upgrade to New Relic's Node.js v2 agent, or refer to New Relic's Node.js v2 migration guide on GitHub. Here is a summary of major changes.

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

Updated configuration options as of v2

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.

These Node.js 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.

Deprecated API methods as of v2

The following methods from the Node.js agent have been deprecated, and New Relic will delete them in the next major version of the Node.js agent. Each has an easy replacement that accomplishes the same task in a more flexible and reliable way.

newrelic.createWebTransaction()

Replace with newrelic.startWebTransaction() and newrelic.getTransaction().

newrelic.createBackgroundTransaction()

Replace with newrelic.startBackgroundTransaction() and newrelic.getTransaction().

newrelic.addCustomParameter()

Replace with newrelic.addCustomAttribute().

newrelic.addCustomParameters()

Replace with newrelic.addCustomAttributes().

New v2 agent API methods

The following API methods are new with the New Relic Node.js v2 agent.

newrelic.getTransaction()

This method gets a reference to the currently running transaction. Use in conjunction with:

newrelic.startWebTransaction()
newrelic.startBackgroundTransaction()

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.

newrelic.instrument()
newrelic.instrumentDatastore()
newrelic.instrumentWebframework()
newrelic.instrumentMessages()

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.

newrelic.addCustomAttribute()

Use this method to add a custom trace attribute.

newrelic.addCustomAttributes()

Use this method to add multiple custom trace attributes.

Node version support

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. The next major version of the New Relic Node.js agent will likely remove support for Node 0.10.

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 cross_application_tracer.enabled configuration value.

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

For more help

Recommendations for learning more: