• /
  • EnglishEspañolFrançais日本語한국어Português
  • Log inStart now

Java agent configuration: Config file

The New Relic Java agent reads its configuration from the newrelic.yml file. By default the agent looks for this file in the directory that contains newrelic.jar. You can override the config file's location by setting the newrelic.config.file system property to a fully qualified file name.

You'll be able to configure our Java agent to suit your environment after you create a New Relic account (it's free, forever) and install the Java agent.

Configuration file structure

The newrelic.yml file has separate sections for different environments:

  • Test
  • Development
  • Staging
  • Production (default)

New Relic applies settings in the common section to each of these environments. You can select other environments as the default by setting the newrelic.environment system property to the environment name.

Tip

A newrelic.yml template is available.

If you edit newrelic.yml, be careful to conform to the YAML format. Use a YAML validator to ensure the syntax is accurate before using the file with New Relic's Java agent, and follow these rules:

Java agent newrelic.yml

Requirements

Format

YML files are case sensitive.

Indentations

All indentations must be in increments of two characters. Other indentations will result in an Unable to parse configuration file error upon agent startup.

  • Use the same level of indentation for data in the same section of the file.
  • Indent any sub-sections by an additional two spaces.

Changes to file

You must restart your JVM host process for changes to take effect.

Exception: Property changes to log_level and audit_mode do not require a restart. Property changes under circuit breaker don't require a restart.

Configuration settings precedence

To override any setting in the config file, use a system property override. In certain environments, environment variables can also be used to override both the config file and the system properties. The environment variables primarily exist to support Heroku. When used, server-side configuration overrides all other configuration settings.

java-config-order.png

With the Java agent, server-side configuration overrides all other settings. Environment variables override Java system properties. Java properties override user configuration settings in your newrelic.yml file. User settings override the newrelic.yml default settings.

Configuring the Java extensions directory

The Java agent reads the configuration files on process startup. To identify the directory where the files are located, either create a new or specify an existing extensions directory:

General configuration settings

Set these options in the common section. To override any of these options, use a newrelic.config prefixed system property.

Environment variables

Environment variables take the highest precedence and override the system properties and yml config settings.

  • To set environment variables, use the export VARNAME=value command.
  • To permanently set environment variables, add the export line to a file such as ~/.bashrc or ~/.bash_profile.

You can override any setting from a system property or in the newrelic.yml by setting an environment variable. The environment variable corresponding to a given setting in the config file is the setting name prefixed by NEW_RELIC with all dots (.) and dashes (-) replaced by underscores (_). For example, the environment variable for the log_level setting is NEW_RELIC_LOG_LEVEL.

For settings nested in sections, prepend the section name to the setting name. For example:

class_transformer:
  com.newrelic.instrumentation.kafka-clients-spans-0.11.0.0:
    enabled: true

The configuration above would convert to the following environment variable: NEW_RELIC_CLASS_TRANSFORMER_COM_NEWRELIC_INSTRUMENTATION_KAFKA_CLIENTS_SPANS_0_11_0_0_ENABLED

Important

Agent configuration via environment variables requires Java agent version 4.10.0 or higher.

System properties

You can override any setting in the newrelic.yml file by setting a system property. The system property corresponding to a given setting in the config file is the setting name prefixed by newrelic.config. For example, the system property for the log_level setting is newrelic.config.log_level.

For settings nested in sections, prepend the section name to the setting name. For example, the system property for the enabled setting in the transaction_tracer section is newrelic.config.transaction_tracer.enabled.

In addition to overriding configuration settings, the agent recognizes these system properties:

AI monitoring

This section details the Java agent configuration options for AI monitoring. This feature can be configured in the ai_monitoring yaml config file stanza, with newrelic.config.ai_monitoring. prefixed system properties, or with NEW_RELIC_AI_MONITORING_ prefixed environment variables.

Important

If distributed tracing is disabled or high security mode is enabled, AI monitoring will not collect AI data.

Important

When enabled, AI monitoring records a streaming copy of inputs and outputs sent to and from the models you choose to monitor, including any personal information contained therein. You're responsible for obtaining consent from your model users that their interactions may be recorded by a third party (New Relic) for the purpose of providing the AI monitoring feature.

Attributes

To set these options, use the attributes section. To override them, use a newrelic.config.attributes prefixed system property.

Attributes are key-value pairs related to transaction traces, traced errors, , and transaction events. There's an attribute section under each destination. For more information, see Java agent attributes, Enabling and disabling attributes and Attribute examples.

Async instrumentation

These options are set directly in the common section and can be overridden by using a prefixed system property.

