---
title: Java agent other settings
source: https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-other-settings
---

These settings cover additional Java agent configuration options including cloud platform detection, performance controls, and agent lifecycle settings.

> #### 💡 TIP
>
> Back to the full settings index: [Java agent configuration](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file)

## Circuit breaker

These settings customize the behavior of the [Java circuit breaker](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/circuit-breaker-java-custom-instrumentation). These settings are not included in `newrelic.yml` by default. You do not need to restart your JVM after changing them.

If you want to customize the circuit breaker, add it under the `common` section:

```yml
common: &default_settings​
  OTHER_CONFIG_SETTINGS
  circuitbreaker:
    enabled: true
    memory_threshold: 20
    gc_cpu_threshold: 10
```

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

If your application is behaving as expected, you may want to disable the circuit breaker.

**memory_threshold**

| Type    | Integer (0 to 100) |
| ------- | ------------------ |
| Default | `20`               |

Customize the percentage of free heap memory below which the circuit breaker should trip. When the percentage of free heap memory is less than `memory_threshold`, and the CPU time spent doing garbage collection is greater than `gc_cpu_threshold`, the circuit breaker trips. In order to make the circuit breaker less likely to trip, decrease `memory_threshold` and/or increase `gc_cpu_threshold`. Adjust these values as needed, based on your application's operating performance and behavior.

**gc_cpu_threshold**

| Type    | Integer (0 to 100) |
| ------- | ------------------ |
| Default | `10`               |

Customize the percentage of garbage collection CPU time above which the circuit breaker should trip. When the percentage of free heap memory is less than `memory_threshold`, and the CPU time spent doing garbage collection is greater than `gc_cpu_threshold`, the circuit breaker trips. In order to make the circuit breaker less likely to trip, decrease `memory_threshold` and/or increase `gc_cpu_threshold`. Adjust these values as needed, based on your application's operating performance and behavior.

## Cloud configuration

