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.

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

Deprecated API methods

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

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

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

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

Released feature flags

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.

New framework minimum versions

Module V2 minimum Minimum before v2
express 4.6.0 2.0.0
mysql 2.0.0 0.9.0

For more help

Additional documentation resources include:

For more help

Join the discussion about Node.js monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.