Browser monitoring

These options are set in the browser_monitoring section and can be overridden by using a newrelic.config.browser_monitoring prefixed system property.

Browser monitoring gives you insight into the performance real users are experiencing with your website. This is accomplished by measuring the time it takes for your users' browsers to download and render your web pages by injecting a small amount of JavaScript code into the header and footer of each page.

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

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

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.

Errors inbox configuration

Setting one of the following tags will help you identify which versions of your software are producing the errors.

  • NEW_RELIC_METADATA_SERVICE_VERSION will create tags.service.version on event data containing the version of your code that is deployed, in many cases a semantic version such as 1.2.3, but not always.
  • NEW_RELIC_METADATA_RELEASE_TAG will create tags.releaseTag on event data containing the release tag (such as v0.1.209 or release-209).
  • NEW_RELIC_METADATA_COMMIT will create tags.commit on event data containing the commit sha. You can use the entire sha or use just the first seven characters (e.g., 734713b).

An upcoming release of errors inbox will automatically track which versions of your software are producing errors. The version data will display in CodeStream.

Cross application tracer

Important

Cross application tracing has been deprecated as of agent version 7.4.0 and will be removed in a future agent version.

Instead of using cross application tracing, we recommend our distributed tracing features. Distributed tracing is an improvement on the cross application tracing feature and is recommended for large, distributed systems.

Set the cross application tracing options in the cross_application_tracer section. These settings can be overridden with a newrelic.config.cross_application_tracer prefixed system property.

Cross application tracing adds request and response headers to external calls using the Apache HttpClient libraries. This provides better performance data when calling applications monitored by other New Relic agents.

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

Class transformer

Set instrumentation related settings in the class_transformer section. You can override these settings with a newrelic.config.class_transformer prefixed system property or a NEW_RELIC_CLASS_TRANSFORMER_ prefixed environment variable.

Distributed tracing

Important

Enabling distributed tracing disables cross application tracing, and has other effects on APM features. Before enabling, read the transition guide.

Requires Java agent version 4.3.0 or higher.

Distributed tracing lets you see the path that a request takes as it travels through a distributed system. It is on by default for Java agent version 7.4.0 or higher.

In the config file, you can override this manually in the distributed_tracing section. You can also override this using a prefixed system property (newrelic.config.distributed_tracing) or an environment variable (NEW_RELIC_DISTRIBUTED_TRACING_ENABLED). See the examples below.

For more information about setting up distributed tracing, see Enable distributed tracing for your Java applications.

Error collector

Set the error collector settings in the error_collector section. Unless otherwise noted, you can override these settings with a newrelic.config.error_collector prefixed system property. The error collector captures information about uncaught exceptions and sends them to New Relic for viewing.

Tip

For how to configure errors for the Java agent, including how to configure errors via the UI, see Java agent error configuration.

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:

Infinite Tracing

Important

Requirements:

To turn on Infinite Tracing, enable distributed tracing and add the additional setting below. For an example, see Language agents: Configure distributed tracing.

Instrumentation

These options are set in the instrumentation stanza and can be overridden by using a newrelic.config.instrumentation prefixed system property.

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:

JFR (Real-time profiling)

The Java agent uses Java Flight Recorder (JFR) to collect high fidelity JVM data for Real-time profiling.

Configure real-time profiling in the jfr section in the agent YAML. These configuration options can be overridden with system properties prefixed by newrelic.config.jfr. or with environment variables prefixed with NEW_RELIC_JFR_.

JMX

To set these options, use the jmx section. To override them, use a newrelic.config.jmx prefixed system property.

The Java agent uses JMX to collect JVM data. Additionally the agent can expose linking metadata over JMX that can be used by other tracing systems.

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.

Kafka message queues

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

Logs in context

Starting with Java agent version 7.6.0, support for logs in context has been added to the agent, making it easy to use for supported logging frameworks. For tips on using the Java agent for logs in context, see Java logs in context.

Changing these settings in your local agent configuration file happens dynamically and doesn't require a restart of the agent for those changes to take effect. An example configuration:

application_logging:
  enabled: true
  forwarding:
    enabled: true
    max_samples_stored: 10000
    labels:
      enabled: false
      exclude:
    context_data:
      enabled: false
      include:
      exclude:
  metrics:
    enabled: true
  local_decorating:
      enabled: false

Set the logs in context configuration in the application_logging section. This can be overridden with a newrelic.config.application_logging prefixed system property. The only option available is:

Log forwarding

If you're using a supported logging framework and want to use the agent to send your application logs to New Relic, you can control that through settings under the forwarding section. These settings can be overridden by the newrelic.config.application_logging.forwarding prefixed system property. Options available are:

