Guide to using the Node.js agent API

The New Relic Node.js agent API allows you to extend the agent's standard functionality. You can use this API to:

  • Customize your app name
  • Create custom transaction parameters
  • Report custom errors and metrics

You can also use the API for custom instrumentation. For supported frameworks, the agent instruments most activity automatically. Custom instrumentation lets you extend that monitoring to frameworks without default instrumentation.

Other resources:


To use the Node.js agent API, make sure you have the latest Node.js agent release. In addition, see:

Instrument missing sections of your code with transactions

To instrument your app, New Relic separates each path through your code into its own transaction. New Relic times (or "instruments") the parent method in these transactions to measure your app's overall performance, and collects transaction traces from long-running transactions for additional detail.

Use these methods when New Relic is not instrumenting a particular part of your code at all:

If you want to... Do this...
Start timing a method New Relic is not instrumenting automatically Create a new transaction. See newrelic.startWebTransaction().
Stop timing a method after its work is completed

Use either of these options:

Prevent a transaction from reporting to New Relic

Ignore the transaction using any of these options:

Time specific methods using segments

If a transaction is already visible in the New Relic UI, but you don't have enough data about a particular method that was called during that transaction, you can create segments to time those individual methods in greater detail. For example, you might want to time a particularly critical method with complex logic.

Use this method when you want to instrument a method within an existing transaction:

If you want to... Do this...
Time a particular method See newrelic.startSegment().

For more information about timing, see the instrumentation tutorial on GitHub.

Enhance the metadata of a transaction

Sometimes the code you are targeting is visible in the New Relic UI, but some details of the method are not useful. For example:

Use these methods when you want to change how New Relic instruments a transaction that's already visible in the New Relic UI:

If you want to... Do this...
Change the name of a transaction See newrelic.setTransactionName and
Add metadata (such as your customer’s account name or subscription level) to your transactions Use custom attributes. (Custom attribute collection is enabled by default in the Node.js agent.) See newrelic.addCustomAttribute() and newrelic.addCustomAttributes().
Create a new transaction for background work See newrelic.startBackgroundTransaction().
Create a new web transaction Use newrelic.startWebTransaction().
Prevent a transaction from affecting your Apdex score See Rules for naming and ignoring requests, including the ignoring rules example.
Record other performance data, such as timing or computer resource data Use the custom metrics API.

Instrument asynchronous work

For supported frameworks and supported Node.js versions, New Relic's Node.js agent usually correctly instruments async work. However, if your app uses another framework, or if the default async instrumentation is inaccurate, you can explicitly track async work.

If you want to... Do this...
Trace an async method that New Relic is already instrumenting See newrelic.startSegment.
Trace an async method that New Relic is not instrumenting See newrelic.startSegment.
Trace a transaction that got lost See newrelic.startSegment. You can also create your own custom instrumentation for libraries that are losing your transactions.
Trace a lost transaction state A common issue is the loss of transaction state while using uninstrumented libraries. For more information, see the transaction preservation tutorial on GitHub.

Instrument calls to external services

Once the request naming API loads, New Relic's Node.js agent can automatically identify external service calls. You can also use these methods to collect data about your app's connections to other apps or databases:

If you want to... Do this...
Time a call to an external resource (such as an external service, database server, or message queue)

Use any of these as appropriate:

Also see the tutorials on GitHub for datastore shims and message shims.

Connect activity to another app instrumented by a New Relic agent Use cross application tracing.

Collect or ignore errors

Usually the agent detects errors automatically. However, you can manually mark an error with the agent. You can also mark errors as ignored.

If you want to... Do this...
Report an error the agent does not report automatically See newrelic.noticeError().

Send custom event and metric data from your app

New Relic APM includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see Data collection.

If you want to... Do this...
Send data about an event so you can analyze it in New Relic Insights Create a custom event. See newrelic.recordCustomEvent().
Tag your events with metadata to filter and facet them in Insights or error analytics Add custom attributes if needed. (Custom attribute collection is enabled by default in the Node.js agent.) See newrelic.addCustomAttribute() and newrelic.addCustomAttributes().
Report custom performance data Create a custom metric. See newrelic.recordMetric() and newrelic.incrementMetric(). To view the data, use the Metric explorer in New Relic Insights.

Control the New Relic Browser agent

Usually the Browser agent is added automatically to your pages or deployed by copy/pasting the JavaScript snippet. For more information about these recommended methods, see Add apps to New Relic Browser.

You can also control the New Relic Browser agent via APM agent API calls. For more information, see New Relic Browser and the Node.js agent.

Extend custom instrumentation

The newrelic.instrument() provides additional flexibility for custom instrumentation. For more information, including tutorials and examples, see the shims documentation on GitHub.

For more help

Recommendations for learning more: