• English日本語한국어
  • 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 environnment after you create a New Relic account (it's free, forever) and install the Java agent.

Configuration file structure

The newrelic.yml file is split into stanzas corresponding to different environments:

  • Test
  • Development
  • Staging
  • Production (default)

New Relic applies settings in the common stanza 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 stanza of the file.
  • Indent any sub-stanzas 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.

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 stanza. To override any of these options, use a newrelic.config prefixed system property.

Important

As of Java agent 3.48.0, SSL is enabled by default and the config option to disable it has been deprecated. As of Java agent 4.0.0, the ability to disable SSL has been removed.

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 stanzas, prepend the stanza 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 stanzas, prepend the stanza name to the setting name. For example, the system property for the enabled setting in the transaction_tracer stanza is newrelic.config.transaction_tracer.enabled.

In addition to overriding configuration settings, the following system properties are recognized by the agent:

Attributes

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

Attributes are key-value pairs that provide information for transaction traces, traced errors, browser monitoring, and transaction events. There is also an attribute stanza 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 stanza and can be overridden by using a prefixed system property.

Browser monitoring

These options are set in the browser_monitoring stanza 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 the stanza under the common stanza:

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

Cloud platform utilization

These options are set in the utilization stanza and can be overridden by using a 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. For more information on code-level metrics, see Performance monitoring with CodeStream.

The code-level metrics options are set in the code_level_metrics stanza and can be overridden by using 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. The entire sha can be used or 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. Any version data will also be displayed 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.

The cross application tracing options are set in the cross_application_tracer stanza and can be overridden by using 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

Custom events are set in the custom_insights_events stanza and can be overridden by using 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 stanza formatting:

custom_insights_events:
  enabled: false
  max_samples_stored: 5000

Custom instrumentation

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

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

These options are set in the error_collector stanza and unless noted otherwise can be overridden by using 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

The external tracing options are set in the external_tracer stanza and can be overridden by using a newrelic.config.external_tracer prefixed system property.

Hostname configuration

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

These properties are used for configuring 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.

Jar collector

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

Jar collection configuration is set in the jar_collector stanza and can be overridden by using 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.

Real-time profiling can be configured in the jfr stanza in the agent yaml, 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 stanza. 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.

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
    context_data:
      enabled: false
      include:
      exclude:
  metrics:
    enabled: true
  local_decorating:
      enabled: false

Logs in context configuration is set in the application_logging stanza and can be overridden by using 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 stanza which can be overridden by the newrelic.config.application_logging.forwarding prefixed system property. Options available are:

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 under the context_data stanza, which is nested under the forwarding stanza. 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 also capture logging metric data, which is displayed in the logs chart in the New Relic UI. This is controlled by settings under the metrics stanza and can be overridden by the newrelic.config.application_logging.metrics prefixed system property. The only available option is:

Log decorating

The local_decorating stanza allows for controlling the decorating of local log lines and can be overridden by 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

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

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.

New Relic Security agent configuration is set in the security stanza and can be overridden by using 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. Distributed tracing must be enabled to report span events.

Span configuration is set in the span_events stanza and can be overridden by using 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

These options are set in the strip_exception_messages stanza and unless noted otherwise can be overridden by using a newrelic.config.strip_exception_messages prefixed system property. This configuration can be enabled to control whether Java exception messages are reported to New Relic.

Thread profiler

These options are set in the thread_profiler stanza and can be overridden by using 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

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

Transaction events provide the data for displaying histograms and percentiles in the UI.

Important

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

Transaction segments

These options are set in the transaction_segments stanza and can be overridden by using 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

These options are set in the transaction_tracer stanza and can be overridden by using 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 © 2023 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.