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.

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:

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 will use the Rails environment (RAILS_ENV or RAILS.env, depending on the version of Rails) to determine the application environment and which section of the newrelic.yml to use. You can still use the NEW_RELIC_* environment variables to take precedence over the other settings in your newrelic.yml config file, but NEW_RELIC_ENV will not be used to determine the application environment.

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

While the setting specifies SSL, the setting refers to HTTPS encryption to the latest industry standards. The agent communicates with New Relic via HTTPS by default, and New Relic requires HTTPS for all traffic to New Relic APM and the New Relic REST API.

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.

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.

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.

labels

Type

String

Default

""

Environ variable

NEW_RELIC_LABELS

A dictionary of label names and values that will be applied to the data sent from this agent. May also be expressed as a semicolon-delimited ; string of colon-separated : pairs. For example, Server:One;Data Center:Primary.

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 TransactionState in Agent.drop_buffered_data.

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.

Browser Monitoring

New Relic Browser's 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).

Analytics Events

New Relic Insights is a software analytics 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.

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 New Relic APM, traced errors in New Relic APM, transaction events in Insights, and page views in Insights. 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.

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.

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.

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.

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

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

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

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.

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

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.

Specify a whitelist 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".