Node.js Agent v2.x Instrumentation API Beta


The New Relic Node.js Agent v2.x Instrumentation API is an enhanced API that allows you to easily write high-quality custom instrumentation that can be distributed independently from the agent.

With these enhancements, Node package authors can easily create and distribute New Relic instrumentation for modules together with packages, or as a separate package that can be optionally included by users. Node package consumers can independently author their own instrumentation for packages not currently supported out-of-the-box, or replace New Relic's out-of-the-box instrumentation with their own.

This release includes new API for writing custom instrumentation for datastores and web frameworks. If you have authored datastore driver or web framework packages that are currently un-instrumented, or are instrumented using pre-2.0 custom instrumentation, please give us your feedback.

Supported versions

This beta is a part of version 2.x of the New Relic Node agent. For Node.js, you must have version 0.10.x or higher.

Beta access

To access the Beta agent, review and complete the New Relic Node.js Agent Beta Test Agreement. After approval, you will receive an email with a Beta token and further instructions.

Install the Beta agent

As with any beta software, New Relic strongly advises running this agent in a testing or staging environment before considering its use in a production environment.

Once you have received your Beta token, install the beta agent:

  1. Install the beta agent module via npm install @newrelic/beta-agent.
  2. Update the package.json for your application to depend on @newrelic/beta-agent instead of newrelic.
  3. Change the require('newrelic') line at the top of your application's main module to require('@newrelic/beta-agent') to reference the beta package. If you are not already including the agent, you will need to add this line.
  4. Set the beta_token in your newrelic.js file or the environment variable NEW_RELIC_BETA_TOKEN to the beta token you received in your beta agreement approval email.

Beta documentation

For additional Beta agent and API documentation (including examples, naming rules, and more) see the full beta documentation on Github.

You can also view a tutorial on how to use the new API to instrument a database driver or instrument a web framework.

Feedback and questions

If you encounter a bug or issue while running the beta, contact New Relic Support and mention the Node.js Agent v2.x Instrumentation API Beta in your message.

If you would like to provide general feedback or have any questions, see the Node.js Agent section of the New Relic Online Technical Community.

For more help

Additional documentation resources include:

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