Ruby agent configuration

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:

Add the prefix NEW_RELIC_ to the setting's name.
Replace any periods . with underscores _.

You can also configure a few values in the UI via server-side configuration.

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.

Here is an example newrelic.yml config file:

common: &default_settings
  license_key: 'YOUR_LICENSE_KEY'
  app_name: 'My Application Name'
production:
  <<: *default_settings
  log_level: info
development: 
  <<: *default_settings
  log_level: debug

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.

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.

license_key

Type	String
Default	`""`
Environ variable	`NEW_RELIC_LICENSE_KEY`

Your New Relic license key.

agent_enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_AGENT_ENABLED`

If true, allows the Ruby agent to run.

app_name

Type	String
Default	(Dynamic)
Environ variable	`NEW_RELIC_APP_NAME`

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.

entity_guid

Type	String
Default	`nil`
Environ variable	`NEW_RELIC_ENTITY_GUID`

The Entity GUID for the entity running this agent.

monitor_mode

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_MONITOR_MODE`

When true, the agent transmits data about your app to the New Relic collector.

log_level

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.

high_security

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.

security_policies_token

Type	String
Default	`""`
Environ variable	`NEW_RELIC_SECURITY_POLICIES_TOKEN`

Applies Language Agent Security Policy settings.

proxy_host

Type	String
Default	`nil`
Environ variable	`NEW_RELIC_PROXY_HOST`

Defines a host for communicating with the New Relic collector via a proxy server.

proxy_port

Type	Integer
Default	`8080`
Environ variable	`NEW_RELIC_PROXY_PORT`

Defines a port for communicating with the New Relic collector via a proxy server.

proxy_user

Type	String
Default	`nil`
Environ variable	`NEW_RELIC_PROXY_USER`

Defines a user for communicating with the New Relic collector via a proxy server.

proxy_pass

Type	String
Default	`nil`
Environ variable	`NEW_RELIC_PROXY_PASS`

Defines a password for communicating with the New Relic collector via a proxy server.

capture_params

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.

config_path

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.

apdex_t

Type	Float
Default	`0.5`
Environ variable	`NEW_RELIC_APDEX_T`

DEPRECATED Deprecated. For agent versions 3.5.0 or higher, set your Apdex T via the New Relic UI.

sync_startup

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_SYNC_STARTUP`

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.

send_data_on_exit

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.

timeout

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.

log_file_name

Type	String
Default	`"newrelic_agent.log"`
Environ variable	`NEW_RELIC_LOG_FILE_NAME`

Defines a name for the log file.

log_file_path

Type	String
Default	`"log/"`
Environ variable	`NEW_RELIC_LOG_FILE_PATH`

Defines a path to the agent log file, excluding the filename.

prepend_active_record_instrumentation

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_PREPEND_ACTIVE_RECORD_INSTRUMENTATION`

If true, uses Module.prepend rather than alias_method for ActiveRecord instrumentation.

capture_memcache_keys

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_CAPTURE_MEMCACHE_KEYS`

Enable or disable the capture of memcache keys from transaction traces.

message_tracer.segment_parameters.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_MESSAGE_TRACER_SEGMENT_PARAMETERS_ENABLED`

If true, the agent will collect metadata about messages and attach them as segment parameters.

marshaller

Type	String
Default	`"json"`
Environ variable	`NEW_RELIC_MARSHALLER`

Specifies a marshaller for transmitting data to the New Relic collector. Currently json is the only valid value for this setting.

backport_fast_active_record_connection_lookup

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_BACKPORT_FAST_ACTIVE_RECORD_CONNECTION_LOOKUP`

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.

labels

Type	String
Default	`""`
Environ variable	`NEW_RELIC_LABELS`

Attach tags to this app.

Note that this option now enables tags, which replaced the label feature. You can still query your historical labels.

ca_bundle_path

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.

datastore_tracer.instance_reporting.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_DATASTORE_TRACER_INSTANCE_REPORTING_ENABLED`

If false, the agent will not report datastore instance metrics, nor add host or port_path_or_id parameters to transaction or slow sql traces.

datastore_tracer.database_name_reporting.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_DATASTORE_TRACER_DATABASE_NAME_REPORTING_ENABLED`

If false, the agent will not add database_name parameter to transaction or slow sql traces.

clear_transaction_state_after_fork

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.

infinite_tracing.trace_observer.host

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.

infinite_tracing.trace_observer.port

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.

transaction_tracer.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_ENABLED`

If true, enables collection of transaction traces.

transaction_tracer.transaction_threshold

