Java agent 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

Circuit breaker

These settings customize the behavior of the Java circuit breaker. 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:

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

Type	Boolean
Default	`true`

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

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.

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 or a NEW_RELIC_CLOUD_ prefixed environment variable.

An example configuration:

cloud:
  aws:
    account_id: 123456789012
  metadata_bypass_proxy: false

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:

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

Cloud platform 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.

Code-level metrics

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 with a newrelic.config.code_level_metrics prefixed system property.

Custom events

Set custom events settings in the custom_insights_events section. You can override these settings with a newrelic.config.custom_insights_events prefixed system property.

APM lets you record custom event data via the New Relic language agent APIs, which you can then query.

Important

For Java agent versions prior to 4.1.0, the following YAML configuration is recognized:

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:

custom_insights_events:
  enabled: false
  max_samples_stored: 5000

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+.

Type	Integer
Default	`30000`

The maximum number of sampled custom events reported every 60 seconds.
When configuring the agent for AI monitoring, set to max value 100000. Ensures that the maximum amount of LLM events are captured.

External tracer

Set the external tracing options in the external_tracer section. These options can be overridden with a newrelic.config.external_tracer prefixed system property.

Hostname configuration

Set the hostname configuration options in the process_host section. These options can be overridden with a newrelic.config.process_host prefixed system property.

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

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 with a newrelic.config.jar_collector prefixed system property. Options include:

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 or a NEW_RELIC_OBFUSCATE_JVM_PROPS_ prefixed environment variable.

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

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, where allow works as include.

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, where block works as exclude.

Kafka message queues

Detailed information on Kafka instrumentation configuration and can be found on the Instrument Kafka message queues page.

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.
----------

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.

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 by using a newrelic.config.slow_transactions prefixed system property. Options include:

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

Set the strip exceptions options in the strip_exception_messages section. These options can be overridden with a newrelic.config.strip_exception_messages prefixed system property. Enable this setting to control whether Java exception messages are reported to New Relic.

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.

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, 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.

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.

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.

Important

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

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

Set the thread profiler options in the thread_profiler section. These options can be overridden 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.

Tip

Circuit breaker.css-21sua1{background:none;border:none;width:0;padding:0;}

memory_threshold

gc_cpu_threshold

Cloud configuration

aws.account_id

metadata_bypass_proxy

Cloud platform utilization

detect_aws

detect_azure

detect_gcp

detect_kubernetes

detect_pcf

detect_docker

Code-level metrics

enabled

Custom events

Important

enabled

max_attribute_value

max_samples_stored

External tracer

exclude_request_uri

Hostname configuration

display_name

ipv_preference

Jar collector

enabled

skip_temp_jars

jars_per_second

JVM properties obfuscation

enabled

allow

block

Kafka message queues

Skip Applications

Important

NEW_RELIC_STARTUP_JAVA_ARTIFACT_SKIPS

NEW_RELIC_STARTUP_JAVA_ARTIFACT_INCLUDES

Slow transaction detection

enabled

threshold

evaluate_completed_transaction

Strip exceptions

enabled

whitelist (DEPRECATED)

allowed_classes

Temporary Jar File Removal

Important

NEW_RELIC_TEMP_JARFILE_AGE_THRESHOLD_HOURS

Thread profiler

enabled

Circuit breaker