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:
- Create web transactions (useful for things like web sockets, where transactions can't be automatically created).
- Create non-web background transactions (useful for recording background jobs).
- Target specific sections of your code for deeper analysis.
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, see the example application 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, see the example application 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, see the example application on GitHub.
Instrument web transactions
In order to create custom web transactions, call startWebTransaction to start the transaction. For more information, see the example application on GitHub.
The linked example application only gives basic timing data for the transaction created. To create more intricate timing data and transaction naming for a particular framework, see the Node.js API docs and the related WebFramework example application on GitHub.
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. For more information, see the example application on GitHub.
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. For more information, see the example application on GitHub.