You can configure the New Relic Ruby agent with settings in a configuration file, environment variables, or programmatically with server-side configuration. This document summarizes the configuration options available for the Ruby agent.
If the default value for a configuration option is (Dynamic), this means the Ruby agent calculates the default at runtime. The value for the config setting defaults to the value of another setting as appropriate.
Configuration methods and precedence
The primary (default) method to configure the Ruby agent is via the configuration file (newrelic.yml) in the config subdirectory. To set configuration values using environment variables:
The Ruby agent follows this order of precedence for configuration:
Environment variables
Server-side configuration
Configuration file (newrelic.yml)
Default configuration settings
In other words, environment variables override all other configuration settings and info, server-side configuration overrides the configuration file and default config settings, and so on.
View and edit config file options
The Ruby agent's newrelic.yml is a standard YAML configuration file. It typically includes a Defaults section at the top, plus sections below for each application environment; for example, Development, Testing, and Production.
The Ruby agent determines which section of the newrelic.yml config file to read from by looking at certain environment variables to derive the application's environment. This can be useful, for example, when you want to use info for the log_level config setting in your production environment, and you want more verbose log_level config settings (such as debug in your development environment.
For non-Rails apps, the Ruby agent looks for the following environment variables, in this order, to determine the application environment:
NEW_RELIC_ENV
RUBY_ENV
RAILS_ENV
APP_ENV
RACK_ENV
If the Ruby agent does not detect values for any of those environment variables, it will default the application environment to development and read from the development section of the newrelic.yml config file.
When running the Ruby agent in a Rails app, the agent first looks for the NEW_RELIC_ENV environment variable to determine the application environment and which section of the newrelic.yml to use. If NEW_RELIC_ENV is not present, the agent uses the Rails environment (RAILS_ENV or RAILS.env, depending on the version of Rails) .
When you edit the config file, be sure to:
Indent only with two spaces.
Indent only where relevant, in stanzas such as error_collector.
If you do not indent correctly, the agent may throw an Unable to parse configuration file error on startup.
To view the most current list of available Ruby agent configuration options, use the rake newrelic:config:docs command. This document describes the most common options.
Update the config file
This documentation applies to the Ruby agent's latest release. For details on earlier versions, refer to the comments in newrelic.yml itself.
To update newrelic.yml file after a new release, use the template in the base directory of the agent gem. When you update to new gem versions, examine or diff config/newrelic.yml and newrelic.yml in the installation directory to take advantage of new configuration options.
Important
Updating the gem does not automatically update config/newrelic.yml.
General
These settings are available for agent configuration. Some settings depend on your New Relic subscription level.
Specify the application name used to aggregate data in the New Relic UI. To report data to multiple apps at the same time, specify a list of names separated by a semicolon ;. For example, MyApp or MyStagingApp;Instance1.
Type
String
Default
nil
Environ variable
NEW_RELIC_ENTITY_GUID
The Entity GUID for the entity running this agent.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_MONITOR_MODE
When true, the agent transmits data about your app to the New Relic collector.
Type
String
Default
"info"
Environ variable
NEW_RELIC_LOG_LEVEL
Sets the level of detail of log messages. Possible log levels, in increasing verbosity, are: error, warn, info or debug.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_HIGH_SECURITY
If true, enables high security mode. Ensure you understand the implications of high security mode before enabling this setting.
Type
String
Default
""
Environ variable
NEW_RELIC_SECURITY_POLICIES_TOKEN
Applies Language Agent Security Policy settings.
Type
String
Default
nil
Environ variable
NEW_RELIC_PROXY_HOST
Defines a host for communicating with the New Relic collector via a proxy server.
Type
Integer
Default
8080
Environ variable
NEW_RELIC_PROXY_PORT
Defines a port for communicating with the New Relic collector via a proxy server.
Type
String
Default
nil
Environ variable
NEW_RELIC_PROXY_USER
Defines a user for communicating with the New Relic collector via a proxy server.
Type
String
Default
nil
Environ variable
NEW_RELIC_PROXY_PASS
Defines a password for communicating with the New Relic collector via a proxy server.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_CAPTURE_PARAMS
When true, the agent captures HTTP request parameters and attaches them to transaction traces, traced errors, and TransactionError events.
When using the capture_params setting, the Ruby agent will not filter sensitive information. Recommendation: To filter sensitive information from request parameters, use the attributes.include setting instead. For details, see the Ruby attribute examples.
Type
String
Default
(Dynamic)
Environ variable
NEW_RELIC_CONFIG_PATH
Path to newrelic.yml. If undefined, the agent checks the following directories (in order): config/newrelic.yml, newrelic.yml, $HOME/.newrelic/newrelic.yml and $HOME/newrelic.yml.
When set to true, forces a synchronous connection to the New Relic collector during application startup. For very short-lived processes, this helps ensure the New Relic agent has time to report.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_SEND_DATA_ON_EXIT
If true, enables the exit handler that sends data to the New Relic collector before shutting down.
Type
Integer
Default
120
Environ variable
NEW_RELIC_TIMEOUT
Defines the maximum number of seconds the agent should spend attempting to connect to the collector.
Type
String
Default
"newrelic_agent.log"
Environ variable
NEW_RELIC_LOG_FILE_NAME
Defines a name for the log file.
Type
String
Default
"log/"
Environ variable
NEW_RELIC_LOG_FILE_PATH
Defines a path to the agent log file, excluding the filename.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_PREPEND_ACTIVE_RECORD_INSTRUMENTATION
If true, uses Module.prepend rather than alias_method for ActiveRecord instrumentation.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_CAPTURE_MEMCACHE_KEYS
Enable or disable the capture of memcache keys from transaction traces.
Backports the faster ActiveRecord connection lookup introduced in Rails 6, which improves agent performance when instrumenting ActiveRecord. Note that this setting may not be compatible with other gems that patch ActiveRecord.
Note that this option now enables tags, which replaced the label feature. You can still query your historical labels.
Type
String
Default
nil
Environ variable
NEW_RELIC_CA_BUNDLE_PATH
Manual override for the path to your local CA bundle. This CA bundle will be used to validate the SSL certificate presented by New Relic's data collection service.
If false, the agent will not add database_name parameter to transaction or slow sql traces.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_CLEAR_TRANSACTION_STATE_AFTER_FORK
If true, the agent will clear Tracer::State in Agent.drop_buffered_data.
Type
String
Default
""
Environ variable
NEW_RELIC_INFINITE_TRACING_TRACE_OBSERVER_HOST
Configures the hostname for the Trace Observer Host. When configured, enables tail-based sampling by sending all recorded spans to a Trace Observer for further sampling decisions, irrespective of any usual agent sampling decision.
Type
Integer
Default
443
Environ variable
NEW_RELIC_INFINITE_TRACING_TRACE_OBSERVER_PORT
Configures the TCP/IP port for the Trace Observer Host
Transaction Tracer
The transaction traces feature collects detailed information from a selection of transactions, including a summary of the calling sequence, a breakdown of time spent, and a list of SQL queries and their query plans (on mysql and postgresql). Available features depend on your New Relic subscription level.
Specify a threshold in seconds. Transactions with a duration longer than this threshold are eligible for transaction traces. Specify a float value or the string apdex_f.
Type
String
Default
"obfuscated"
Environ variable
NEW_RELIC_TRANSACTION_TRACER_RECORD_SQL
Obfuscation level for SQL queries reported in transaction trace nodes.
By default, this is set to obfuscated, which strips out the numeric and string literals.
If you do not want the agent to capture query information, set this to none.
If you want the agent to capture all query information in its original form, set this to raw.
When you enable high security mode, this is automatically set to obfuscated.
Threshold (in seconds) above which the agent will collect explain plans. Relevant only when explain_enabled is true.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_TRANSACTION_TRACER_EXPLAIN_ENABLED
If true, enables the collection of explain plans in transaction traces. This setting will also apply to explain plans in slow SQL traces if slow_sql.explain_enabled is not set separately.
The Browser monitoring page load timing feature (sometimes referred to as real user monitoring or RUM) 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
(Dynamic)
Environ variable
NEW_RELIC_BROWSER_MONITORING_AUTO_INSTRUMENT
If true, enables auto-injection of the JavaScript header for page load timing (sometimes referred to as real user monitoring or RUM).
New Relic dashboards is a resource to gather and visualize data about your software and what it says about your business. With it you can quickly and easily create real-time dashboards to get immediate answers about end-user experiences, clickstreams, mobile activities, and server transactions.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_ANALYTICS_EVENTS_ENABLED
If true, enables analytics event sampling.
Type
Integer
Default
1200
Environ variable
NEW_RELIC_ANALYTICS_EVENTS_MAX_SAMPLES_STORED
Defines the maximum number of request events reported from a single harvest.
Attributes are key-value pairs containing information that determines the properties of an event or transaction. These key-value pairs can be viewed within transaction traces in APM, traced errors in APM, transaction events in dashboards, and page views in dashboards. You can customize exactly which attributes will be sent to each of these destinations.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_ATTRIBUTES_ENABLED
If true, enables capture of attributes for all destinations.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_ENABLED
If true, the agent captures attributes from transaction traces.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_ENABLED
If true, the agent captures attributes from transaction events.
Caution
When Distributed Tracing and/or Infinite Tracing are enabled, information from Transaction Events is applied to the root Span Event of the transaction. Consider applying any attribute settings for Transaction Events to Span Events and/or apply them as Global Attribute settings.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_ENABLED
If true, the agent captures attributes from error collection.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_ENABLED
If true, the agent captures attributes from browser monitoring.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_ENABLED
If true, the agent captures attributes on span events.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_ENABLED
If true, the agent captures attributes on transaction segments.
Type
Array
Default
[]
Environ variable
NEW_RELIC_ATTRIBUTES_EXCLUDE
Prefix of attributes to exclude from all destinations. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_EXCLUDE
Prefix of attributes to exclude from transaction traces. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_EXCLUDE
Prefix of attributes to exclude from transaction events. Allows * as wildcard at end.
Caution
When Distributed Tracing and/or Infinite Tracing are enabled, information from Transaction Events is applied to the root Span Event of the transaction. Consider applying any attribute settings for Transaction Events to Span Events and/or apply them as Global Attribute settings.
Type
Array
Default
[]
Environ variable
NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_EXCLUDE
Prefix of attributes to exclude from error collection. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_EXCLUDE
Prefix of attributes to exclude from browser monitoring. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_EXCLUDE
Prefix of attributes to exclude from span events. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_EXCLUDE
Prefix of attributes to exclude from transaction segments. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_ATTRIBUTES_INCLUDE
Prefix of attributes to include in all destinations. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_INCLUDE
Prefix of attributes to include in transaction traces. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_INCLUDE
Prefix of attributes to include in transaction events. Allows * as wildcard at end.
Caution
When Distributed Tracing and/or Infinite Tracing are enabled, information from Transaction Events is applied to the root Span Event of the transaction. Consider applying any attribute settings for Transaction Events to Span Events and/or apply them as Global Attribute settings.
Type
Array
Default
[]
Environ variable
NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_INCLUDE
Prefix of attributes to include in error collection. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_INCLUDE
Prefix of attributes to include in browser monitoring. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_INCLUDE
Prefix of attributes to include on span events. Allows * as wildcard at end.
Type
Array
Default
[]
Environ variable
NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_INCLUDE
Prefix of attributes to include on transaction segments. Allows * as wildcard at end.
Audit Log
Type
Boolean
Default
false
Environ variable
NEW_RELIC_AUDIT_LOG_ENABLED
If true, enables an audit log which logs communications with the New Relic collector.
Type
String
Default
(Dynamic)
Environ variable
NEW_RELIC_AUDIT_LOG_PATH
Specifies a path to the audit log file (including the filename).
Specify a list of constants that should prevent the agent from starting automatically. Separate individual constants with a comma ,. For example, Rails::Console,UninstrumentedBackgroundJob.
If true, disables instrumentation for ActiveRecord 4, 5, and 6.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_BUNNY
If true, disables instrumentation for the bunny gem.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_CURB
If true, disables instrumentation for the curb gem.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_EXCON
If true, disables instrumentation for the excon gem.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_HTTPCLIENT
If true, disables instrumentation for the httpclient gem.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_NET_HTTP
If true, disables instrumentation for Net::HTTP.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_RACK
If true, prevents the agent from hooking into the to_app method in Rack::Builder to find gems to instrument during application startup.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_RACK_URLMAP
If true, prevents the agent from hooking into Rack::URLMap to install middleware tracing.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_DISABLE_PUMA_RACK
If true, prevents the agent from hooking into the to_app method in Puma::Rack::Builder to find gems to instrument during application startup.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_DISABLE_PUMA_RACK_URLMAP
If true, prevents the agent from hooking into Puma::Rack::URLMap to install middleware tracing.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_TYPHOEUS
If true, the agent won't install instrumentation for the typhoeus gem.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_HTTPRB
If true, the agent won't install instrumentation for the http.rb gem.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_MIDDLEWARE_INSTRUMENTATION
If true, the agent won't wrap third-party middlewares in instrumentation (regardless of whether they are installed via Rack::Builder or Rails).
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISABLE_GRAPE
If true, the agent won't install Grape instrumentation.
Distributed Tracing
Type
Boolean
Default
false
Environ variable
NEW_RELIC_DISTRIBUTED_TRACING_ENABLED
Distributed tracing lets you see the path that a request takes through your distributed system. Enabling distributed tracing changes the behavior of some New Relic features, so carefully consult the transition guide before you enable this feature.
Type
Boolean
Default
false
Environ variable
NEW_RELIC_EXCLUDE_NEWRELIC_HEADER
Allows newrelic distributed tracing headers to be suppressed on outbound requests.
Heroku
Type
Boolean
Default
true
Environ variable
NEW_RELIC_HEROKU_USE_DYNO_NAMES
If true, the agent uses Heroku dyno names as the hostname.
Type
Array
Default
["scheduler", "run"]
Environ variable
NEW_RELIC_HEROKU_DYNO_NAME_PREFIXES_TO_SHORTEN
Ordinarily the agent reports dyno names with a trailing dot and process ID (for example, worker.3). You can remove this trailing data by specifying the prefixes you want to report without trailing data (for example, worker).
Mongo
Type
Boolean
Default
true
Environ variable
NEW_RELIC_MONGO_CAPTURE_QUERIES
If true, the agent captures Mongo queries in transaction traces.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_MONGO_OBFUSCATE_QUERIES
If true, the agent obfuscates Mongo queries in transaction traces.
Specify a threshold in seconds. The agent collects slow SQL queries and explain plans that exceed this threshold.
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_SLOW_SQL_EXPLAIN_ENABLED
If true, the agent collects explain plans in slow SQL queries. If this setting is omitted, the transaction_tracer.explain_enabled setting will be applied as the default setting for explain plans in slow SQL as well.
Type
String
Default
(Dynamic)
Environ variable
NEW_RELIC_SLOW_SQL_RECORD_SQL
Defines an obfuscation level for slow SQL queries. Valid options are obfuscated, raw, or none).
Type
Boolean
Default
false
Environ variable
NEW_RELIC_SLOW_SQL_USE_LONGER_SQL_ID
Generate a longer sql_id for slow SQL traces. sql_id is used for aggregation of similar queries.
Span Events
Type
Boolean
Default
true
Environ variable
NEW_RELIC_SPAN_EVENTS_ENABLED
If true, enables span event sampling.
Type
Integer
Default
10000
Environ variable
NEW_RELIC_SPAN_EVENTS_QUEUE_SIZE
Sets the maximum number of span events to buffer when streaming to the trace observer.
Type
Integer
Default
1000
Environ variable
NEW_RELIC_SPAN_EVENTS_MAX_SAMPLES_STORED
Defines the maximum number of span events reported from a single harvest.
Strip Exception Messages
Type
Boolean
Default
(Dynamic)
Environ variable
NEW_RELIC_STRIP_EXCEPTION_MESSAGES_ENABLED
If true, the agent strips messages from all exceptions except those in the allowlist. Enabled automatically in high security mode.
Specify a list of exceptions you do not want the agent to strip when strip_exception_messages is true. Separate exceptions with a comma. For example, "ImportantException,PreserveMessageException".
If true, the agent automatically detects that it is running in an AWS environment.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_UTILIZATION_DETECT_AZURE
If true, the agent automatically detects that it is running in an Azure environment.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_UTILIZATION_DETECT_GCP
If true, the agent automatically detects that it is running in an Google Cloud Platform environment.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_UTILIZATION_DETECT_PCF
If true, the agent automatically detects that it is running in a Pivotal Cloud Foundry environment.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_UTILIZATION_DETECT_DOCKER
If true, the agent automatically detects that it is running in Docker.
Type
Boolean
Default
true
Environ variable
NEW_RELIC_UTILIZATION_DETECT_KUBERNETES
If true, the agent automatically detects that it is running in Kubernetes.
For more help
Additional documentation resources include:
New Relic for Ruby (compatibility and requirements, installation, configuration, troubleshooting, known issues, advanced features and configuration, beta releases)