--- title: Collect custom attributes source: https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/collect-custom-attributes --- When it comes to reporting custom data not reported by default by New Relic solutions, two of the most popular solutions are [custom attributes and custom events](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/report-custom-event-data). This doc will go into more detail about why you'd use custom attributes. For some New Relic solutions, one way to [report custom data to New Relic](https://docs.newrelic.com/docs/telemetry-data-platform/custom-data/intro-custom-data) is to use custom [attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/agent-attributes). By adding custom attributes to your data, you can do more in-depth and customized analysis of your business. 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. > #### ⚠️ IMPORTANT > > Custom attributes count toward GB Ingested and are billable data. ## Requirements [#requirements] Custom attributes are available for these New Relic solutions: - APM - Browser monitoring - Mobile monitoring - Infrastructure monitoring - Synthetic monitors We'll go into more detail on these options below. ## Recommendations for creating and using custom attributes [#best-practices] At New Relic, [attributes](https://docs.newrelic.com/docs/new-relic-solutions/get-started/glossary/#attribute) are key-value pairs that provide metadata about the [events](https://docs.newrelic.com/docs/new-relic-solutions/get-started/glossary/#event) they're attached to. A common pattern when creating custom attributes is to capture user information, such as name, ID, email, and more. This allows you to create an association between your operational data and your business data. For example, if you have the user information, you tie together your service desk and CRM data with the operational data in New Relic. Other types of business context might include: - Customer token - Customer market segment - Customer value classification - Workflow control values not obvious in the URIStem - User/product/account privilege context Operational context might include: - Which feature flags were used - What datastore was accessed - What cache was accessed - What errors were detected and ignored (fault partitioning) Once you add a custom attribute, you can query it in New Relic and create custom charts from that data. For example, if you used the [Java agent API](#java-att) to add a `userId` attribute to your `Transaction` and `TransactionError` events, you could then create a NRQL query using that attribute, like: ```sql SELECT count(*) FROM TransactionError WHERE userId = '1401961100' FACET dateOf(timestamp), `error.message` SINCE 1 week ago ``` ## APM: Record custom attributes [#enabling-custom] > #### ⚠️ IMPORTANT > > Review the list of [reserved terms used by NRQL](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/data-requirements-limits-custom-event-data/#reserved-words). Using reserved terms can cause issues. To enable and use custom attributes for APM, follow the procedure for your APM agent: **Go** Custom attribute collection is enabled by default in the Go agent. However, you can [disable custom attribute collection](https://docs.newrelic.com/docs/agents/go-agent/instrumentation/go-agent-attributes#change-attribute-destination). **Java** 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. Note that collecting custom attributes requires that the [New Relic Java API jar](https://docs.newrelic.com/docs/apm/agents/java-agent/api-guides/guide-using-java-agent-api) be in the application's classpath. | 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](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-custom-instrumentation-xml-examples). - From your `Extensions` directory within the New Relic Java agent, create a single [XML file](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-xml). - Define the methods you want New Relic to monitor by [editing your XML file](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-xml) directly. - Define an XML instrumentation file using the [New Relic UI](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/custom-instrumentation-editor-quickly-customize-your-java-instrumentation). This may require additional config in the `common:` block of your **newrelic.yml**. See **Report custom attributes** under [Instrumentation options](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/custom-instrumentation-editor-instrument-ui#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`](https://docs.newrelic.com/docs/agents/java-agent/attributes/enabling-and-disabling-attributes#cfg-attributes-include) and [`attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/attributes/enabling-and-disabling-attributes#cfg-attributes-exclude). For example, to record a variable named `userId`, include this code in the parent method: ```java 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`](https://docs.newrelic.com/docs/agents/java-agent/attributes/enabling-and-disabling-attributes#cfg-attributes-include) and [`span_events.attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/attributes/enabling-and-disabling-attributes#cfg-attributes-exclude). For example, to record a variable named `userId` on the current span, include this code in the associated method: ```java NewRelic.getAgent().getTracedMethod().addCustomAttribute("userId", userId); ``` | | Collect user attributes | The Java agent also includes a built-in mechanism to [enable user attributes](https://docs.newrelic.com/docs/agents/java-agent/attributes/enabling-disabling-attributes-java#user-attributes) and collect user information from `HttpServletRequest.getUserPrincipal()` as custom attributes. | **.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 [`AddCustomAttribute`](https://docs.newrelic.com/docs/apm/agents/net-agent/net-agent-api/net-agent-api/#AddCustomAttribute). 2. Optional: Include or exclude attributes with the [`include`](https://docs.newrelic.com/docs/agents/net-agent/installation-configuration/net-agent-configuration#agent-attributes-include) and [`exclude`](https://docs.newrelic.com/docs/agents/net-agent/installation-configuration/net-agent-configuration#agent-attributes-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: ```cs IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); ITransaction transaction = agent.CurrentTransaction; transaction .AddCustomAttribute("Discount Code", "Summer Super Sale") .AddCustomAttribute("Item Code", 31456); ``` **Node.js** 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`](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/api-guides/nodejs-agent-api/#add-custom-attribute). - To record multiple attributes using a single call, use [`newrelic.addCustomAttributes`](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/api-guides/nodejs-agent-api/#add-custom-attributes). For example, to record attributes for a coupon code and an item ID code, you could include this in the parent method: ```js newrelic.addCustomAttributes({ "Discount Code": "Summer Super Sale", "Item Code": 31456 }); ``` **PHP** 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`](https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelic_add_custom_parameter/) for transaction events and spans - [`newrelic_add_custom_span_parameter`](https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelicaddcustomspanparameter-php-agent-api/) for only spans For example, to record a variable named `$userId`, include this code in the parent method: ```php newrelic_add_custom_parameter ('userID', $userId) ``` **Python** Custom attribute collection is enabled by default in Python. To collect custom attributes, call [`add_custom_attribute`](https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/addcustomattribute-python-agent-api/) 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: ````python newrelic.agent.add_custom_attribute('user_id', user_id) ``` ```` **Ruby** Custom attribute collection is enabled by default in Ruby. To collect custom attributes, call the [`add_custom_attributes`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#add_custom_attributes-instance_method) method. For example, to record a variable named `@user_id`, include this code in the parent method: ````ruby ::NewRelic::Agent.add_custom_attributes({ user_id: @user.id }) ``` ```` ## Browser monitoring: Record custom attributes [#collecting_browser] The browser agent provides an API to specify extra details associated with browser events across a page load, either by [forwarding attributes from APM to browser monitoring](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/insert-data-via-new-relic-browser#custom-attribute-forward-apm) or by [specifying custom attributes through JavaScript](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/set-custom-attribute). Values forwarded from the APM agent are encoded and injected into browser attributes by our browser agent. ## Infrastructure monitoring: Record custom attributes [#collecting_browser] Our [Infrastructure monitoring](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/getting-started/welcome-new-relic-infrastructure) lets you create [custom attributes](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/configuration/configure-infrastructure-agent#attributes) that are used to annotate the data from the infrastructure agent. You can use this metadata to filter your entities, group your results, and annotate your data. ## Mobile monitoring: Record custom attributes [#collecting_mobile] Mobile agents include API calls to record custom attributes: - For an overview of mobile monitoring custom data, see [Insert custom events and attributes](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-events/insert-custom-events-attributes-mobile-data) - Android method: [`setAttribute`](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/) - iOS method: [`setAttribute`](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/) ## Synthetic monitors: Record custom attributes [#synthetics] See [Synthetic monitor custom attributes](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/add-custom-attributes-synthetic-monitoring-data).