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.
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.
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:
To create the extensions directory:
Navigate to the directory where newrelic.jar and newrelic.yml are located. Create a directory named extensions.
In newrelic.yml, check that the property extensions.dir is not set.
To use an existing Java extensions directory:
In your newrelic.yml file, locate the common section.
Use the property extensions.dir to specify the location of the file.
General configuration settings
Set these options in the common stanza. To override any of these options, use a newrelic.config prefixed system property.
Type
String
Default
(none)
This setting is required. You must specify the license key associated with your New Relic account. This key binds your agent's data to your account in the New Relic service.
Type
String
Default
(none)
This setting is required. Defines the application name used to report data to New Relic.
If enable_auto_app_naming is false, the agent reports all data to this application. Otherwise, the agent reports only background tasks (transactions for non-web applications) to this application.
To report data to more than one application, separate the application names with a semicolon. For example, to report data to My Application and My Application 2 use this:
Flag to enable the agent. Use this setting to force the agent to run or not run.
Type
Float
Default
1.0
The apdex_t threshold in seconds for the application's Apdex score. For Java agent versions 1.2.008 or higher, the apdex_t value is set in the UI and the value in newrelic.yml is ignored.
Type
Integer
Default
(none)
Number to differentiate JVMs for the same app on the same machine. New Relic uses host/port for uniqueness, so you can distinguish the JVMs by putting a switch like this into the startup arguments for each JVM:
-Dnewrelic.config.appserver_port=8081
Once you have used appserver_port to name the JVMs and restart them, you should be able to see them individually in the dropdown and in the profiling interface.
Important
This is only a change for New Relic; it doesn't actually affect the port on which the host communicates in any way.
Type
Boolean
Default
false
Enables plain text logging of all data sent to New Relic to the agent logfile. This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
Type
String
Value Format
/path/to/ca/cert/bundle.pem
Specifies a path to a custom SSL certificate bundle that will be used by the agent to establish a secure connection to New Relic. If your custom SSL certificate bundle doesn't include certificates that are sufficient to connect to New Relic then you'll need to merge the required certs into your custom certificate bundle.
Type
Boolean
Default
false
The following SSL certificates are bundled into the agent jar:
META-INF/certs/eu-newrelic-com.pem
META-INF/certs/eu01-nr-data-net.pem
META-INF/certs/newrelic-com.pem
By default (use_private_ssl: false) the agent will use the SSL certificates bundled into the JDK to establish a secure connection to New Relic or the custom SSL certificates bundle specified by ca_bundle_path. If you want to use the SSL certificates bundled with the agent, set use_private_ssl: true.
Note: use_private_ssl will be ignored if ca_bundle_path is set.
Type
Boolean
Default
false
Enables the reporting of data separately for each web app. Set to true to enable support for auto app naming. The name of each web app is detected automatically and the agent reports data separately for each one. This provides a finer-grained performance breakdown for web apps in New Relic.
Enables component-based transaction naming. Set to true to enable component-based transaction naming. Set to false to use the URI of a web request as the name of the transaction. For more information, see Naming web transactions.
Caution
Unless you implement API calls to name your transactions, disabling auto-transaction naming is very likely to cause Metric grouping issues.
Type
Boolean
Default
true
Enables all instrumentation using an @Trace annotation. Disabling this causes @Trace annotations to be ignored.
Event ingest URI used by some agent features. Defaults to the US production ingest endpoint. Can be manually configured to send events to other ingest endpoints (for example, EU production: https://insights-collector.eu01.nr-data.net/v1/accounts/events).
Type
String
Default
(none)
Defines the location of the optional extensions directory. If this property is not set, the agent will look for a subdirectory named extensions in the same directory as newrelic.jar and newrelic.yml.
Type
Boolean
Default
false
In order for high security to be enabled, this property must be set to true and the high security property in the New Relic user interface must be enabled. Enabling high security means SSL is turned on, request and message queue parameters are not collected, and queries cannot be sent to New Relic in their raw form.
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.
Type
String
Default
(none)
A valid Insert API Key for your account. This is not currently used by the agent.
Note that this option now enables tags, which replaced the label feature. You can still query your historical labels.
Type
Integer
Default
30
Limits the number of lines the agent collects from each stack trace. Increasing this value may impact performance, because it increases the amount of memory the agent uses and the amount of data sent to New Relic.
Metric ingest URI used by some agent features. Defaults to the US production ingest endpoint. Can be manually configured to send metrics to other ingest endpoints (example EU production URI: https://metric-api.eu.newrelic.com/metric/v1).
Type
String
Default
(none)
The proxy host through which to connect to the New Relic collector. If a proxy is used, the host setting is required. Other proxy settings are optional.
Type
String
Default
(none)
The password for proxy authentication. If a proxy is used, the host setting is required. Other proxy settings are optional. The username and password settings will be used to authenticate to Basic Auth challenges from a proxy server.
Important
The Java agent supports Basic (clear text) authentication.
Type
String
Default
8080
The proxy host port number. If a proxy is used, the host setting is required. Other proxy settings are optional.
Type
String
Default
(none)
The username for proxy authentication, such as Basic (clear text) authentication. If a proxy is used, the host setting is required. Other proxy settings are optional. The username and password settings will be used to authenticate to Basic Auth challenges from a proxy server.
Type
String
Default
(none)
The proxy scheme used. Setting proxy_scheme: "https" will allow the agent to connect through proxies using the HTTPS scheme.
Type
Boolean
Default
false
Whether errors are reported for Reactor Netty. Default is false. If set to true, Reactor Netty errors will be reported.
Notice, default was changed to false as of Java agent 6.5.0.
Type
Boolean
Default
false
Enable delayed JVM shutdown to give the agent a chance to send latest metric data to New Relic before JVM shutdown.
Type
Integer
Default
60
The number of seconds after which the agent will use the send_data_on_exit setting.
Type
Boolean
Default
true
Enable reporting of JVM settings to New Relic.
Type
Boolean
Default
true
When set to true, JVM properties will be sent to New Relic.
Type
Boolean
Default
true
Requires connections to the New Relic collector to go over SSL.
The agent communicates with New Relic via HTTPS by default, and New Relic requires HTTPS for all traffic to APM and the New Relic REST API.
This work is done asynchronously to the threads that process your application code, so response times will not be directly affected by this change.
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.
Type
Boolean
Default
false
Enable the agent to connect the New Relic collector immediately upon app startup.
For more concise transaction trace details, the agent does not report Scala Futures as transaction segments, and those Futures do not contribute to the transaction’s total time.
Enabling scala_futures_as_segments increases your overhead. If you want Scala Futures to report as transaction segments so you can view them in a transaction trace, you can enable it:
scala_futures_as_segments:
enabled: true
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.
For agent versions 4.10.0 or higher the following environment variables are available:
Type
String
Default
(none)
This setting is required. Contains the application name under which to report data to New Relic. Set the name of your application as you want it to appear in New Relic.
If enable_auto_app_naming is false, the agent reports all data to this application. Otherwise, the agent reports only background tasks (transactions for non-web applications) to this application.
To report data to more than one application, separate the application names with a semicolon ;. For example, to report data to My Application and My Application 2:
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:
Type
String
Default
(none)
Set a display name to decorate the "host:port" label in the New Relic UI. Requires Java agent 3.17 or higher.
Type
String
Default
(none)
String containing a fully qualified path to the newrelic configuration file. If empty, the agent assumes newrelic.yml is in the same directory as newrelic.jar.
Type
Boolean
Default
(none)
Enable debug logging.
Type
String
Default
(none)
String containing the environment configuration for the agent to use.
Type
String
Default
(none)
String containing the home directory of agent. This defaults to the same directory as the agent jarfile.
Type
String
Default
newrelic_agent.log
String containing the name of the agent log file.
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.
Type
Boolean
Default
true
This setting can be used to turn on or off all attributes.
Important
For security reasons, capturing custom attributes using the Custom Instrumentation Editor is set to false by default.
Type
List of Strings
Default
(none)
If attributes are enabled, attribute keys found in this list will be sent to New Relic. Separate the keys in the list with a comma; for example:
These options are set directly in the common stanza and can be overridden by using a prefixed system property.
Type
Integer
Default (seconds)
180
The number of seconds after which the agent will automatically expire an async token that has not been explicitly expired with token.expire(). For usage instructions, see Tokens: Connect async threads.
Important
Increasing this value may impact performance, because it increases the amount of memory the agent uses and prevents transactions from being reported due to unexpired tokens.
Type
Integer
Default (seconds)
600
The number of seconds after which the agent will automatically end a segment that has not been explicitly ended with segment.end() or segment.ignore(). For usage instructions, see Segments: Time arbitrary async activity.
Important
Increasing this value may impact performance, because it increases the amount of memory the agent uses and prevents transactions from being reported due to un-ended segments.
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.
Type
Boolean
Default
true
By default the agent automatically inserts API calls in compiled JSPs to inject the monitoring JavaScript into web pages. Set this attribute to false to turn off this behavior.
Type
Comma-separated list of strings
Default
(none)
When auto_instrument is true, by default all pages are instrumented. List all pages that you want the auto instrumentation to skip here. You can still use manual instrumentation on these pages.
This setting can be used to turn on or off all attributes for browser monitoring. This is the data you can query. If attributes.enabled is false at the root level, no attributes will be sent up in browser monitoring regardless on how this property under browser_monitoring is set.
Type
List of Strings
Default
(none)
If attributes are enabled for browser_monitoring, all attribute keys found in this list will be sent to New Relic in page views. For more information, see the agent attribute rules.
Type
List of Strings
Default
(none)
All attribute keys found in this list will not be sent to New Relic in page views. For more information, see the agent attribute rules.
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:
If your application is behaving as expected, you may want to disable the circuit breaker.
Type
Integer (0 to 100)
Default
20
Customize the precentage 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 precentage 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 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.
Type
Boolean
Default
true
Determines whether the agent polls AWS metadata API.
Type
Boolean
Default
true
Determines whether the agent reads Docker information from the file system.
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 are set in the custom_insights_events stanza and can be overridden by using a newrelic.config.custom_insights_events prefixed system property.
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
Type
Boolean
Default
true
This enables the custom event service.
Type
Integer
Default/Max
10000
The maximum number of sampled custom events reported every 60 seconds.
Custom instrumentation
These options set in the class_transformer stanza and can be overridden by using a newrelic.config.class_transformer prefixed system property.
Type
String
Default
(none)
String containing the full class name of the annotation class the agent uses to determine which user-specified methods to instrument. For more information about custom annotations, see Java custom metric collection.
Type
Boolean
Default
false
Enable this option to capture the userPrincipal name. This name is included as a transaction trace attribute, and can be queried.
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.
By default, supported versions of the agent utilize both the newrelic header and W3C Trace Context headers for distributed tracing. The newrelic distributed tracing header allows interoperability with older agents that don't support W3C Trace Context headers. Agent versions that support W3C Trace Context headers will prioritize them over newrelic headers for distributed tracing.
If you do not want to utilize the newrelic header, setting this to true will result in the agent excluding the newrelic header and only using W3C Trace Context headers for distributed tracing.
For example, to exclude newrelic headers in the config file, you would use:
distributed_tracing:
exclude_newrelic_header: true
To exclude newrelic headers using a system property, you would use:
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.
Type
Boolean
Default
true
Enable error collection.
Type
Stanza containing a list of fully qualified class_name strings
Default
(none)
Specified exception class names will be ignored and will not affect error rate or Apdex score, or be reported to APM. Cannot be specified by system property.
This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
For example:
error_collector:
ignore_classes:
- "com.example.MyException"
- "com.example.DifferentException"
An environment variable can be used to list exception class names you want to be ignored:
Stanza containing a fully qualified class_name and a list of messages per error class
Default
(none)
Specify exception class names the agent should ignore. Ignored messages will not affect error rate or Apdex score, or be reported to APM. Contains yaml pairs consisting of:
A fully qualified exception class name that should not be reported to APM
AND
A list of exception messages to match against (at least one is required)
If the exception class name matches an error but the message does not, then that error will not be ignored. Message strings use contains for matching. A message cannot be provided on its own and must always be paired with a fully qualified class name. Cannot be specified by system property.
This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
For example:
error_collector:
ignore_messages:
com.example.MyException:
- "Some error message to ignore"
- "Some other error message to ignore"
com.example.DifferentException:
- "Some different error message to ignore"
An environment variable can be used to list exception class names and messages you want to be ignored:
NEW_RELIC_ERROR_COLLECTOR_IGNORE_MESSAGES="{\"com.example.MyException\": [\"Some error message to ignore\", \"Some other error message to ignore\"], \"com.example.DifferentException\": [\"Some different error message to ignore\"]}"
Type
Comma-separated list of strings and ranges
Default
404
A comma-separated list comprised of individual and dashed ranges of HTTP status codes that should not be treated as errors.
If this property is commented out in the newrelic.yml configuration file, then the 404 status code will automatically be ignored. When using server-side configuration, the status code 404 must be specified in order for it to be ignored.
This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
For example:
error_collector:
ignore_status_codes: 404,507-511
Type
Stanza containing a List of fully qualified class_name strings
Default
(none)
Prevents specified exception classes from affecting error rate or Apdex score while still reporting the errors to APM. Cannot be specified by system property.
This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
For example:
error_collector:
expected_classes:
- "com.example.MyException"
- "com.example.DifferentException"
An environment variable can be used to list expected exception class names:
Stanza containing a fully qualified class_name and a List of messages per error class
Default
(none)
Contains yaml pairs consisting of a fully qualified exception class name that should be marked as expected and thus prevented from affecting error rate or Apdex score and a List of exception messages to match against, the latter of which at least one is required. If the exception class name matches an error but the message does not, then that error will not be marked as expected and therefore will affect error rate and Apdex score.
Message strings use contains for matching. A message cannot be provided on its own and must always be paired with a fully qualified class name. Cannot be specified by system property.
This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
For example:
error_collector:
expected_messages:
com.example.MyException:
- "Some expected error message"
- "Some other expected error message"
com.example.DifferentException:
- "Some different expected error message"
An environment variable can be used to list expected exception class names and messages:
NEW_RELIC_ERROR_COLLECTOR_EXPECTED_MESSAGES="{\"com.example.MyException\": [\"Some error message to ignore\", \"Some other error message to ignore\"], \"com.example.DifferentException\": [\"Some different error message to ignore\"]}"
Type
Comma-separated list of strings and ranges
Default
(none)
A comma-separated list comprised of individual and dashed ranges of HTTP status codes to be marked as expected and thus prevented from affecting error rate or Apdex score.
This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
For example:
error_collector:
expected_status_codes: 415,500-506
Expected status codes can also be with the NEW_RELIC_ERROR_COLLECTOR_EXPECTED_STATUS_CODES environment variable.
Type
Boolean
Default
true
This setting can be used to turn on or off all attributes for traced errors. If attributes.enabled is false at the root level, then no attributes will be sent to traced errors regardless of how this property is set under error_collector.
Type
List of strings
Default
(none)
If attributes are enabled for traced errors, all attribute keys found in this list will be sent to New Relic in traced errors. For more information, see the agent attribute rules.
Type
List of strings
Default
(none)
Attribute keys found in this list will not be sent to New Relic in traced errors. For more information, see the agent attribute rules.
Type
Boolean
Default
true
When multiple errors are noticed in a transaction, only the last error will be reported by default. Setting this property to false will instead report only the first error that is noticed. For more information, see the noticeError API.
For example:
error_collector:
ignoreErrorPriority: false
Type
Comma-separated list of Strings
Default
(none)
All specified exception class names specified will not be treated as errors. Deprecated as of Java agent 3.40.0 and replaced by ignore_classes.
For example:
error_collector:
ignore_errors: some.other.MyException
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.
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
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:
Type
String
Default
(none)
Set a display name to decorate the "host:port" label in the New Relic UI.
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.
You can also use the system property newrelic.config.infinite_tracing.trace_observer.host or the environment variable NEW_RELIC_INFINITE_TRACING_TRACE_OBSERVER_HOST.
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:
Type
Boolean
Default
true
Used to enable/disable jar collection and reporting.
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.
Type
Integer
Default
10
The maximum number of jars to process per second. Must be positive.
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_.
Real-time profiling with JFR is on by default in Java agent version 7.1.0. If you are on any other agent version 7.0.0 or higher, you can turn on JFR by changing the value to true.
Type
Boolean
Default
false
Set to true to enable audit logging which will display all JFR metrics and events in each harvest batch. Audit logging is extremely verbose and should only be used for troubleshooting purposes.
Changing these settings in your local agent configuration file are dynamic and does not require a restart of the agent for them to take effect. An example configuration:
application_logging:
enabled: true
forwarding:
enabled: true
max_samples_stored: 10000
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:
Type
Boolean
Default
true
Set to true to enable the core Logs in Context feature. When enabled, additional logging framework instrumentation is enabled, whether or not logs are decorated or sent to New Relic.
Important
Agent releases 7.7.0 and higher has this feature enabled in the agent configuration file by default.
Set to false to completely disable this feature, including the collection of log metrics.
If you are 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:
Type
Boolean
Default
true
Enables the sending of application logs to New Relic.
Important
Agent releases 7.7.0 and higher have this feature enabled in the agent configuration file by default.
Using the log forwarding feature will increase your data ingest, which may affect your billing. For more information, see our documentation about tracking your data ingest.
If you have an existing log forwarding solution and are updating your agent to use automatic logs in context, be sure to disable your old log forwarder. Otherwise, your app will be sending double log lines. Depending on your account, this could result in double billing. For more information, follow the procedures to disable your specific log forwarder.
Set this to true to have your decorated logs sent to New Relic.
Set this to false if you do not want your decorated logs sent to New Relic.
Type
Integer
Default
10,000
A positive integer specifying the maximum number of logs lines per minute to send.
Set this to 0 to effectively disable the sending of logs.
Important
This controls the number of logs sent per minute. Setting max_samples_stored to 0 - or any value less than 12 - does not disable the feature itself, though it does result in no log lines being sent to New Relic.
Set this to a lower value to reduce the amount of log lines sent (may cause log sampling). Set this to a higher value to send more log lines.
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:
Type
Boolean
Default
true
Enables the capture of metrics information about your logs and log levels, which is displayed in a chart on the NR1 summary page.
Leave this set to true to allow the agent to capture metric information about your logs.
Set this to false to disable this feature.
Important
If you disable the collection of log metrics, the log chart on the summary page will appear blank.
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:
Type
Boolean
Default
false
This controls whether locally stored log lines are decorated or not. This is independent of whether log forwarding is enabled or not and is used to support customers that want to use a separate log forwarding solution.
Set this to true to cause the agent to add logs in context linking metadata to log lines stored locally by supported frameworks.
Important
Enabling local log decorating will add linking metadata to your application log files, resulting in an increase in disk storage. Disable this feature if this is unacceptable.
It is not necessary to use local log decorating when log forwarding is enabled. Doing so will cause linking metadata to be added to your log messages unnecessarily, which may be visually distracting.
Set this to false to turn off the local decorating feature. This will not impact the decorating of log lines being sent to New Relic.
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.
Type
Boolean
Default
false
Set to true to roll the logs daily. Overrides the other configuration variables that affect log rotation.
Type
Integer
Default
1
The maximum number of log files to keep when using log rotation.
Type
String
Default
newrelic_agent.log
The unqualified log file name or the string STDOUT which will log to standard out.
Type
String
Default
logs subdirectory where newrelic.jar is located
The log file path.
Tip
If log_file_path is specified, the directory must already exist. If the default value is used, the agent will attempt to create the directory.
Type
String
Default
info
The log verbosity level.
The agent uses its own log file to keep its logging separate from that of your application. Valid options, in order of verboseness, are:
off
severe
warning
info
fine
finer
finest
This setting is dynamic, so running agents will notice changes to newrelic.yml without a JVM restart.
Type
Integer
Default
0
The log file size in kilobytes at which log files are rotated. Set to 0 for no limit.
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.
Type
Boolean
Default
true
Adds message properties to tracer attributes. Set this to false to turn it off.
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:
Type
Boolean
Default
true
Used to enable/disable span event reporting.
Type
Integer
Default
2000
Determines the number of Span events that can be captured during an agent harvest cycle. Available in Java agent 7.4.0 and above.
Important
Increasing the number of Span events can lead to additional agent overhead. A maximum value may be imposed server side by New Relic.
Type
Boolean
Default
true
This setting can be used to turn on or off all attributes for span events. If attributes.enabled at the root level is false, no attributes will be sent to span events regardless on how this property (span_events.attributes.enabled) is set.
Type
List of strings
Default
(none)
If attributes are enabled for span events, all attribute keys found in this list will be sent to New Relic in span_events. For more information, see the agent attribute rules.
Type
List of strings
Default
(none)
All attribute keys found in this list will not be sent to New Relic in span events. For more information, see the agent attribute rules.
These options are set in the strip_exception_messages stanza and unless noted otherwise can be overridden by using a newrelic.config.strip_exception_messagesprefixed system property. This configuration can be enabled 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 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.
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.
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.
Type
Boolean
Default
true
Enable the thread profiler.
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.
Type
Boolean
Default
true
Enable the transaction events service.
Type
Integer
Default
2000
Max
10000
The maximum number of sampled transaction events reported every 60 seconds.
Type
List of maps
Default
None
Important
Unlike other settings, custom_request_headers have to be paired together and must be set in the newrelic.yml file. They can't be overwritten by Java virtual machine arguments (system property) or environment variables.
A list of maps with the paired keys header_name and the optional header_alias. Choose one or more custom HTTP request headers to add as transaction attributes.
You can list multiple header configurations:
transaction_events:
custom_request_headers:
-
header_name: "X-Custom-Header-1"
-
header_name: "X-Custom-Header-2"
header_alias: "CustomHeader2alias"
In the first map set, X-Custom-Header-1 is captured and reported by the agent as the header name for a corresponding value from the request object. The header_name will also be the name of the attribute sent to New Relic.
In the second map set, the request header is X-Custom-Header-2, but the CustomHeader2alias is the name sent to New Relic.
Type
Boolean
Default
true
This setting can be used to turn on or off all attributes for transaction events. If attributes.enabled is false at the root level, then no attributes will be sent to transaction events regardless of how this property is set under transaction_events.
Type
List of Strings
Default
(none)
If attributes are enabled for transaction events, all attribute keys found in this list will be sent to New Relic in transaction events. For more information, see the agent attribute rules.
Type
List of Strings
Default
(none)
All attribute keys found in this list will not be sent to New Relic in transaction events. For more information, see the agent attribute rules.
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.
This setting can be used to turn on or off all attributes for transaction segments. If attributes.enabled at the root level is false, no attributes will be sent to transaction segments regardless on how this property (transaction_segments.attributes.enabled) is set.
Type
List of strings
Default
(none)
If attributes are enabled for transaction segments, all attribute keys found in this list will be sent to New Relic in transaction segments. For more information, see the agent attribute rules.
Type
List of Strings
Default
(none)
All attribute keys found in this list will not be sent to New Relic in transaction segments. For more information, see the agent attribute rules.
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.
Type
Boolean
Default
true
The transaction tracer is enabled by default. Set this to false to turn it off.
Threshold in seconds for query execution time below which the slow query and the EXPLAIN plan (if supported) will not be captured. Relevant to slow queries only when record_sql is set to raw or obfuscated. Relevant to EXPLAIN plans only when explain_enabled is set to true.
Type
Integer
Default
2000
The character limit for the SQL query string. If you have many slow SQL queries with large chunks of information, this could negatively affect performance or how quickly you see your data in New Relic. Increase the value gradually until you find the right balance of information and performance.
Type
Boolean
Default
false
Set to true to enable logging of queries to the agent log file instead of uploading to New Relic. Queries are logged using the record_sql mode.
Type
String
Default
obfuscated
When the transaction tracer is on, query statements can optionally be recorded. The recorder has three modes:
off: Send no queries.
raw: Send the query statement in its original form.
obfuscated: Strips out numeric and string literals.
Type
Boolean
Default
False
Defaulted to true until Java agent version 3.12.1, when it was changed to false.
This option is for Play 2.x+ only. Play/Scala instrumentation can use Thread.getStackTrace() to improve tracer naming, but at the cost of increased overhead.
Type
Integer
Default
0.5
Defines a threshold (in seconds) for collecting stack traces from an SQL call. When SQL statements exceed this threshold, the agent will capture the current stack trace. This is useful for pinpointing where long SQL calls originate from.
Type
Integer
Default
20
Use this setting to control the variety of your transaction traces. top_n is an integer that represents the number of unique, slow transactions that traces will be created for.
If you want transaction traces to more accurately reflect the actual slowest transactions in your app, make this value lower.
If you want to sample a more diverse array of transactions, make the value higher.
A value of 0 would mean that only the slowest transaction is always traced. This is considered not to be optimal, though, because you may have one or two transactions that are always the slowest, and repeatedly seeing those same transaction traces will probably not give you much value.
If the same transaction is often the slowest, the top_n setting allows the Java agent (over time) to sample the slowest n transactions. This gives you greater variety and more insight into your application.
Type
String (float)
Default
apdex_f
The time threshold used to determine when a transaction is eligible to be traced. When the transaction's response time exceeds this threshold, a transaction trace will be recorded and sent to New Relic.
The default is apdex_f (default), which sets the threshold to be the "Frustrated"Apdex level (four times the apdex_t value). You can also set a specific time threshold by entering a float value that represents a number of seconds.
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 collect_slow_queries_from.
By default, high security mode does not allow the agent to collect slow queries. Enable this option to collect Cassandra queries from the DataStax driver, even with high security enabled. If you don't use high security, the agent collects slow queries automatically.
For DataStax driver 2.1.2, add this rule to your allow list:
By default, high security mode does not allow the agent to collect slow queries. Enable this option to collect Cassandra queries from the DataStax driver, even with high security enabled. If you don't use high security, the agent collects slow queries automatically.
For DataStax driver 2.1.2, add this rule to your allow list:
This setting can be used to turn on or off all attributes for transaction traces. If attributes.enabled at the root level is false, no attributes will be sent to transaction traces regardless on how this property (transaction_tracer.attributes.enabled) is set.
Type
List of strings
Default
(none)
If attributes are enabled for transaction traces, all attribute keys found in this list will be sent to New Relic in transaction traces. For more information, see the agent attribute rules.
Type
List of Strings
Default
(none)
All attribute keys found in this list will not be sent to New Relic in transaction traces. For more information, see the agent attribute rules.
Type
Integer
Default
3000
Limits the number of Tokens that can be created per Transaction. Increasing this value may impact performance, because it increases the amount of memory the agent uses and the amount of data sent to New Relic.
Type
Integer
Default
3000
Limits the number of segments that can be created per transaction. Increasing this value may impact performance, because it increases the amount of memory the agent uses and the amount of data sent to New Relic.