Type	Float
Default	(Dynamic)
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_TRANSACTION_THRESHOLD`

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.

transaction_tracer.record_sql

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.

transaction_tracer.record_redis_arguments

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_RECORD_REDIS_ARGUMENTS`

If true, the agent records Redis command arguments in transaction traces.

transaction_tracer.capture_attributes

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_CAPTURE_ATTRIBUTES`

DEPRECATED Deprecated; use transaction_tracer.attributes.enabled instead.

transaction_tracer.explain_threshold

Type	Float
Default	`0.5`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_EXPLAIN_THRESHOLD`

Threshold (in seconds) above which the agent will collect explain plans. Relevant only when explain_enabled is true.

transaction_tracer.explain_enabled

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.

transaction_tracer.stack_trace_threshold

Type	Float
Default	`0.5`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_STACK_TRACE_THRESHOLD`

Specify a threshold in seconds. The agent includes stack traces in transaction trace nodes when the stack trace duration exceeds this threshold.

transaction_tracer.limit_segments

Type	Integer
Default	`4000`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_LIMIT_SEGMENTS`

Maximum number of transaction trace nodes to record in a single transaction trace.

Error Collector

The agent collects and reports all uncaught exceptions by default. These configuration options allow you to customize the error collection.

error_collector.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_ENABLED`

If true, the agent captures traced errors and error count metrics.

error_collector.capture_attributes

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_CAPTURE_ATTRIBUTES`

DEPRECATED Deprecated; use error_collector.attributes.enabled instead.

error_collector.ignore_errors

Type	String
Default	`"ActionController::RoutingError,Sinatra::NotFound"`
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERRORS`

Specify a comma-delimited list of error classes that the agent should ignore.

error_collector.max_backtrace_frames

Type	Integer
Default	`50`
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_MAX_BACKTRACE_FRAMES`

Defines the maximum number of frames in an error backtrace. Backtraces over this amount are truncated at the beginning and end.

error_collector.capture_events

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_CAPTURE_EVENTS`

If true, the agent collects TransactionError events.

error_collector.max_event_samples_stored

Type	Integer
Default	`100`
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_MAX_EVENT_SAMPLES_STORED`

Defines the maximum number of TransactionError events sent to New Relic per harvest cycle.

Browser Monitoring

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.

browser_monitoring.auto_instrument

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

browser_monitoring.capture_attributes

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_BROWSER_MONITORING_CAPTURE_ATTRIBUTES`

DEPRECATED Deprecated; use browser_monitoring.attributes.enabled instead.

Analytics Events

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.

analytics_events.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_ANALYTICS_EVENTS_ENABLED`

If true, enables analytics event sampling.

analytics_events.max_samples_stored

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.

analytics_events.capture_attributes

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_ANALYTICS_EVENTS_CAPTURE_ATTRIBUTES`

DEPRECATED Deprecated; use transaction_events.attributes.enabled instead.

Attributes

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.

attributes.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_ATTRIBUTES_ENABLED`

If true, enables capture of attributes for all destinations.

transaction_tracer.attributes.enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_ENABLED`

If true, the agent captures attributes from transaction traces.

transaction_events.attributes.enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_ENABLED`

If true, the agent captures attributes from transaction events.

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.

error_collector.attributes.enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_ENABLED`

If true, the agent captures attributes from error collection.

browser_monitoring.attributes.enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_ENABLED`

If true, the agent captures attributes from browser monitoring.

span_events.attributes.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_ENABLED`

If true, the agent captures attributes on span events.

transaction_segments.attributes.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_ENABLED`

If true, the agent captures attributes on transaction segments.

attributes.exclude

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_ATTRIBUTES_EXCLUDE`

Prefix of attributes to exclude from all destinations. Allows * as wildcard at end.

transaction_tracer.attributes.exclude

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_EXCLUDE`

Prefix of attributes to exclude from transaction traces. Allows * as wildcard at end.

transaction_events.attributes.exclude

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_EXCLUDE`

Prefix of attributes to exclude from transaction events. Allows * as wildcard at end.

error_collector.attributes.exclude

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_EXCLUDE`

Prefix of attributes to exclude from error collection. Allows * as wildcard at end.

browser_monitoring.attributes.exclude

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_EXCLUDE`

Prefix of attributes to exclude from browser monitoring. Allows * as wildcard at end.

span_events.attributes.exclude

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_EXCLUDE`

Prefix of attributes to exclude from span events. Allows * as wildcard at end.

transaction_segments.attributes.exclude

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_EXCLUDE`

Prefix of attributes to exclude from transaction segments. Allows * as wildcard at end.

attributes.include

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_ATTRIBUTES_INCLUDE`

Prefix of attributes to include in all destinations. Allows * as wildcard at end.

transaction_tracer.attributes.include

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_INCLUDE`

Prefix of attributes to include in transaction traces. Allows * as wildcard at end.

transaction_events.attributes.include

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_INCLUDE`

Prefix of attributes to include in transaction events. Allows * as wildcard at end.

error_collector.attributes.include

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_INCLUDE`

Prefix of attributes to include in error collection. Allows * as wildcard at end.

browser_monitoring.attributes.include

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_INCLUDE`

Prefix of attributes to include in browser monitoring. Allows * as wildcard at end.

span_events.attributes.include

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_INCLUDE`

Prefix of attributes to include on span events. Allows * as wildcard at end.

transaction_segments.attributes.include

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

audit_log.enabled

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.

audit_log.path

Type	String
Default	(Dynamic)
Environ variable	`NEW_RELIC_AUDIT_LOG_PATH`

Specifies a path to the audit log file (including the filename).

audit_log.endpoints

Type	Array
Default	`[".*"]`
Environ variable	`NEW_RELIC_AUDIT_LOG_ENDPOINTS`

List of allowed endpoints to include in audit log

Autostart

autostart.blacklisted_constants

Type	String
Default	`"Rails::Console"`
Environ variable	`NEW_RELIC_AUTOSTART_BLACKLISTED_CONSTANTS`

Deprecated. For agent versions 6.8.0 or higher, use autostart.denylisted_constants instead.

autostart.denylisted_constants

Type	String
Default	`"Rails::Console"`
Environ variable	`NEW_RELIC_AUTOSTART_DENYLISTED_CONSTANTS`

Specify a list of constants that should prevent the agent from starting automatically. Separate individual constants with a comma ,. For example, Rails::Console,UninstrumentedBackgroundJob.

autostart.blacklisted_executables

Type	String
Default	`"irb,rspec"`
Environ variable	`NEW_RELIC_AUTOSTART_BLACKLISTED_EXECUTABLES`

Deprecated. For agent versions 6.8.0 or higher, use autostart.denylisted_executables instead.

autostart.denylisted_executables

Type	String
Default	(Dynamic)
Environ variable	`NEW_RELIC_AUTOSTART_DENYLISTED_EXECUTABLES`

Defines a comma-delimited list of executables that the agent should not instrument. For example, rake,my_ruby_script.rb.

autostart.blacklisted_rake_tasks

Type	String
Default	"about,assets:clean,assets:clobber,assets:environment,assets:precompile,assets:precompile:all,db:create,db:drop,db:fixtures:load,db:migrate,db:migrate:status,db:rollback,db:schema:cache:clear,db:schema:cache:dump,db:schema:dump,db:schema:load,db:seed,db:setup,db:structure:dump,db:version,doc:app,log:clear,middleware,notes,notes:custom,rails:template,rails:update,routes,secret,spec,spec:features,spec:requests,spec:controllers,spec:helpers,spec:models,spec:views,spec:routing,spec:rcov,stats,test,test:all,test:all:db,test:recent,test:single,test:uncommitted,time:zones:all,tmp:clear,tmp:create,webpacker:compile"
Environ variable	`NEW_RELIC_AUTOSTART_BLACKLISTED_RAKE_TASKS`

Deprecated. For agent versions 6.8.0 or higher, use autostart.denylisted_rake_tasks instead.

autostart.denylisted_rake_tasks

Type	String
Default	(Dynamic)
Environ variable	`NEW_RELIC_AUTOSTART_DENYLISTED_RAKE_TASKS`

Defines a comma-delimited list of Rake tasks that the agent should not instrument. For example, assets:precompile,db:migrate.

Cross Application Tracer

cross_application_tracer.enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_CROSS_APPLICATION_TRACER_ENABLED`

If true, enables cross-application tracing.

Custom Attributes

custom_attributes.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_CUSTOM_ATTRIBUTES_ENABLED`

If false, custom attributes will not be sent on queried events.

Custom Events

custom_insights_events.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_ENABLED`

If true, the agent captures New Relic custom events.

custom_insights_events.max_samples_stored

Type	Integer
Default	`1000`
Environ variable	`NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_SAMPLES_STORED`

Specify a maximum number of custom events to buffer in memory at a time.

Disabling

Use these settings to toggle instrumentation types during agent startup.

disable_rake

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_RAKE`

If true, disables Rake instrumentation.

disable_samplers

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_SAMPLERS`

