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.
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
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 (
- 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.
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,
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:
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, 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.
This documentation applies to the Ruby agent's latest release. For details on earlier versions, refer to the comments in
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
newrelic.yml in the installation directory to take advantage of new configuration options.
Updating the gem does not automatically update
These settings are available for agent configuration. Some settings depend on your New Relic subscription level.
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.
The agent collects and reports all uncaught exceptions by default. These configuration options allow you to customize the error collection.
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.
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
Use these settings to toggle instrumentation types during agent startup.
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.