--- title: Java agent attributes source: https://docs.newrelic.com/docs/apm/agents/java-agent/attributes/java-agent-attributes --- New Relic [attributes](https://docs.newrelic.com/docs/features/agent-attributes) are key-value pairs containing information that determines the properties of an event or transaction. These key-value pairs can help you gain greater insight into your application and annotate the data when [you query it](https://docs.newrelic.com/docs/query-your-data/explore-query-data/explore-data/introduction-querying-new-relic-data). You can also automatically [forward user information to New Relic](#). Both default and [custom](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes) attributes are visible in APM transaction traces, distributed traces, and error analytics; [APM events](https://docs.newrelic.com/docs/insights/explore-data/attributes/apm-default-attributes-insights) and [Browser events](https://docs.newrelic.com/docs/insights/explore-data/attributes/browser-default-attributes-insights#browser-attributes-table) in [dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-new-relic-one-dashboards). You can customize exactly which attributes will be sent to each of these destinations. This document describes the Java agent attributes, details how to enable or disable attributes, and describes the rules the agent follows to determine which attributes to include or exclude for a [destination](https://docs.newrelic.com/docs/features/agent-attributes#destinations). > #### 💡 TIP > > These attribute settings apply to version 3.7.0 or higher of the Java agent. If you use an older version of the agent, see [Update legacy attribute configuration](https://docs.newrelic.com/docs/agents/java-agent/troubleshooting/update-legacy-attribute-configuration). ## Java-specific attributes [#attributes] In addition to the [default APM attributes](https://docs.newrelic.com/docs/insights/new-relic-insights/decorating-events/apm-default-attributes-insights#transaction-defaults), the Java agent collects attributes from these sources: **HTTP response codes** The response status code for a web request. The key for this attribute is `http.statusCode`. Note: Agent versions below 8.0.0 used the attribute `httpResponseCode`. The default setting for each destination is: - Transaction traces: Enabled - Error analytics: Enabled - APM events: Enabled - Browser events: Disabled **HTTP response messages** The response status message if present for a web request. The key for this attribute is `http.statusText`. Note: Agent versions below 8.0.0 used the attribute `httpResponseMessage`. The default setting for each destination is: - Transaction traces: Enabled - Error analytics: Enabled - APM events: Enabled - Browser events: Disabled **JVM threads** The name of the thread. The key for this attribute is `jvm.thread_name`. The default setting for each destination is: - Transaction traces: Enabled - Error analytics: Enabled - APM events: Disabled - Browser events: Unavailable **Locked JVM threads** The name of a locked thread. The key for this attribute is `jvm.lock_thread_name`. The default setting for each destination is: - Transaction traces: Unavailable - Error analytics: Enabled - APM events: Unavailable - Browser events: Unavailable **Custom transaction attributes** Attributes added by a call to the [NewRelic.addCustomParameter(...)](http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/NewRelic.html#addCustomParameter-java.lang.String-java.lang.Number-) Java agent API. The key name for this attribute depends on what you specify when you call the method. The default setting for each destination is: - Transaction traces: Enabled - Error analytics: Enabled - APM events: Disabled - Browser events: Disabled > #### ⚠️ IMPORTANT > > Before creating custom attributes, review New Relic's list of [reserved terms used by NRQL](https://docs.newrelic.com/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words). Otherwise, you might get some unexpected results. **Custom span event attributes** Attributes added by a call to the [NewRelic.getAgent().getTracedMethod().addCustomAttribute(...)](http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/TracedMethod.html) Java agent API. The key name for this attribute depends on what you specify when you call the method. These attributes are added to span events, which can be found in the [distributed tracing UI](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/get-started/how-new-relic-distributed-tracing-works#trace-structure) or directly queried in the [query builder](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder). > #### ⚠️ IMPORTANT > > Before creating custom attributes, review New Relic's list of [reserved terms used by NRQL](https://docs.newrelic.com/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words). Otherwise, you might get unexpected results. **NoticeError() API calls** Attributes added to a [`NoticeError()`](http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/NewRelic.html#noticeError-java.lang.String-) call on the Java agent API. The key name for this attribute depends on what you specify when you call the method. The default setting for each destination is: - Transaction traces: Unavailable - Error analytics: Enabled - APM events: Unavailable - Browser events: Unavailable **Request and response headers** The Java agent can capture the following response and request headers as attributes: Captured HTTP request headers: - `request.headers.referer` - `request.headers.accept` - `request.headers.contentLength` - `request.headers.host` - `request.headers.userAgent` Captured response header: `response.headers.contentType` The agent does not capture other request headers. The attribute system does not apply to any header values other than the ones listed above. If you want to capture additional request headers not listed here, you must use the [custom_request_headers](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/#tt-custom-request-headers) config option to specify headers for the agent to capture. Alternatively, you can directly record the headers yourself using the `addCustomParameter()` method from the [Java agent API](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes#api-java). The default setting for each destination is: - Transaction traces: Enabled - Error analytics: Enabled - APM events: Enabled - Browser events: Disabled **Request parameters** The Java agent captures request methods GET, POST and PUT by default as part of the `request.method` attribute. Request parameters from the transaction are not captured by default. Use the [`addCustomParameter()`](http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/NewRelic.html#addCustomParameter-java.lang.String-java.lang.Number-) Java agent API to capture request parameters. The key for these attributes is `request.parameters.*`. If capturing sensitive information is a concern, you can use these options: - Avoid using wild cards in `attributes.include`. Instead, explicitly specify each field to capture. - If you want to use a wild card in `attributes.include`, explicitly exclude the sensitive fields using `attributes.exclude`. ## Collect user attributes [#user-attributes] With APM's Java agent, you can automatically collect user information in by editing your configuration file. You can then run [NRQL queries](https://docs.newrelic.com/docs/insights/using-insights-ui/basic-ui-tasks/query-page-create-edit-nrql-queries) against user information without needing to create custom attributes manually. This feature is available with New Relic's [Java agent 3.10.0](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes) or higher. > #### ⚠️ IMPORTANT > > Java user attributes are incompatible with [high-security mode](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security). **Enable collection of user attributes** To collect the `enduser.id` user attribute via the [public api](https://docs.newrelic.com/docs/apm/agents/java-agent/api-guides/guide-using-java-agent-api/#transactions) with Java agent 8.1.0 or higher, call: ````java NewRelic.setUserId(String userId); ``` Here's an example code snippet setting the user ID: ```java @Trace(dispatcher = true) public void run() { NewRelic.setUserId("example-user-id"); } ``` To collect user attributes via our servlet instrumentation with Java agent 3.10.0 or higher: 1. Open `newrelic.yml`, usually located in the same directory as `newrelic.jar`. 2. In the [`class_transformer`](/docs/agents/java-agent/configuration/java-agent-configuration-config-file#Custom_Instrumentation) section, edit [`com.newrelic.instrumentation.servlet-user`](/docs/agents/java-agent/configuration/java-agent-configuration-config-file#servlet-user) to set `enabled` to `true`: ```yml class_transformer: # This instrumentation reports the name of the user principal returned from # HttpServletRequest.getUserPrincipal() when servlets and filters are invoked. com.newrelic.instrumentation.servlet-user: enabled: true ``` 3. Restart your web server. ```` **View user attributes in dashboards** If you are using the [8.1.0](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes/) release of the Java agent, or higher, you can query the `enduser.id` attribute through either enabling [`com.newrelic.instrumentation.servlet-user`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#servlet-user) or using the [public API](https://docs.newrelic.com/docs/apm/agents/java-agent/api-guides/guide-using-java-agent-api/#transactions) and waiting a few minutes. For example, you could use the following [NRQL query](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/introduction-nrql-new-relics-query-language) to obtain a unique count of all users: ````sql SELECT uniqueCount(enduser.id) FROM Transaction SINCE 1 day ago ``` Or if you are using the [3.10.0](/docs/release-notes/agent-release-notes/java-release-notes/) release of the Java agent or higher, and enabled [`com.newrelic.instrumentation.servlet-user`](/docs/agents/java-agent/configuration/java-agent-configuration-config-file#servlet-user), you can query the `user` attribute within a few minutes: ```sql SELECT uniqueCount(user) FROM Transaction SINCE 1 day ago ``` In both cases, if errors are reported, you can use the user attribute(s) to see [how many users are impacted in a given error group](/docs/errors-inbox/error-users-impacted). ```` ## Configure attributes: Enable, include, and exclude [#properties] You can configure which types of attributes, or which specific attributes, the Java agent reports to New Relic. This is often done for security reasons, when there are certain sensitive attributes you don't want reported to New Relic. To learn what settings override other settings, see the [attribute configuration rules](#attruls). Attribute configuration options: **destination.attributes.enabled** | Destination | Configuration option | Default | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | All | [`attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-attributes-enabled) | True | | Transaction traces | [`transaction_tracer.attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-tt-attributes-enabled) | True | | Transaction segments | [`transaction_segments.attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-ts-attributes-enabled) | True | | Error analytics | [`error_collector.attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-error-attributes-enabled) | True | | APM events | [`transaction_events.attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-events-attributes-enabled) | True | | Browser events | [`browser_monitoring.attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-browser-attributes-enabled) | False | | Span events | `span_events.attributes.enabled` | True | Other resources: - See the [Java agent config file template](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-config-file-template). - See [rules governing attribute configuration, including what settings override other settings](#attruls). **destination.attributes.include** | Destination | Configuration option | Default | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | All | [`attributes.include`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-attributes-include) | (none) | | Transaction traces | [`transaction_tracer.attributes.include`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-tt-attributes-include) | (none) | | Transaction segments | [`transaction_segments.attributes.include`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-ts-attributes-include) | (none) | | Error analytics | [`error_collector.attributes.include`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-ec-attributes-include) | (none) | | APM events | [`transaction_events.attributes.include`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-te-attributes-include) | (none) | | Browser events | [`browser_monitoring.attributes.include`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-bm-attributes-include) | (none) | | Span events | `span_events.attributes.include` | (none) | Other resources: - See the [Java agent config file template](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-config-file-template). - See [rules governing attribute configuration, including what settings override other settings](#attruls). **destination.attributes.exclude** | Destination | Configuration option | Default | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | All | [`attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-attributes-exclude) | (none) | | Transaction traces | [`transaction_tracer.attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-tt-attributes-exclude) | (none) | | Transaction segments | [`transaction_segments.attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-ts-attributes-exclude) | (none) | | Error analytics | [`error_collector.attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-ec-attributes-exclude) | (none) | | APM events | [`transaction_events.attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-te-attributes-exclude) | (none) | | Browser events | [`browser_monitoring.attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-bm-attributes-exclude) | (none) | | Span events | [`span_events.attributes.exclude`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-span-events-attributes-exclude) | (none) | Other resources: - See the [Java agent config file template](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-config-file-template). - See [rules governing attribute configuration, including what settings override other settings](#attruls). ## Attribute rules [#attruls] The Java agent follows these rules when determining which attributes to include or exclude for a destination: **Setting attributes.enabled to false overrides all other settings.** If you set the main [`attributes.enabled`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-attributes-enabled) property to `false`, the agent does not report any attributes at all. **Disabling all attributes** Agent configuration: - `attributes.enabled: false` - `attributes.include: request.parameters.*` - `error_collector.attributes.enabled: true` Input keys: - `foo` - `bar` - `request.parameters.foo` - `request.parameters.bar` Agent output: - Transaction traces: No attributes - Error analytics: No attributes - APM events: No attributes - Browser events: No attributes **Setting a destination to false overrides include/exclude.** When you set [enabled](#cfg-attributes-enabled) to `false` for a destination, the agent ignores your include/exclude settings and doesn't report any attributes for that destination. **Disable one destination** Agent configuration: - `transaction_tracer.attributes.enabled: false` - `attributes.include: one, two*` - `transaction_tracer.attributes.include: three, four` Input keys: - `one` - `two` - `three` - `four` Agent output: - Transaction traces: No attributes - Error analytics: `one`, `two` - APM events: `one`, `two` - Browser events: No attributes **Exclude overrides include.** The `.exclude` properties override the `.include` properties. **Conflict between include and exclude settings** Agent configuration: - `attributes.enabled: true` - `attributes.include: foo, myCustomAtt` - `attributes.exclude: password, myCustomAtt` Input keys: - `foo` - `myCustomAtt` - `password` Agent output: - Transaction traces: `foo` - Error analytics: `foo` - APM events: `foo` - Browser events: `foo` **More specific rules take priority.** If multiple include or exclude attributes affect the same key, the most specific setting will have priority. **Conflicting specific settings** Agent configuration: - `attributes.enabled: true` - `attributes.include: foo, myCustomAtt` - `attributes.exclude: password, myCustomAtt` - `browser_monitoring.attributes.enabled: true` Input keys: - `food` - `food.bread` - `food.fruit.banana` - `food.fruit.apple` Agent output: - Transaction traces: `food.fruit.apple` - Error analytics: `food.fruit.banana`, `food.fruit.apple` - APM events: `food.fruit.banana`, `food.fruit.apple` - Browser events: `food.fruit.banana`, `food.fruit.apple` **Keys are case-sensitive.** The keys specified in the `.include` and `.exclude` properties are case-sensitive. **Keys which do not match the specified case** Agent configuration: - `attributes.enabled: true` - `attributes.exclude: password, PaSsWoRd` Input keys: - `password` - `Password` - `PASSWORD` - `PaSsWoRd` - `PassWORD` Agent output: - Transaction traces: `Password`, `PASSWORD`, `PassWORD` - Error analytics: `Password`, `PASSWORD`, `PassWORD` - APM events: `Password`, `PASSWORD`, `PassWORD` - Browser events: `Password`, `PASSWORD`, `PassWORD` **Use an asterisk for wildcards.** You can use an asterisk `*` at the end of a key as a wildcard. This will match a set of attributes with the same prefix. **Match multiple input keys** Agent configuration: - `attributes.enabled: true` - `attributes.include: custom*` - `attributes.exclude: request.parameters.*` Input keys: - `custom` - `custom.key1` - `custom.key2` - `request.parameters.` - `request.parameters.foo` - `request.parameters.bar` Agent output: - Transaction traces: `custom`, `custom.key1`, `custom.key2` - Error analytics: `custom`, `custom.key1`, `custom.key2` - APM events: `custom`, `custom.key1`, `custom.key2` - Browser events: `custom`, `custom.key1`, `custom.key2`