If true, disables the collection of sampler metrics. Sampler metrics are metrics that are not event-based (such as CPU time or memory usage).

disable_resque

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_RESQUE`

If true, disables Resque instrumentation.

disable_sidekiq

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_SIDEKIQ`

If true, disables Sidekiq instrumentation.

disable_dj

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_DJ`

If true, disables Delayed::Job instrumentation.

disable_sinatra

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_SINATRA`

If true , disables Sinatra instrumentation.

disable_sinatra_auto_middleware

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_SINATRA_AUTO_MIDDLEWARE`

If true, disables agent middleware for Sinatra. This middleware is responsible for advanced feature support such as cross application tracing, page load timing, and error collection.

disable_view_instrumentation

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_VIEW_INSTRUMENTATION`

If true, disables view instrumentation.

disable_activerecord_instrumentation

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_DISABLE_ACTIVERECORD_INSTRUMENTATION`

If true, disables active record instrumentation.

disable_data_mapper

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_DATA_MAPPER`

If true, disables DataMapper instrumentation.

disable_activejob

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_ACTIVEJOB`

If true, disables ActiveJob instrumentation.

disable_action_cable_instrumentation

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_ACTION_CABLE_INSTRUMENTATION`

If true, disables Action Cable instrumentation.

disable_active_storage

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_ACTIVE_STORAGE`

If true, disables ActiveStorage instrumentation.

disable_memcached

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_DISABLE_MEMCACHED`

If true, disables instrumentation for the memcached gem.

disable_memcache_client

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_DISABLE_MEMCACHE_CLIENT`

If true, disables instrumentation for the memcache-client gem.

disable_dalli

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_DISABLE_DALLI`

If true, disables instrumentation for the dalli gem.

disable_dalli_cas_client

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_DISABLE_DALLI_CAS_CLIENT`

If true, disables instrumentation for the dalli gem's additional CAS client support.

disable_memcache_instrumentation

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_MEMCACHE_INSTRUMENTATION`

If true, disables memcache instrumentation.

disable_gc_profiler

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_GC_PROFILER`

If true, disables the use of GC::Profiler to measure time spent in garbage collection

disable_sequel_instrumentation

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_SEQUEL_INSTRUMENTATION`

If true, disables Sequel instrumentation.

disable_database_instrumentation

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_DATABASE_INSTRUMENTATION`

DEPRECATED Deprecated; use disable_sequel_instrumentation instead.

disable_mongo

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_MONGO`

If true, the agent won't install instrumentation for the Mongo gem.

disable_redis

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_REDIS`

If true, the agent won't install instrumentation for Redis.

disable_vm_sampler

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_VM_SAMPLER`

If true, the agent won't sample performance measurements from the Ruby VM.

disable_memory_sampler

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_MEMORY_SAMPLER`

If true, the agent won't sample the memory usage of the host process.

disable_cpu_sampler

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_CPU_SAMPLER`

If true, the agent won't sample the CPU usage of the host process.

disable_delayed_job_sampler

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_DELAYED_JOB_SAMPLER`

If true, the agent won't measure the depth of Delayed Job queues.

disable_active_record_4

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_ACTIVE_RECORD_4`

DEPRECATED Deprecated. For agent versions 6.3 or higher, use disable_active_record_notifications instead.

disable_active_record_5

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_ACTIVE_RECORD_5`

DEPRECATED Deprecated. For agent versions 6.3 or higher, use disable_active_record_notifications instead.

disable_active_record_notifications

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_ACTIVE_RECORD_NOTIFICATIONS`

If true, disables instrumentation for ActiveRecord 4, 5, and 6.

disable_bunny

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_BUNNY`

If true, disables instrumentation for the bunny gem.

disable_curb

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_CURB`

If true, disables instrumentation for the curb gem.

disable_excon

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_EXCON`

If true, disables instrumentation for the excon gem.

disable_httpclient

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_HTTPCLIENT`

If true, disables instrumentation for the httpclient gem.

disable_net_http

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_NET_HTTP`

If true, disables instrumentation for Net::HTTP.

disable_rack

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.

disable_rack_urlmap

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.

disable_puma_rack

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.

disable_puma_rack_urlmap

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.

disable_typhoeus

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_TYPHOEUS`

If true, the agent won't install instrumentation for the typhoeus gem.

disable_httprb

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_HTTPRB`

If true, the agent won't install instrumentation for the http.rb gem.

disable_middleware_instrumentation

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

disable_grape

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_DISABLE_GRAPE`

If true, the agent won't install Grape instrumentation.

Distributed Tracing

distributed_tracing.enabled

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.

