API

Add a custom attribute to the current transaction. Some attributes are reserved (see CUSTOM_DENYLIST for the current, very short list), and as with most API methods, this must be called in the context of an active transaction. Most recently set value wins.

Adds all custom attributes in an object to the current transaction.

See documentation for newrelic.addCustomAttribute for more information on setting custom attributes.

An example of setting a custom attribute object:

newrelic.addCustomAttributes({test: 'value', test2: 'value2'});

Add a custom span attribute to the current transaction. Some attributes are reserved (see CUSTOM_DENYLIST for the current, very short list), and as with most API methods, this must be called in the context of an active segment/span. Most recently set value wins.

Add custom span attributes in an object to the current segment/span.

See documentation for newrelic.addCustomSpanAttribute for more information.

An example of setting a custom span attribute:

newrelic.addCustomSpanAttribute({test: 'value', test2: 'value2'})

If the URL for a transaction matches the provided pattern, ignore the transaction attached to that URL. Useful for filtering socket.io connections and other long-polling requests out of your agents to keep them from distorting an app's apdex or mean response time. Pattern may be a (standard JavaScript) RegExp or a string.

Example:

newrelic.addIgnoringRule('^/socket\.io/')

If the URL for a transaction matches the provided pattern, name the transaction with the provided name. If there are capture groups in the pattern (which is a standard JavaScript regular expression, and can be passed as either a RegExp or a string), then the substring matches ($1, $2, etc.) are replaced in the name string. BE CAREFUL WHEN USING SUBSTITUTION. If the replacement substrings are highly variable (i.e. are identifiers, GUIDs, or timestamps), the rule will generate too many metrics and potentially get your application blocked by New Relic.

An example of a good rule with replacements:

newrelic.addNamingRule('^/storefront/(v[1-5])/(item|category|tag)', 'CommerceAPI/$1/$2')

An example of a bad rule with replacements:

newrelic.addNamingRule('^/item/([0-9a-f]+)', 'Item/$1')

Keep in mind that the original URL and any query parameters will be sent along with the request, so slow transactions will still be identifiable.

Naming rules can not be removed once added. They can also be added via the agent's configuration. See configuration documentation for details.

End the current web or background custom transaction. This method requires being in the correct transaction context when called.

Get the script header necessary for Browser Monitoring This script must be manually injected into your templates, as high as possible in the header, but after any X-UA-COMPATIBLE HTTP-EQUIV meta tags. Otherwise you may hurt IE!

By default this method will return a script wrapped by <script> tags, but with option hasToRemoveScriptWrapper it can send back only the script content without the <script> wrapper. Useful for React component based frontend.

This method must be called every time you want to generate the headers.

Do not reuse the headers between users, or even between requests.

This method returns an object with the following keys/data:

• trace.id: The current trace ID
• span.id: The current span ID
• entity.name: The application name specified in the connect request as app_name. If multiple application names are specified this will only be the first name
• entity.type: The string "SERVICE"
• entity.guid: The entity ID returned in the connect reply as entity_guid
• hostname: The hostname as specified in the connect request as utilization.full_hostname. If utilization.full_hostname is null or empty, this will be the hostname specified in the connect request as host.

Returns the current trace and span id.

This method returns an object with the following methods:

• end: end the transaction that was active when API#getTransaction was called.

• ignore: set the transaction that was active when API#getTransaction was called to be ignored.

Create or update a custom metric that acts as a simple counter. The count of the given metric will be incremented by the specified amount, defaulting to 1.

Registers an instrumentation function.

• newrelic.instrument(moduleName, onRequire [,onError])
• newrelic.instrument(options)

Registers an instrumentation function.

• newrelic.instrumentConglomerate(moduleName, onRequire [, onError])
• newrelic.isntrumentConglomerate(options)

Registers an instrumentation function.

• newrelic.instrumentDatastore(moduleName, onRequire [,onError])
• newrelic.instrumentDatastore(options)

Applies an instrumentation to an already loaded CommonJs module.

Note: This function will not work for ESM packages.

// oh no, express was loaded before newrelic const express = require('express') const newrelic = require('newrelic')

// phew, we can use instrumentLoadedModule to make // sure express is still instrumented newrelic.instrumentLoadedModule('express', express)

Registers an instrumentation function for instrumenting message brokers.

