• EnglishEspañol日本語한국어Português
  • Log inStart now

Node.js v1 custom instrumentation (legacy)

New Relic for Node.js automatically instruments most standard web requests, but sometimes you want expanded instrumentation. With custom instrumentation, you can instrument web sockets, background jobs, and unsupported databases. Custom instrumentation can also target specific sections of your code for deeper insight.

Custom instrumentation is available in versions 1.10.0 or higher of the Node.js agent. To take advantage of the latest Node.js agent features, upgrade your agent.

Instrumenting web transactions

To instrument web transactions, such as websocket requests, create a custom transaction. Creating a custom transaction gives you the same type of visibility into that custom transaction that you would get from a transaction that the agent automatically instruments.

  1. Wrap the handler you want to instrument with createWebTransaction().
  2. Ensure you call endTransaction() at the end of the transaction.


Do not use brackets [suffix] at the end of your transaction name. New Relic automatically strips brackets from the name. Instead, use parentheses (suffix) or other symbols if needed.

Instrumenting background transactions

You can also use custom transactions to instrument background tasks, such as periodic jobs within your app or work that continues after a request completes. To instrument background tasks, wrap the handler you want to instrument with createBackgroundTransaction(). Ensure you call endTransaction() at the end of the transaction.

Expanding instrumentation within transactions

You can also use custom instrumentation to provide more visibility into web transactions that are already instrumented, or to 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 callbacks, wrap the callback with createTracer(). If you want to instrument a function that is called inside an asynchronous function, you need to wrap both the target function and its parent asynchronous function with createTracer().


You must place these examples inside an already instrumented transaction. The transaction can be automatically instrumented, or via a custom transaction.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.