exclude_newrelic_header

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_EXCLUDE_NEWRELIC_HEADER`

Allows newrelic distributed tracing headers to be suppressed on outbound requests.

Heroku

heroku.use_dyno_names

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_HEROKU_USE_DYNO_NAMES`

If true, the agent uses Heroku dyno names as the hostname.

heroku.dyno_name_prefixes_to_shorten

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

mongo.capture_queries

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_MONGO_CAPTURE_QUERIES`

If true, the agent captures Mongo queries in transaction traces.

mongo.obfuscate_queries

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_MONGO_OBFUSCATE_QUERIES`

If true, the agent obfuscates Mongo queries in transaction traces.

Process Host

process_host.display_name

Type	String
Default	(Dynamic)
Environ variable	`NEW_RELIC_PROCESS_HOST_DISPLAY_NAME`

Specify a custom host name for display in the New Relic UI.

Rake

rake.tasks

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_RAKE_TASKS`

Specify an array of Rake tasks to automatically instrument.

rake.connect_timeout

Type	Integer
Default	`10`
Environ variable	`NEW_RELIC_RAKE_CONNECT_TIMEOUT`

Timeout for waiting on connect to complete before a rake task

Resque

resque.capture_params

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_RESQUE_CAPTURE_PARAMS`

DEPRECATED If true, enables the capture of job arguments for transaction traces and traced errors in Resque.

Rules

rules.ignore_url_regexes

Type	Array
Default	`[]`
Environ variable	`NEW_RELIC_RULES_IGNORE_URL_REGEXES`

Define transactions you want the agent to ignore, by specifying a list of patterns matching the URI you want to ignore.

Sidekiq

sidekiq.capture_params

Type	Boolean
Default	`false`
Environ variable	`NEW_RELIC_SIDEKIQ_CAPTURE_PARAMS`

DEPRECATED If true, enables the capture of job arguments for transaction traces and traced errors in Sidekiq.

Slow SQL

slow_sql.enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_SLOW_SQL_ENABLED`

If true, the agent collects slow SQL queries.

slow_sql.explain_threshold

Type	Float
Default	(Dynamic)
Environ variable	`NEW_RELIC_SLOW_SQL_EXPLAIN_THRESHOLD`

Specify a threshold in seconds. The agent collects slow SQL queries and explain plans that exceed this threshold.

slow_sql.explain_enabled

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.

slow_sql.record_sql

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

slow_sql.use_longer_sql_id

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

span_events.enabled

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_SPAN_EVENTS_ENABLED`

If true, enables span event sampling.

span_events.queue_size

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.

span_events.max_samples_stored

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

strip_exception_messages.enabled

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.

strip_exception_messages.whitelist

Type	String
Default	`""`
Environ variable	`NEW_RELIC_STRIP_EXCEPTION_MESSAGES_WHITELIST`

DEPRECATED Deprecated. For agent versions 6.8.0 or higher, use strip_exception_messages.allowed_classes instead.

strip_exception_messages.allowed_classes

Type	String
Default	`""`
Environ variable	`NEW_RELIC_STRIP_EXCEPTION_MESSAGES_ALLOWED_CLASSES`

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

Thread Profiler

thread_profiler.enabled

Type	Boolean
Default	(Dynamic)
Environ variable	`NEW_RELIC_THREAD_PROFILER_ENABLED`

If true, enables use of the thread profiler.

Utilization

utilization.detect_aws

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_UTILIZATION_DETECT_AWS`

If true, the agent automatically detects that it is running in an AWS environment.

utilization.detect_azure

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.

utilization.detect_gcp

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.

utilization.detect_pcf

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.

utilization.detect_docker

Type	Boolean
Default	`true`
Environ variable	`NEW_RELIC_UTILIZATION_DETECT_DOCKER`

If true, the agent automatically detects that it is running in Docker.

utilization.detect_kubernetes

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)
Transaction traces and Configuring transaction traces (detailed information about New Relic's Transaction Traces feature)

Ruby agent

Getting started

Installation

Configuration

Features

API guides

Instrumented gems

Background jobs

Attributes

Troubleshooting

Configuration methods and precedence

View and edit config file options

Update the config file

General

Transaction Tracer

Error Collector

Browser Monitoring

Analytics Events

Attributes

Audit Log

Autostart

Cross Application Tracer

Custom Attributes

Custom Events

Disabling

Distributed Tracing

Heroku

Mongo

Process Host

Rake

Resque

Rules

Sidekiq

Slow SQL

Span Events

Strip Exception Messages

Thread Profiler

Utilization

For more help