Attributes, Events, and Metrics
This page covers the API for attaching your own data to New Relic telemetry: custom attributes on transactions and spans, the end-user ID, custom events, and custom metrics. For how attributes are filtered per destination, see Attributes, Privacy, and Security.
addCustomAttribute(key, value)addCustomAttributes(atts)addCustomSpanAttribute(key, value)addCustomSpanAttributes(atts)setUserID(id)recordCustomEvent(eventType, attributes)recordMetric(name, value)incrementMetric(name, value)
Attribute Limits
These limits apply to all custom attributes, as implemented in lib/attributes/:
| Limit | Value |
|---|---|
| Value types | string, number, boolean. Other types (objects, arrays, undefined, null) are dropped with a debug log. |
| Attributes per transaction (custom) | 64. Further new keys are dropped. |
| Attributes per span (custom) | 64, prioritized (see below). |
| Key length | 255 bytes. Longer keys are rejected with Length limit exceeded for attribute name, not adding: <key>. |
| String value length | attributes.value_size_limit (default 256, capped at 4096). Longer values are truncated. |
| Reserved keys | nr_flatten_leading cannot be set (Not overwriting value of NR-only attribute ...). |
Attributes must also pass the include/exclude rules for at least one destination, or they are silently not stored.
addCustomAttribute(key, value)
Adds an attribute to the current transaction and to the currently active span. The most recent value for a key wins.
| Parameter | Type | Description |
|---|---|---|
key |
string | Attribute name. |
value |
string, number, boolean | Attribute value. |
Returns: false when the attribute was refused, otherwise undefined.
It returns false when:
high_securityistrue(logged once:Custom attributes are disabled by high security mode.);api.custom_attributes_enabledisfalse;- there is no active transaction (
No transaction found for custom attributes.); - the key is reserved.
On the transaction, the attribute targets transaction events, transaction traces, error events, and browser monitoring (subject to filters — browser attributes are off by default). On the span, it is added with low priority, so attributes added directly with addCustomSpanAttribute win when the span reaches its 64-attribute limit.
app.get('/cart', (req, res) => {
newrelic.addCustomAttribute('customerTier', req.user.tier)
newrelic.addCustomAttribute('itemCount', req.session.cart.length)
res.render('cart')
})
addCustomAttributes(atts)
Calls addCustomAttribute for each own enumerable property of atts.
newrelic.addCustomAttributes({ region: 'eu-west', experiment: 'B', retries: 2 })
It does not return anything, so you cannot tell which individual keys were refused.
addCustomSpanAttribute(key, value)
Adds an attribute to the current span only (it does not appear on the transaction event). Useful to annotate one specific operation, such as a segment created with startSegment.
Returns: false when refused (high security mode, api.custom_attributes_enabled: false, no active span, reserved key), otherwise undefined.
await newrelic.startSegment('resizeImage', false, async () => {
newrelic.addCustomSpanAttribute('image.width', width)
return resize(file, width)
})
addCustomSpanAttributes(atts)
Calls addCustomSpanAttribute for each own property of atts.
setUserID(id)
Sets the enduser.id agent attribute on the current transaction. It is sent with transaction events, transaction traces, and errors that occur in that transaction.
| Parameter | Type | Description |
|---|---|---|
id |
string | A unique user identifier. |
With an empty id or no transaction, it logs User id is empty or not in a transaction, not assigning `enduser.id` attribute ... and does nothing.
Note: User IDs can be personal data. Prefer an opaque internal ID over an email address.
recordCustomEvent(eventType, attributes)
Records a custom event, queryable with NRQL (SELECT * FROM <eventType>). Events can be recorded inside or outside transactions.
| Parameter | Type | Description |
|---|---|---|
eventType |
string | Event type name. Must match /^[a-zA-Z0-9:_ ]+$/ and be at most 255 characters. |
attributes |
object | A plain object. Keys must be at most 255 characters; values must be string, number, or boolean. |
Returns: false when disabled by high security mode or api.custom_events_enabled: false; otherwise undefined.
newrelic.recordCustomEvent('CheckoutCompleted', {
orderId: order.id,
total: order.total,
currency: 'EUR',
firstPurchase: true
})
Validation details:
- All arguments are checked before giving up, so one call can log several warnings (for example
recordCustomEvent eventType of my-event is invalid, it must match /^[a-zA-Z0-9:_ ]+$/). Any failure means the event is dropped. Note that-and.are not allowed in the type. attributesmust be a plain object; an array ornullis rejected (recordCustomEvent requires an object for its second argument ...).- Attribute values of other types are omitted individually, with an info log
Omitting attribute <key> from <eventType> custom event call, type must be boolean, number, or string. - If
custom_insights_events.enabledisfalse, the call returns silently without any log. - At most
custom_insights_events.max_samples_storedevents (default 3000) are kept per harvest cycle; beyond that, events are sampled by priority. Inside a sampled transaction, the event uses the transaction's priority; outside, a random priority.
recordMetric(name, value)
Records a custom metric named Custom/<name>.
| Parameter | Type | Description |
|---|---|---|
name |
string | Metric name, following New Relic metric naming (segments separated by /). |
value |
number or object | A single measurement, or pre-aggregated statistics. |
When value is a number, it is recorded as one measurement (for example a duration in your own unit).
When value is an object, it must have numeric count, total, min, max, and sumOfSquares; totalExclusive is optional and defaults to total. The statistics are merged with previous values for the same metric. This is useful for aggregating yourself and reporting periodically:
newrelic.recordMetric('Queue/depth', queue.length)
newrelic.recordMetric('Batch/processingTime', {
count: 10,
total: 4.2,
min: 0.2,
max: 0.9,
sumOfSquares: 2.1
})
A non-string name logs Metric name must be a string. A missing statistic logs Metric object must include <key> as a number and records nothing.
incrementMetric(name, value)
Increments the call count of the custom metric Custom/<name>, acting as a counter.
| Parameter | Type | Description |
|---|---|---|
name |
string | Metric name. |
value |
integer | Optional amount. Defaults to 1. 0 is accepted. |
A non-integer value (such as 1.5) logs Metric Increment value must be an integer and is ignored.
newrelic.incrementMetric('Cache/miss')
newrelic.incrementMetric('Emails/sent', batch.length)