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, the Node.js agent API documentation on Github and Node.js agent example applications.

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.

Requirements

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

Guidelines

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.

/user/customers/all/prospects
/user/customers/all/current
/user/customers/all/returning
/user/customers/John
/user/customers/Jane

// newrelic.js
exports.config={
  //other configuration
  rules:{
    name:[
      { pattern: "/user/customers/all/prospects/", name: "/user/customers/all/prospects" },
      { pattern: "/user/customers/all/.*", name: "/user/customers/all" },
      { pattern: "/user/customers/.*", name: "/user/customers/:customer" }
    ]
  }
};

Load the 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 New Relic Node.js 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.

• setTransactionName
• setControllerName

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:

• recordCustomEvent
• recordLogEvent

Transaction handle methods

Use these API calls to interact with the current transaction

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.

NEW_RELIC_NAMING_RULES='{"pattern":"^t","name":"u"},{"pattern":"^u","name":"t"}'

pattern:     '[0-9]+',
replace_all: true

$
node node_modules/.bin/newrelic-naming-rules

pattern: '^/items/[0-9]+$',
name:    '/items/:id'

/items/123   =>  /items/:id
/orders/123  =>  /orders/123   (not replaced since the rule is a full match)

pattern: '[0-9]+',
name:    ':id'

/orders/123            =>  /orders/:id
/items/123             =>  /items/:id
/orders/123/items/123  =>  /orders/:id/items/123

pattern:     '[0-9]+',
name:        ':id',
replace_all: true

/orders/123/items/123  =>  /orders/:id/items/:id

pattern: '^/(items|orders)/[0-9]+$',
name:    '/\\1/:id'

/orders/123  =>  /orders/:id
/items/123   =>  /items/:id

NEW_RELIC_IGNORING_RULES='^/socket\.io/\*/xhr-polling,ignore_me'

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

// newrelic.js
exports.config = {
  // other configuration
  rules : {
    name : [
      { pattern: "/tables/name-here", name: "/name-hererule1" }
    ]
  }
};

// newrelic.js
exports.config = {
  // other configuration
  rules : {
    ignore : [
      '^\/socket\.io\/.*\/xhr-polling'
    ]
  }
};

API calls for rules

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

• addNamingRule
• addIgnoringRule