• EnglishEspañol日本語한국어Português
  • Log inStart now

Node.js agent API

New Relic offers several tools to help obtain the information needed to provide useful metrics about your Node.js application. These include:

  • Reading the route names (if used) from the Express and Restify routers
  • Using the API to name the current request, either with simple names or groups of controllers with actions
  • Support rules that are stored in your agent's configuration that can mark requests to be renamed or ignored based on regular expressions matched against the request's raw URLs (also available as API calls)

The number of names that New Relic tracks needs to be small enough so that the user experience is robust. It also needs to be large enough to provide the right amount of information (without overwhelming you with data) so that you can identify problem spots in your applications more easily.

For more information, see the Node.js agent configuration documentation and the Node.js agent API documentation on Github.

Request names

The Node.js agent captures the HTTP method along with a potentially parameterized path (such as /user/:id) or a regular expression (such as /^/user/([-0-9a-f]+)$/). These pieces of information become part of the request name.

If you have support for slow transaction traces and have added 'request.parameters.*' to attributes.include in your config file, the transaction trace will also have the request's parameters and their values attached. If you don't like the request names that the Node.js agent uses, you can use API calls to create more descriptive names.


If grouping your requests under the generic name, then /* is sufficient, and you do not need to customize your configuration file or API calls.


New Relic uses request names to group requests for many charts and tables. The value of these visualizations will drop as the number of different request names increases.

For example, do not include potentially dynamic data like GUIDs, numerical IDs, or timestamps in the request names you create. If your request is slow enough to generate a transaction trace, that trace will contain the original URL. If you enable parameter capture, the parameters will also be attached to the trace.


Avoid having more than 50 different transaction names. For example, if you have more than a couple hundred different request names, rethink your naming strategy.

Avoid metric grouping issues

The request naming API helps New Relic avoid problems with trying to handle too many metrics, which sometimes is referred to as "metric explosion." New Relic has several strategies to deal with these issues; the most severe is simply to add offending applications to your deny list.

The main reason for you to be careful in using these request-naming tools is to prevent that from happening to your applications. For more information, see Metric grouping issues.


Define your configuration rules from the most specific to the most general. The first rules listed in your config file or added with the Node.js transaction naming API will be applied first and should be narrowly targeted. More general "fall-through" rules should be added toward the end of the list, because they will be evaluated in the order they were configured or added using the Node.js transaction naming API.

Load the request naming API

Make sure that loading the New Relic module is the first thing your application does, as it needs to bootstrap itself before the rest of your application loads:

const newrelic = require('newrelic');

This returns the request naming API. You can safely require the module from multiple modules in your application, as it only initializes itself once.

Request API calls

Here is a summary of the Request API calls for New Relic's Node.js agent.

Custom instrumentation API calls

Use these API calls to expand your instrumentation with custom instrumentation.

Custom metrics API calls

Use these API calls to record additional arbitrary metrics:

Custom events API calls

Use these API calls to record additional events:

Transaction handle methods

This section details the methods provided by the TransactionHandle class instance that can be obtained through newrelic.getTransaction().

Use these methods to interact directly with the current transaction:

Other API calls

New Relic's Node.js agent includes additional API calls.

Rules for naming and ignoring requests

If you do not want to put calls to the New Relic module directly into your application code, you can use pattern-based rules to name requests. There are two sets of rules: one for renaming requests, and one to mark requests to be ignored by New Relic's instrumentation.

Here is the structure for rules in New Relic's Node.js agent.

Here are full examples of how rules are included in the configuration file:

API calls for rules

Here are the API calls for naming and ignoring rules with New Relic's Node.js agent.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.