• newrelic.instrumentMessages(moduleName, onRequire [,onError])
• newrelic.instrumentMessages(options)

Registers an instrumentation function.

• newrelic.instrumentWebframework(moduleName, onRequire [,onError])
• newrelic.instrumentWebframework(options)

Send errors to New Relic that you've already handled yourself. Should be an Error or one of its subtypes, but the API will handle strings and objects that have an attached .message or .stack property.

An example of using this function is

try { performSomeTask(); } catch (err) { newrelic.noticeError( err, {extraInformation: "error already handled in the application"}, true ); }

NOTE: Errors that are recorded using this method do not obey the ignore_status_codes configuration.

Obfuscates SQL for a given database engine.

Record custom event data which can be queried in New Relic Insights.

Record a LLM feedback event which can be viewed in New Relic API Monitoring.

Sends an application log message to New Relic. The agent already automatically does this for some instrumented logging libraries, but in case you are using another logging method that is not already instrumented by the agent, you can use this function instead.

If application log forwarding is disabled in the agent configuration, this function does nothing.

An example of using this function is

newrelic.recordLogEvent({ message: 'cannot find file', level: 'ERROR', error: new SystemError('missing.txt') })

Record a custom metric, usually associated with a particular duration. The name must be a string following standard metric naming rules. The value will usually be a number, but it can also be an object. When value is a numeric value, it should represent the magnitude of a measurement associated with an event; for example, the duration for a particular method call. When value is an object, it must contain count, total, min, max, and sumOfSquares keys, all with number values. This form is useful to aggregate metrics on your own and report them periodically; for example, from a setInterval. These values will be aggregated with any previously collected values for the same metric. The names of these keys match the names of the keys used by the platform API.

Give the current transaction a name based on your own idea of what constitutes a controller in your Node application. Also allows you to optionally specify the action being invoked on the controller. If the action is omitted, then the API will default to using the HTTP method used in the request (e.g. GET, POST, DELETE). Overrides any New Relic naming rules set in configuration or from New Relic's servers.

IMPORTANT: this function must be called when a transaction is active. New Relic transactions are tied to web requests, so this method may be called from within HTTP or HTTPS listener functions, Express routes, or other contexts where a web request or response object are in scope.

Specify the Dispatcher and Dispatcher Version environment values. A dispatcher is typically the service responsible for brokering the request with the process responsible for responding to the request. For example Node's http module would be the dispatcher for incoming HTTP requests.

Function for adding a custom callback to generate Error Group names, which will be used by the Errors Inbox to group similar errors together via the error.group.name agent attribute.

Provided functions must return a string, and receive an object as an argument, which contains information related to the Error that occurred, and has the following format:

{
  customAttributes: object,
  'request.uri': string,
  'http.statusCode': string,
  'http.method': string,
  error: Error,
  'error.expected': boolean
}

Calling this function multiple times will replace previously defined functions

Registers a callback which will be used for calculating token counts on Llm events when they are not available. This function will typically only be used if ai_monitoring.record_content.enabled is false and you want to still capture token counts for Llm events.

Provided callbacks must return an integer value for the token count for a given piece of content.

Give the current transaction a custom name. Overrides any New Relic naming rules set in configuration or from New Relic's servers.

IMPORTANT: this function must be called when a transaction is active. New Relic transactions are tied to web requests, so this method may be called from within HTTP or HTTPS listener functions, Express routes, or other contexts where a web request or response object are in scope.

Assigns enduser.id attribute on transaction and trace events. It will also assign the attribute to errors if they occur within a transaction.

Shuts down the agent.

Creates and starts a background transaction to record work done in the handle supplied. This transaction will run until the handle synchronously returns UNLESS:

1. The handle function returns a promise, where the end of the transaction will be tied to the end of the promise returned.
2. API#getTransaction is called in the handle, flagging the transaction as externally handled. In this case the transaction will be ended when TransactionHandle#end is called in the user's code.

Wraps the given handler in a segment which may optionally be turned into a metric.

Creates and starts a web transaction to record work done in the handle supplied. This transaction will run until the handle synchronously returns UNLESS:

1. The handle function returns a promise, where the end of the transaction will be tied to the end of the promise returned.
2. API#getTransaction is called in the handle, flagging the transaction as externally handled. In this case the transaction will be ended when TransactionHandle#end is called in the user's code.