Collect custom attributes

New Relic allows you to collect standard attributes, as well as custom attributes, to several destinations. For example, you may want to track the user name associated with a slow or failing request.

Enable attributes for APM

To enable and use custom attributes for New Relic APM and New Relic Insights, follow the procedure for your agent.

Before creating custom attributes, review New Relic's list of reserved terms used by NRQL and Insights. Otherwise unexpected results may occur.

Go

Custom attribute collection is enabled by default in the Go agent. To learn how to turn off custom attribute collection, see Change attribute destination.

Java

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

Via 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:

  1. From your Extensions directory within the New Relic Java agent, create a single XML file.
  2. Define the methods you want New Relic to monitor by editing your XML file directly.
  3. Define an XML instrumentation file via the New Relic UI.

For more information about file format, methods and classes, and examples, see Java custom instrumentation by XML examples.

Via agent API

To collect custom attributes via API, call the relevant methods:

  1. For each method you want to record an attribute, call addCustomParameter.
  2. 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);
.NET

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

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

    To record a number (for example, to use with Insights functions operating on numeric values such as min(), max(), histogram(), etc.), be sure to convert this to a Single. Other numeric values will be converted to strings.

  2. 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 (Single number), you could include this code in the parent method:

NewRelic.Api.Agent.AddCustomParameter("Discount Code", "Summer Super Sale");
NewRelic.Api.Agent.AddCustomParameter("Item Code", (Single)31456);
Node.js

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

  1. For each attribute you wish to record, call newrelic.addCustomParameter.
  2. To record multiple attributes using a single call, use newrelic.addCustomParameters.

For example, to record atttributes for a coupon code and an item ID code, you could include this in the parent method:

newrelic.addCustomParameters({
  "Discount Code": "Summer Super Sale",
  "Item Code": 31456
});
PHP

Custom attribute collection is enabled by default in PHP. To collect custom attributes, simply call the relevant API methods (newrelic_add_custom_parameter) for each method for which you want to record an attribute.

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

newrelic_add_custom_parameter ('userID', $userId)
Python

Custom attribute collection is enabled by default in Python. To collect custom attributes, call add_custom_parameter for each method for which 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)
Ruby

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

For 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 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 })

Record custom attributes from APM

Anywhere in the code that handles a web transaction in your application, you can call an API to define custom attributes. For more information, refer to the API documentation for your agent:

Record custom attributes from Browser

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

Record custom attributes from Infrastructure

New Relic Infrastructure lets you create custom attributes used to annotate the data from the Infrastructure agent. You can use this metadata to build filter sets, group your results, and annotate your Insights data. For more information, see Infrastructure custom attributes.

For more help

Additional documentation resources include:

Join the discussion about New Relic APM in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.