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.
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 enabled
capture_params in your config file, the transaction trace will also have the request's parameters and their values attached to it. If you are dissatisfied with 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.
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.
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:
var 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.
Here is a summary of the Request API calls for New Relic's Node.js agent.
Use these API calls to expand your instrumentation with custom instrumentation.
Use these API calls to record additional arbitrary metrics:
Use these API calls to record additional events:
This section details the methods provided by the
TransactionHandle class instance that can be obtained through
Use these methods to interact directly with the current transaction:
New Relic's Node.js agent includes additional API calls.
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:
Here are the API calls for naming and ignoring rules with New Relic's Node.js agent.