• /
  • Log in
  • Free account

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.

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

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 for configuration variables affecting log rotation.

  • If log_daily is true, other log rotation settings are ignored.
  • If log_file_count is 1 or 0, the size limit is ignored.
  • Finally, the agent applies log_limit_in_kbytes.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

The maximum number of sampled custom events reported every 60 seconds.

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:

Custom instrumentation

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

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:

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, the environment variable for the enabled setting in the transaction_tracer stanza is NEW_RELIC_TRANSACTION_TRACER_ENABLED.

Important

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

For agent versions 4.10.0 or higher the following environment variables are available:

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) EC2 instances and Docker containers.

Async instrumentation

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

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

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.

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. In the config file, it can be set in the distributed_tracing stanza. It can be overridden using a newrelic.config.distributed_tracing prefixed system property.

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.

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.

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:

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.