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
orMyStagingApp;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
ordebug
. - 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, andTransactionError
events.When using the
capture_params
setting, the Ruby agent will not filter sensitive information. Recommendation: To filter sensitive information from request parameters, use theattributes.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 addhost
orport_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 adddatabase_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 clearTracer::State
inAgent.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
.
- If you do not want the agent to capture query information, set this to
- 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 ifslow_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.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.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.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.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 theto_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 theto_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, thetransaction_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
, ornone
). - 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)