Log labels (tags)

The Java agent supports adding custom labels (tags) to agent-forwarded logs. Labels are sourced from the labels section at the top level of the agent configuration. This feature can be enabled within the labels section, nested under the forwarding section. You can override these settings using the newrelic.config.application_logging.forwarding.labels prefixed system property. Available options include:

Log context data

The Java agent can capture context data (Mapped Diagnostic Context in logback/slf4j, ThreadContext in log4j2) and add its contents as attributes in the logs forwarded to New Relic. You can control that through settings in the context_data section, nested under the forwarding section. These settings can be overridden by the newrelic.config.application_logging.forwarding.context_data prefixed system property. Options available are:

Log metrics

In addition to allowing you to decorate and send individual log lines, the Java agent can capture logging metric data. You can find this data in the logs chart in the New Relic UI. You can configure log metrics settings in the metrics section. You can override these settings with the newrelic.config.application_logging.metrics prefixed system property. The only available option is:

Log decorating

You can configure the log decorating settings in the local_decorating section. You can use this to control how local log lines are decorated. You can override these settings with a newrelic.config.application_logging.local_decorating prefixed system property. The only option available is:

Logging configuration

These are part of the general configuration variables. They are broken out here because they are frequently tweaked for debugging.

Some of the logging configuration variables are dynamic and do not need a host restart for them to take effect. For instance, if log files are growing too quickly, log_level can be set to a less verbose setting to reduce the reporting rate.

Here is the order of precedence and explanation for configuration variables affecting log rotation.

  • If log_daily is true:
    • A log_limit_in_kbytes value greater than zero will result in a composite triggering policy, where logs will roll once per day or when the defined size is reached, retaining up to log_file_count files
    • A log_limit_in_kbytes value of zero will result in logs rolling once per day retaining up to log_file_count files
  • If log_daily is false and log_limit_in_kbytes > 0, a sized based policy will be configured, where logs will roll when the defined size is reached, retaining up to log_file_count files
  • If log_daily is false and log_limit_in_kbytes = 0, no log file rolling logic will be configured

Depending on the growth rate, it is possible for the log file size to exceed the configured value by a small amount.

Message tracer

Set message tracer options in the message_tracer section. You can override these settings with a newrelic.config.message_tracer prefixed system property.

Open Telemetry SDK Auto-Configuration

Configuration for the open telemetry SDK autoconfigure instrumentation under the section:

opentelemetry:
  sdk:
    autoconfigure:

Security Agent

New Relic Security agent interactive applications security testing (IAST) tests your applications for any exploitable vulnerability by replaying the generated HTTP request with vulnerable payloads.

Important

Run IAST with non-production deployments only to avoid exposing vulnerabilities on your production software.

You can set the New Relic Security agent configuration in the security section. These settings can be overridden with a newrelic.config.security prefixed system property. Options include:

Important

New Relic Security agent interactive applications security testing (IAST) mode requires Java agent version 8.4.0 or higher.

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:

Span events

Span events are reported for distributed tracing. You must enable distributed tracing to report span events.

Set span events configuration in the span_events section. These settings can be overridden with a newrelic.config.span_events prefixed system property. Options include:

Important

Span event attribute filtering requires Java agent version 4.10.0 or higher.

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.

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.

Transaction events

Set the transaction events options in the transaction_events section. These options can be overridden with a newrelic.config.transaction_events prefixed system property.

Transaction events data is used to display histograms and percentiles in the UI.

Important

Previously, this section was called analytics_events. If your configuration file still uses analytics_events, update your agent to use transaction_events.

Transaction segments

Set the transaction segments options in the transaction_segments section. These options can be overridden with a newrelic.config.transaction_segments prefixed system property.

Transaction segments represent discrete pieces of work (generally method calls) and are displayed within transaction traces.

Important

Transaction segment attribute filtering requires Java agent version 4.10.0 or higher.

Transaction tracer

Set the transaction tracer options in the transaction_tracer section. These options can be overridden with a newrelic.config.transaction_tracer prefixed system property.

Transaction tracing captures deep information about slow transactions and sends this to the New Relic service. The transaction includes the exact call sequence of the transactions, including any query statements issued.

Important

Do not use brackets [suffix] at the end of your transaction name. New Relic automatically strips brackets from the name. Instead, use parentheses (suffix) or other symbols if needed.

Copyright © 2025 New Relic Inc.
CareersTerms of ServiceDMCA PolicyPrivacy NoticeCookie PolicyUK Slavery Act

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.