• /
  • Log in
  • Free account

Node.js custom instrumentation

New Relic for Node.js automatically instruments most standard web requests, but sometimes you want expanded instrumentation. With the agent's custom instrumentation API, you can create instrumentation for otherwise unsupported web frameworks, datastores, and message service clients.

The Node.js agent's custom instrumentation API also allows you to:

Agent version requirements

The custom instrumentation methods in this document are available as of Node.js agent version 2.0.0. For information on instrumentation using the custom instrumentation API v1.x, see the documentation for legacy Node.js custom instrumentation.

Instrument unsupported web frameworks

Beginning with Node.js agent version 2.0.0, New Relic provides an API to expand instrumentation for additional web frameworks. For more information, including a tutorial, see the documentation for Node.js web framework instrumentation on GitHub.

Instrument unsupported message service clients

Beginning with Node.js agent version 2.0.0, New Relic provides an API to expand instrumentation for additional message service libraries. For more information, including a tutorial, see the documentation for Node.js message service client instrumentation on GitHub.

Instrument unsupported datastores

Beginning with Node.js agent version 2.0.0, New Relic provides an API to expand instrumentation for additional datastore libraries. For more information, including a tutorial, see the documentation for Node.js datastore instrumentation on GitHub.

Instrument web transactions

In order to create custom web transactions, call startWebTransaction to start the transaction. To end the transaction, use any of these options:

Ending the transaction

Comments

Promise

If the handler passed to startWebTransaction returns a promise, the agent will end the transaction when the returned promise resolves or rejects.

Manual

If you call getTransaction in the context of the new transaction, this notifies the agent that the transaction will be handled manually.

If getTransaction is called in the handler, then you must end the transaction by calling transaction.end().

Synchronous

If neither of these options are fulfilled, the transaction will be ended when the handler returns synchronously.

Instrument background transactions

You can use custom transactions to instrument non-web transactions (background tasks); for example:

  • Periodic jobs within your app
  • Work that continues after a request completes

To instrument background tasks, call startBackgroundTransaction in your handler to start a background transaction. To end the transaction, use any of these options:

Ending the transaction

Comments

Promise

If the handler passed to startBackgroundTransaction returns a promise, the agent will end the transaction when the returned promise resolves or rejects.

Manual

If you call getTransaction in the context of the new transaction, this notifies the agent that the transaction will be handled manually.

If getTransaction is called in the handler, then you must end the transaction by calling transaction.end().

Synchronous

If neither of these options are fulfilled, the transaction will be ended when the handler returns synchronously.

Expand instrumentation within transactions

You can create instrumentation using the instrumentation registration methods on the API. Writing instrumentation using the instrumentation API allows you to specify metrics and naming in greater detail by "monkey patching" methods (replacing functions) on relevant objects. Other options can offer visibility into web transactions that are already instrumented, or gain insight into databases and other in-transaction work that is not automatically instrumented.

To do this, wrap your callbacks in custom tracers. Custom tracers create and collect specific metrics for an additional segment within an existing transaction, such as a particular function or a database call.

  • To instrument individual callbacks, call startSegment() inside the callback, and move the main callback logic to the handler function.
  • To instrument a function that is called inside an asynchronous function, wrap both the target function and its parent asynchronous function with startSegment().

Important

These examples must be placed in code that is running under a transaction. The origin of the transaction, custom or automatically created, does not matter.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.