• EnglishEspañol日本語한국어Português
  • Log inStart now

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:

  1. Add the prefix NEW_RELIC_ to the setting's name.
  2. 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:

  1. Environment variables
  2. Server-side configuration
  3. Configuration file (newrelic.yml)
  4. 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'
<<: *default_settings
log_level: info
<<: *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:

  4. APP_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 sections 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.


These settings are available for agent configuration. Some settings depend on your New Relic subscription level.

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.

Error Collector

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

For information on ignored and expected errors, see this page on Error Analytics in APM. To set expected errors via the NewRelic::Agent.notice_error Ruby method, consult the Ruby Agent API.

AI monitoring

This section includes Ruby agent configurations for setting up AI monitoring.


You need to enable distributed tracing to capture trace and feedback data. It is turned on by default in Ruby agents 8.0.0 and higher.

Browser Monitoring

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

Transaction Events

Application Logging

The Ruby agent supports APM logs in context. For some tips on configuring logs for the Ruby agent, see Configure Ruby logs in context.

Available logging-related config options include:

Ai Monitoring

This section includes Ruby agent configurations for setting up AI monitoring.


You need to enable distributed tracing to capture trace and feedback data. It is turned on by default in Ruby agents 8.0.0 and higher.


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

Audit Log


Code Level Metrics

Errors inbox configuration

Setting one of the following tags will help you identify which versions of your software are producing the errors.

  • NEW_RELIC_METADATA_SERVICE_VERSION will create tags.service.version on event data containing the version of your code that is deployed, in many cases a semantic version such as 1.2.3, but not always.
  • NEW_RELIC_METADATA_RELEASE_TAG will create tags.releaseTag on event data containing the release tag (such as v0.1.209 or release-209).
  • NEW_RELIC_METADATA_COMMIT will create tags.commit on event data containing the commit sha. The entire sha can be used or just the first seven characters (e.g., 734713b).

An upcoming release of errors inbox will automatically track which versions of your software are producing errors. Any version data will also be displayed in CodeStream.

Cross Application Tracer

Custom Attributes

Custom Events

Datastore Tracer


Use these settings to toggle instrumentation types during agent startup.

Distributed Tracing



Infinite Tracing


Message Tracer


Process Host



Serverless Mode


Slow SQL

Span events

Strip Exception Messages


Thread Profiler


Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.