Set cloud related options, in the `cloud` section of the agent YAML. You can override these settings with a `newrelic.config.cloud` prefixed [system property](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/#System_Properties) or a `NEW_RELIC_CLOUD_` prefixed [environment variable](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/#Environment_Variables).

An example configuration:

```yml
cloud:
  aws:
    account_id: 123456789012
  metadata_bypass_proxy: false
```

**aws.account_id**

| Type    | String |
| ------- | ------ |
| Default | (none) |

This setting is read by some cloud service instrumentation so the `cloud.resource_id` attribute can be set in the respective spans.

AWS DynamoDB and Kinesis are services that require this value to be able to populate the `cloud.resource_id` attribute. Likewise, AWS Lambda requires that this value when the account ID is not part of the function name.

The following call will override this setting:

````java
NewRelic.getAgent().getCloud().setAccountInfo(CloudAccountInfo.AWS_ACCOUNT_ID, "...");
```

````

**metadata_bypass_proxy**

| Type    | Boolean |
| ------- | ------- |
| Default | `false` |

When set to true, this setting allows you to bypass proxy for cloud metadata endpoint access. Default is false.

## Cloud platform utilization [#utilization]

Set the cloud platform utilization settings in the `utilization` section and can be overridden with the `newrelic.config.utilization` prefixed system property.

The agent collects utilization information and sends it to the New Relic service. The agent can collect information from Amazon Web Services (AWS), Azure, Google Cloud Platform, and Pivotal Cloud Foundry instances. It will also collect information related to the Docker containers and Kubernetes services.

**detect_aws**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Determines whether the agent polls AWS metadata API.

**detect_azure**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Determines whether the agent polls Azure metadata API.

**detect_gcp**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Determines whether the agent polls Google Cloud Platform metadata API.

**detect_kubernetes**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Determines whether the agent reports the `KUBERNETES_SERVICE_HOST` environment variable.

**detect_pcf**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Determines whether the agent reads Pivotal Cloud Foundry environment variables.

**detect_docker**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Determines whether the agent reads Docker information from the file system.

## Code-level metrics

[Code-level metrics](https://docs.newrelic.com/docs/codestream/observability/code-level-metrics) give you detailed insight into how your code is performing at the method level. You'll see metrics for each method that's been automatically instrumented, or that's been instrumented by the @Trace annotation.

Set the code-level metrics options in the `code_level_metrics` section. They can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.code_level_metrics` prefixed system property.

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

[Code-level metrics](https://docs.newrelic.com/docs/codestream/observability/code-level-metrics) is disabled by default in agent version 7.10.0. Set this to true to turn it on. Beginning in agent version 7.11.0 the default is, as noted above, `true`.

## Custom events [#Custom_Events]

Set custom events settings in the `custom_insights_events` section. You can [override](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) these settings with a `newrelic.config.custom_insights_events` prefixed system property.

APM lets you [record custom event data](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/insert-custom-events-new-relic-apm-agents) via the New Relic language agent APIs, which [you can then query](https://docs.newrelic.com/docs/query-your-data/explore-query-data/explore-data/introduction-querying-new-relic-data).

> #### ⚠️ IMPORTANT
>
> For Java agent versions prior to 4.1.0, the following YAML configuration is recognized:
>
> ```yml
> custom_insights_events.enabled: true
>   custom_insights_events.max_samples_stored: 5000
> ```
>
> For agent versions 4.1.0 and above, the YAML configuration uses the nested section formatting:
>
> ```yml
> custom_insights_events:
>   enabled: false
>   max_samples_stored: 5000
> ```

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

This enables the custom event service.

**max_attribute_value**

| Type    | Integer |
| ------- | ------- |
| Default | `255`   |

The maximum size of an attribute value, after which the value will be truncated. The default is `255` bytes (in UTF-8 charset encoding) and the max limit is `4095`.

This config exists in Java agent version 8.9.0+.

**max_samples_stored**

| Type    | Integer |
| ------- | ------- |
| Default | `30000` |

-   The maximum number of sampled custom events reported every 60 seconds.
-   When configuring the agent for [AI monitoring](https://docs.newrelic.com/docs/ai-monitoring/intro-to-ai-monitoring), set to max value `100000`. Ensures that the maximum amount of LLM events are captured.

## External tracer [#External_Tracer]

Set the external tracing options in the `external_tracer` section. These options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.external_tracer` prefixed system property.

**exclude_request_uri**

| Type    | Boolean |
| ------- | ------- |
| Default | `false` |

This setting can be used to control the collection of outgoing request URIs for errors and transaction traces. Set this to true to disable collecting this information.

## Hostname configuration [#hostname_configuration]

Set the hostname configuration options in the `process_host` section. These options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.process_host` prefixed system property.

Use these properties to configure the hostname displayed in the UI:

**display_name**

| Type    | String |
| ------- | ------ |
| Default | (none) |

Set a [display name](https://docs.newrelic.com/docs/agents/java-agent/configuration/hostname-logic-java#display-name) to decorate the "host:port" label in the New Relic UI.

**ipv_preference**

| Type    | String |
| ------- | ------ |
| Default | `4`    |

If the hostname cannot be determined, then the IP address of the host will be used. This property determines whether the IPv4 or IPv6 address should be used. The default is IPv4.

## Jar collector

The Java agent collects information about jars and their versions on the application classpath.

Set the jar collection configuration in the `jar_collector` section. These configuration options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.jar_collector` prefixed system property. Options include:

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Used to enable/disable jar collection and reporting.

**skip_temp_jars**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Used to enable/disable collection of temporary jars. Temporary jars are those residing in the directory specified by the system property `java.io.tmpdir`.

**jars_per_second**

| Type    | Integer |
| ------- | ------- |
| Default | `10`    |

The maximum number of jars to process per second. Must be positive.

## JVM properties obfuscation

The Java agent sends JVM properties to New Relic for display in the UI. Starting with Java agent version `8.16.0` the values of most properties will be obfuscated. For example: `-Dprop=12345` will now be sent as `-Dprop=obfuscated`.

Set obfuscation related options, in the `obfuscate_jvm_props` section of the agent YAML. You can override these settings with a `newrelic.config.obfuscate_jvm_props` prefixed [system property](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/#System_Properties) or a `NEW_RELIC_OBFUSCATE_JVM_PROPS_` prefixed [environment variable](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/#Environment_Variables).

By default, values of properties starting with `-X` won't be obfuscated.

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Used to enabled/disable obfuscation of JVM properties.

**allow**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

If obfuscation is enabled, when the property key matches a value in this list, then the value won't be obfuscated.

The items in this list can have wildcards, `*` as the last character. Conflicts with the block list are resolved following [attribute rules](https://docs.newrelic.com/docs/apm/agents/java-agent/attributes/java-agent-attributes/#attruls), where `allow` works as `include`.

**block**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

If obfuscation is enabled, when the property key matches a value in this list, then the value will be obfuscated.

The items in this list can have wildcards, `*` as the last character. Conflicts with the allow list are resolved following [attribute rules](https://docs.newrelic.com/docs/apm/agents/java-agent/attributes/java-agent-attributes/#attruls), where `block` works as `exclude`.

## Kafka message queues [#kafka-message-queues]

Detailed information on Kafka instrumentation configuration and can be found on the [Instrument Kafka message queues](https://docs.newrelic.com/docs/apm/agents/java-agent/instrumentation/java-agent-instrument-kafka-message-queues/) page.

-   [Kafka event collection](https://docs.newrelic.com/docs/apm/agents/java-agent/instrumentation/java-agent-instrument-kafka-message-queues/#collect-kafka-events)
-   [Kafka node metrics](https://docs.newrelic.com/docs/apm/agents/java-agent/instrumentation/java-agent-instrument-kafka-message-queues/#kafka-node-metrics)
-   [Kafka config events](https://docs.newrelic.com/docs/apm/agents/java-agent/instrumentation/java-agent-instrument-kafka-message-queues/#kafka-config)
-   [Kafka streams transactions](https://docs.newrelic.com/docs/apm/agents/java-agent/instrumentation/java-agent-instrument-kafka-message-queues/#collect-kafka-streams-transactions)
-   [Kafka connect transactions](https://docs.newrelic.com/docs/apm/agents/java-agent/instrumentation/java-agent-instrument-kafka-message-queues/#collect-kafka-connect-transactions)
-   [Kafka distributed traces](https://docs.newrelic.com/docs/apm/agents/java-agent/instrumentation/java-agent-instrument-kafka-message-queues/#collect-kafka-distributed-traces)

## Skip Applications [#skip-applications]

The agent can be selectively enabled or disabled based on the startup main class or executable jar file that is extracted from the command line. This is handy in situations where the "JAVA_TOOL_OPTIONS" environment
variable is present and contains the -javaagent flag but we don't want to apply the instrumentation to all java apps in the environment - for example in a Kubernetes container.

> #### ⚠️ IMPORTANT
>
> The skip configuration is only supported via a system property an environment variable because of how early in the agent lifecycle the skip configuration needs to be checked.

For diagnostic purposes, if any of the exclude or include configuration variables are defined, the agent will print the extracted command line and parsed skip tokens to stdout:

```
New Relic Agent: New Relic Agent: Configured startup Java artifacts [include|skip] string: keytool,Main
New Relic Agent: Retrieved current startup command line / main artifact name: /Users/bob/.sdkman/candidates/java/11.0.17-amzn/bin/keytool
```

If the agent is disabled based on a include or skip configuration variable, the following will be dumped to stdout:

```
----------
New Relic Agent is disabled by startup class/jar skip or include configuration.
----------
```

**NEW_RELIC_STARTUP_JAVA_ARTIFACT_SKIPS**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

A comma separated list of main classes, executable jar files or Java based tools/apps that the agent should NOT instrument. For example:
`NEW_RELIC_STARTUP_JAVA_ARTIFACT_SKIPS=keytool,myapp.jar,IgnoreThisClass`. The corresponding system property is `newrelic.config.startup_java_artifact_skips`.

**NEW_RELIC_STARTUP_JAVA_ARTIFACT_INCLUDES**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

A comma separated list of main classes, executable jar files or Java based tools/apps that the agent SHOULD instrument. For example:
`NEW_RELIC_STARTUP_JAVA_ARTIFACT_INCLUDES=myapp.jar`. The corresponding system property is `newrelic.config.startup_java_artifact_includes`.

## Slow transaction detection

The agent can now detect slow transactions via `SlowTransaction` events since Java Agent version `8.7.0`.
These events are recorded when the transaction length exceed a certain threshold. By default the treshold is 600000 milliseconds (10 minutes).

Slow transaction detection is set in the `slow_transactions` and can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) by using a `newrelic.config.slow_transactions` prefixed system property. Options include:

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Used to enable/disable slow transaction detection.

**threshold**

| Type    | Integer  |
| ------- | -------- |
| Default | `600000` |

Determines how long a transaction has to take in milliseconds for a `SlowTransaction` event to be reported.

**evaluate_completed_transaction**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

If this is set to true, every transaction will be checked for exceeding the defined threshold on
transaction completion. Note that if a large number of transactions exceed the threshold,
this can be computationally expensive since a stack trace is sent with every SlowTransaction event.

## Strip exceptions [#strip_exceptions]

Set the strip exceptions options in the `strip_exception_messages` section. These options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.strip_exception_messages` prefixed system property. Enable this setting to control whether Java exception messages are reported to New Relic.

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `false` |

By default, this is set to `false`, which means that the agent sends messages from all exceptions to the [New Relic collector](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#collector).

-   If you set this to `true`, the agent strips the messages from exceptions in order to prevent it from inadvertently capturing sensitive information.
-   If you enable [high-security mode](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/high-security-mode), this is automatically set to `true`.
-   If you set `enabled` to `true` but you want the agent to capture messages from specific exceptions, add the exceptions to your [allow list](#strip_exception_messages_whitelist).

**whitelist (DEPRECATED)**

| Type    | String |
| ------- | ------ |
| Default | (none) |

> #### ⚠️ IMPORTANT
>
> This config has been deprecated as of agent version 5.10.0 and will be removed in a future agent version. Instead use `allowed_classes`.

If you set `enabled` to `true` but you want the agent to capture messages for specific exceptions, add each exception to the `whitelist`, separated by a comma.

**allowed_classes**

| Type    | String |
| ------- | ------ |
| Default | (none) |

If you set `enabled` to `true` but you want the agent to capture messages for specific exceptions, add each exception to `allowed_classes`, separated by a comma.

## Temporary Jar File Removal [#temporary-jar-file-removal]

In some customer environments, agent temporary jars aren't properly cleaned up, even though these jars are marked to be deleted on termination of the JVM. This is likely due to abnormal termination of the JVM.
This configuration directs the agent to delete any temporary agent jar files older than the specified value on startup.
This configuration is only supported via a system property or an environment variable because of how early in the agent lifecycle the file deletion must occur.

For diagnostic purposes, if this feature is enabled, the following will be written to the console:

```
New Relic Agent: Removing stale temporary agent file jars from [temporaryFolder] older than [X] hour(s)
```

If any files are deleted, the following will be written to the console:

```
New Relic Agent: Deleted [count] stale temporary jar files freeing up [totalBytes] bytes
```

**NEW_RELIC_TEMP_JARFILE_AGE_THRESHOLD_HOURS**

| Type    | Integer |
| ------- | ------- |
| Default | 0       |

The value is the number of hours old a temp jar needs to be in order to be deleted (whole numbers only).
The default value is 0, which disables the file deletion check. The corresponding system property is `newrelic.config.temp_jarfile_age_threshold_hours`.

## Thread profiler [#Thread_Profiler]

Set the thread profiler options in the `thread_profiler` section. These options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.thread_profiler` prefixed system property.

Thread profiler measures wall clock time, CPU time, and method call counts in your application's threads as they run.

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Enable the thread profiler.