Syntax

newrelic.setCustomAttribute(name: string, value: string|number|null[, persist: boolean])

Adds a user-defined attribute name and value to subsequent events on the page.

Requirements

Agent version nr-593 or higher.

For persist parameter or null value support, agent version 1.230.0 or higher is required.

Description

Make this call before the window load event fires (when that data is transmitted) in order for the attributes to be included in the PageView event. Once an attribute is set, the New Relic platform records it with all events until the page is reloaded or the attribute is manually unset.

If you are using SPA monitoring with a compatible agent version, attributes set with this call will also be included in newrelic.interaction events. However, attributes set using the SPA API will take precedence over these attributes.

Errors for custom attributes will be included in events on the JS Errors page. To view or log errors for a custom attribute via API, use the browser API's noticeError call.

With the persist flag, the attribute can also be in stored in the browser, so that subsequent page visits of the same origin within a session span retain it on events. Do note that this functionality may fluctuate depending on end-user browser privacy settings. If this function is called with a value = null, the attribute will be deleted from both the current page's events and the storage, regardless of the persist flag.

Important

Be aware that persisted attributes have precedence over info.jsAttributes keys of the same name! For example, a persisted attribute someName set on somedomain.com/pageA will override any someName that is statically set on somedomain.com/pageB's info block, assuming they share the same (session) storage.

Parameters

Parameter	Description
`name` string	Required. Name of the attribute. Appears as column in the `PageView` event. It will also appear as a column in the `PageAction` event if you are using it. Avoid using reserved NRQL words when you name the attribute/value.
`value` string OR integer OR null	Required. Value of the attribute. Appears as the value in the named attribute column in the `PageView` event. It will appear as a column in the `PageAction` event if you are using it. Custom attribute values cannot be complex objects, only simple types such as Strings and Integers. Passing a `null` value unsets any existing attribute of the same name. Avoid using reserved NRQL words when you name the attribute/value.
`persist` boolean	Optional. If set to `true`, the name-value pair will also be set into the browser's storage API. Then on the following instrumented pages that load within the same session, the pair will be re-applied as a custom attribute. Defaults to `false`.

Parameter

Description

name

string

Required. Name of the attribute. Appears as column in the PageView event. It will also appear as a column in the PageAction event if you are using it.

Avoid using reserved NRQL words when you name the attribute/value.

value

string OR integer OR null

Required. Value of the attribute. Appears as the value in the named attribute column in the PageView event. It will appear as a column in the PageAction event if you are using it. Custom attribute values cannot be complex objects, only simple types such as Strings and Integers.

Passing a null value unsets any existing attribute of the same name.

Avoid using reserved NRQL words when you name the attribute/value.

persist

boolean

Optional. If set to true, the name-value pair will also be set into the browser's storage API. Then on the following instrumented pages that load within the same session, the pair will be re-applied as a custom attribute.

Defaults to false.

Examples

Get JavaScript/jQuery for HTML elements

This example uses JavaScript/jQuery to get the values of the following HTML elements on a Drupal-generated page:

<link rel="shortlink" href="/node/1111" />
<h1>Using NRQL</h1>

New Relic reports them as custom attributes. This is useful to query PageView and PageAction events.

var node_id = jQuery("link[rel='shortlink']").attr("href");
var node_title = jQuery('h1').text();

if (typeof newrelic == 'object') {
  newrelic.setCustomAttribute('nodeId', node_id);
  newrelic.setCustomAttribute('title', node_title);
}