--- title: Guide to using the Node.js agent API source: https://docs.newrelic.com/docs/apm/agents/nodejs-agent/api-guides/guide-using-nodejs-agent-api --- Our [Node.js agent](https://docs.newrelic.com/docs/agents/nodejs-agent/installation-configuration/install-nodejs-agent) API allows you to extend the agent's standard functionality. You can use this API to: - Create custom transaction parameters - Report custom errors and metrics You can also use the API for [custom instrumentation](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-custom-instrumentation). For [supported frameworks](https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent), the agent instruments most activity automatically. Custom instrumentation lets you extend that monitoring to frameworks without default instrumentation. Other resources: - The [Node.js agent API documentation on GitHub](https://newrelic.github.io/node-newrelic/API.html). - [Example applications using custom instrumentation](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/custom-instrumentation). - You can also adjust the Node.js agent's default behavior with [configuration settings](https://docs.newrelic.com/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration). ## Requirements To use the Node.js agent API, make sure you have the [latest Node.js agent release](https://docs.newrelic.com/docs/release-notes/agent-release-notes/nodejs-release-notes). In addition, see: - [Node.js agent API requirements](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-agent-api) - [Getting started procedures](http://newrelic.github.io/node-newrelic/index.html) on GitHub ## Instrument missing sections of your code with transactions [#creating-transactions] To instrument your app, New Relic separates each path through your code into its own [transaction](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction). New Relic times (or "instruments") the parent method in these transactions to measure your app's overall performance, and collects [transaction traces](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/introduction-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()`](https://newrelic.github.io/node-newrelic/API.html#startWebTransaction). | | Stop timing a method after its work is completed | Use either of these options: - Return a promise from the callback handed to [`newrelic.startWebTransaction`](https://newrelic.github.io/node-newrelic/API.html#startWebTransaction). - Call `end` on a [handle](https://newrelic.github.io/node-newrelic/TransactionHandle.html) (GitHub) returned from [`newrelic.getTransaction`](https://newrelic.github.io/node-newrelic/API.html#getTransaction). | | Prevent a transaction from reporting to New Relic | Ignore the transaction using any of these options: - See [Rules for ignoring requests](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-agent-api#ignoring)`.` - Call `ignore()` on a [handle](http://newrelic.github.io/node-newrelic/TransactionHandle.html) (GitHub) returned from [`newrelic.getTransaction`](https://newrelic.github.io/node-newrelic/API.html#getTransaction). | For more information about create custom web transactions, see the [startWebTransaction example on GitHub](https://github.com/newrelic/newrelic-node-examples/tree/0a036fd669b4b47b8afbc7add8696980f799f0da/custom-instrumentation/start-web-transaction). ## Time specific methods using segments [#segments] If a transaction is already visible in New Relic, 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. To time a particular method, see [newrelic.startSegment](https://newrelic.github.io/node-newrelic/API.html#startSegment). For more information about timing, see the [custom instrumentation example on GitHub](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/custom-instrumentation/segments). ## Enhance the metadata of a transaction [#metadata] Sometimes the code you are targeting is visible in New Relic, but some details of the method are not useful. For example: - The default name might not be helpful. (Perhaps it is causing a [metric grouping issue](https://docs.newrelic.com/docs/agents/manage-apm-agents/troubleshooting/metric-grouping-issues#video).) - You want to add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes) to your transactions so you can filter them . Use these methods when you want to change how New Relic instruments a transaction that's already visible in New Relic: | If you want to... | Do this... | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Change the name of a transaction | See [`newrelic.setTransactionName`](https://newrelic.github.io/node-newrelic/API.html#setTransactionName) and [`rules.name`](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-agent-api#rules-name). | | Add metadata (such as your customer’s account name or subscription level) to your transactions | Use [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes#nodejs-att). (Custom attribute collection is enabled by default in the Node.js agent.) See [`newrelic.addCustomAttribute()`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttribute) and [`newrelic.addCustomAttributes()`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttributes). For more information, see the [example application](https://github.com/newrelic/newrelic-node-examples/tree/69d500e02077d2565c4762c21bf779e3e39845bf/custom-instrumentation/attributes-events-metrics) on GitHub. | | Create a new transaction for background work | See [`newrelic.startBackgroundTransaction()`](https://newrelic.github.io/node-newrelic/API.html#startBackgroundTransaction) and [example application](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/custom-instrumentation/background-transactions) on GitHub. | | Create a new web transaction | Use [`newrelic.startWebTransaction()`](https://newrelic.github.io/node-newrelic/API.html#startWebTransaction). | | Prevent a transaction from affecting your [Apdex](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#apdex) score | See [Rules for naming and ignoring requests](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-agent-api#ignoring), including the [ignoring rules example](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-agent-api#example-ignoring-rule). | | Record other performance data, such as timing or computer resource data | Use [`recordMetric`](https://newrelic.github.io/node-newrelic/API.html#recordMetric) or [`incrementMetric`](https://newrelic.github.io/node-newrelic/API.html#incrementMetric). | ## See related logs [#logs] The agent by default sends logs directly within the context of your application's errors and traces. For more information about correlating log data with other telemetry data and supported frameworks, see [our logs in context docs](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-nodejs). If you're using a logging mechanism that's not instrumented by New Relic, you may instead directly use this API call to record and forward your logs in context: - [`newrelic.recordLogEvent`](https://newrelic.github.io/node-newrelic/API.html#recordLogEvent) An older alternative method is to use your own log forwarder instead of letting the agent do the forwarding for you. In this case, you'll need to annotate your logs with the proper context before you forward them. Use these API calls: - [`newrelic.getTraceMetadata`](https://newrelic.github.io/node-newrelic/API.html#getTraceMetadata) - [`newrelic.getLinkingMetadata`](https://newrelic.github.io/node-newrelic/API.html#getLinkingMetadata) ## Instrument asynchronous work [#async] For [supported frameworks](https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent#supported-frameworks) and [supported Node.js versions](https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent#version), 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`](https://newrelic.github.io/node-newrelic/API.html#startSegment). | | Trace an async method that New Relic is not instrumenting | See [`newrelic.startSegment`](https://newrelic.github.io/node-newrelic/API.html#startSegment). | | Trace a transaction that got lost | See [`newrelic.startSegment`](https://newrelic.github.io/node-newrelic/API.html#startSegment). You can also create your own [custom instrumentation](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-custom-instrumentation) for libraries that are losing your transactions. | ## Instrument calls to external services [#external-services] Once the [request naming API](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-agent-api#loading) 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: - [Custom instrumentation API](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-agent-api#custom-instrumentation-api) - [Message queues](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/message-queues) Also see the [datastore](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/custom-instrumentation/instrument-datastore) and [message shim](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/custom-instrumentation/instrument-messages) example applications on GitHub. | | Connect activity to another app instrumented by a New Relic agent | Use [distributed tracing](https://docs.newrelic.com/docs/enable-distributed-tracing). For more information on manually inserting and accepting distributed tracing headers, see the [example application](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/custom-instrumentation/distributed-tracing) on GitHub. | | See the path that a request takes as it travels through a distributed system. | [Distributed tracing](https://docs.newrelic.com/docs/agents/enable-distributed-tracing) | ## Collect or ignore errors [#errors] Usually the agent detects errors automatically. However, you can manually mark an error with the agent. You can also mark errors as [ignored](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/ignoring-errors-new-relic-apm). For more information on using the API methods to log, group, and associate errors, use the [example application](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/error-fingerprinting) on GitHub. | If you want to... | Do this... | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Report an error the agent does not report automatically | See [`newrelic.noticeError()`](https://newrelic.github.io/node-newrelic/API.html#noticeError). | | Group errors by name, using a custom filter function you define | See [`newrelic.setErrorGroupCallback()`](https://newrelic.github.io/node-newrelic/API.html#setErrorGroupCallback). | | Associate errors with users | See [`newrelic.setUserID()`](https://newrelic.github.io/node-newrelic/API.html#setUserID). | ## Send custom event and metric data from your app [#custom-data] New Relic includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see [Data collection](https://docs.newrelic.com/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-data). For more information on using the API methods below, use the [example application](https://github.com/newrelic/newrelic-node-examples/tree/69d500e02077d2565c4762c21bf779e3e39845bf/custom-instrumentation/attributes-events-metrics) on GitHub. | If you want to... | Do this... | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Send data about an event so you can analyze it in New Relic | Create a [custom event](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/insert-custom-events-new-relic-apm-agents#node-att). See [`newrelic.recordCustomEvent()`](https://newrelic.github.io/node-newrelic/API.html#recordCustomEvent). | | Tag your events with metadata to filter and facet them | Add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes#nodejs=att) if needed. (Custom attribute collection is enabled by default in the Node.js agent.) See [`newrelic.addCustomAttribute()`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttribute) and [`newrelic.addCustomAttributes()`](https://newrelic.github.io/node-newrelic/API.html#addCustomAttributes). | | Report custom performance data | Create a [custom metric](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics). See [`newrelic.recordMetric()`](https://newrelic.github.io/node-newrelic/API.html#recordMetric) and [`newrelic.incrementMetric()`](https://newrelic.github.io/node-newrelic/API.html#incrementMetric). To view the data, use [**metrics and events**](https://docs.newrelic.com/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer). | ## Control the browser agent [#browser] Usually the browser monitoring agent is added automatically to your pages or deployed by copy/pasting the JavaScript snippet. For more information about these recommended methods, see [Add browser apps to New Relic](https://docs.newrelic.com/docs/browser/new-relic-browser/installation-configuration/add-apps-new-relic-browser). You can also control the browser agent via APM agent API calls. For more information, see [Browser monitoring and the Node.js agent](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/new-relic-browser-nodejs-agent). ## Extend custom instrumentation [#custom-instrumentation] For more information about using the custom instrumentation APIs, see [Node.js custom instrumentation](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/extend-your-instrumentation/nodejs-custom-instrumentation/). To add custom instrumentation in ES module applications, please refer to our [ES module](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/es-modules) documentation or [example application](https://github.com/newrelic/newrelic-node-examples/tree/4284ee7eab69708238db0a44f97ff7e839e165cf/esm-app) in GitHub.