Collect custom attributes

For some New Relic solutions, one way to report custom data to New Relic is to use custom attributes. For example, for New Relic browser monitoring, you might create a custom attribute to track the user name associated with a slow or failing request.

Requirements

Custom attributes are available for these New Relic solutions:

APM
Browser monitoring
Mobile monitoring
Infrastructure monitoring

For other custom data solutions, see Intro to custom data.

APM: Record custom attributes

Important

Review the list of reserved terms used by NRQL. Using reserved terms can cause issues.

To enable and use custom attributes for APM, follow the procedure for your APM agent:

Custom attribute collection is enabled by default in Java. You can collect custom attributes using XML and the Java agent APIs. These two methods can be used in conjunction with each other.

Method	How to do it
Specify attributes in XML	XML allows you to specify custom attributes without changing any of your source code. You can have multiple XML files for custom attributes that are grouped by some logical facet. To set custom attributes for your Java app via XML: Review the New Relic Java agent's documentation about XML file format, methods and classes, and examples. From your `Extensions` directory within the New Relic Java agent, create a single XML file. Define the methods you want New Relic to monitor by editing your XML file directly. Define an XML instrumentation file using the New Relic UI. This may require additional config in the `common:` block of your newrelic.yml. See Report custom attributes under Instrumentation options for more detail.
Call the agent's API	Example 1: Adding custom attributes to transactions To collect custom attributes using the agent's API, call the relevant methods: For each method you want to record an attribute for, call `NewRelic.addCustomParameter(...)`. Optional: Include or exclude certain attributes with `attributes.include` and `attributes.exclude`. For example, to record a variable named `userId`, include this code in the parent method: `NewRelic.addCustomParameter("userId", userId);` Example 2: Adding custom attributes to spans in distributed traces To collect custom attributes using the agent's API, call the relevant methods: For each span (currently executing method) that you want to record an attribute for, call `NewRelic.getAgent().getTracedMethod().addCustomAttribute(...)`. Optional: Include or exclude certain attributes with `span_events.attributes.include` and `span_events.attributes.exclude`. For example, to record a variable named `userId` on the current span, include this code in the associated method: `NewRelic.getAgent().getTracedMethod().addCustomAttribute("userId", userId);`
Collect user attributes	The Java agent also includes a built-in mechanism to enable user attributes and collect user information from `HttpServletRequest.getUserPrincipal()` as custom attributes.

Method

How to do it

Specify attributes in XML

XML allows you to specify custom attributes without changing any of your source code. You can have multiple XML files for custom attributes that are grouped by some logical facet.

To set custom attributes for your Java app via XML:

Review the New Relic Java agent's documentation about XML file format, methods and classes, and examples.
From your Extensions directory within the New Relic Java agent, create a single XML file.
Define the methods you want New Relic to monitor by editing your XML file directly.
Define an XML instrumentation file using the New Relic UI. This may require additional config in the common: block of your newrelic.yml. See Report custom attributes under Instrumentation options for more detail.

Call the agent's API

Example 1: Adding custom attributes to transactions

To collect custom attributes using the agent's API, call the relevant methods:

For each method you want to record an attribute for, call NewRelic.addCustomParameter(...).
Optional: Include or exclude certain attributes with attributes.include and attributes.exclude.
For example, to record a variable named userId, include this code in the parent method:
```
NewRelic.addCustomParameter("userId", userId);
```
Example 2: Adding custom attributes to spans in distributed traces
To collect custom attributes using the agent's API, call the relevant methods:
For each span (currently executing method) that you want to record an attribute for, call NewRelic.getAgent().getTracedMethod().addCustomAttribute(...).
Optional: Include or exclude certain attributes with span_events.attributes.include and span_events.attributes.exclude.
For example, to record a variable named userId on the current span, include this code in the associated method:
```
NewRelic.getAgent().getTracedMethod().addCustomAttribute("userId", userId);
```

Collect user attributes

The Java agent also includes a built-in mechanism to enable user attributes and collect user information from HttpServletRequest.getUserPrincipal() as custom attributes.

Custom attribute collection is enabled by default in .NET. To collect custom attributes, call the relevant API methods:

For each method for which you want to record an attribute, call AddCustomAttribute.

Optional: Include or exclude attributes with the include and exclude configuration options.

For example, to record attributes for a coupon code (string) and an item ID code (number), you could include this code in the parent method:

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;

transaction
    .AddCustomAttribute("Discount Code", "Summer Super Sale")
    .AddCustomAttribute("Item Code", 31456);

Custom attribute collection is enabled by default in Node.js. To collect custom attributes, call the relevant API method:

For each attribute you want to record, call newrelic.addCustomAttribute.
To record multiple attributes using a single call, use newrelic.addCustomAttributes.
For example, to record attributes for a coupon code and an item ID code, you could include this in the parent method:
```
newrelic.addCustomAttributes({
  "Discount Code": "Summer Super Sale",
  "Item Code": 31456
});
```

Custom attribute collection is enabled by default in PHP. To collect custom attributes, call the relevant API method for each method that you want to record an attribute;

newrelic_add_custom_parameter for transaction events and spans
newrelic_add_custom_span_parameter for only spans
For example, to record a variable named $userId, include this code in the parent method:
```
newrelic_add_custom_parameter ('userID', $userId)
```

Custom attribute collection is enabled by default in Python. To collect custom attributes, call add_custom_parameter for each method that you want to record an attribute.

For example, to record a variable named user_id, include this code in the parent method:

newrelic.agent.add_custom_parameter('user_id', user_id)

Custom attribute collection is enabled by default in Ruby. To collect custom attributes, call the relevant API methods:

For Ruby agent version 3.12.0 or higher, use the add_custom_attributes method. For example, to record a variable named @user_id, include this code in the parent method:
```
::NewRelic::Agent.add_custom_attributes({ user_id: @user.id })
```
For Ruby agent version 3.11.2 or lower, use the add_custom_parameters method. For example, to record a variable named @user_id, include this code in the parent method:
```
::NewRelic::Agent.add_custom_parameters({ user_id: @user.id })
```

Browser monitoring: Record custom attributes

The browser agent provides an API to specify extra details associated with a page view or browser interaction, either by forwarding attributes from APM to browser monitoring or by specifying custom attributes through JavaScript. Values forwarded from the APM agent are encoded and injected into browser attributes by our browser agent.

Infrastructure monitoring: Record custom attributes

Our Infrastructure monitoring lets you create custom attributes that are used to annotate the data from the infrastructure agent. You can use this metadata to build filter sets, group your results, and annotate your data.

Mobile monitoring: Record custom attributes

Mobile agents include API calls to record custom attributes:

For an overview of mobile monitoring custom data, see Insert custom events and attributes
Android method: setAttribute
iOS method: setAttribute

Requirements

APM: Record custom attributes

Important

C SDK

Go

Java

.NET

Node.js

PHP

Python

Ruby

Browser monitoring: Record custom attributes

Infrastructure monitoring: Record custom attributes

Mobile monitoring: Record custom attributes