---
title: Ruby agent configuration
tags:
  - Agents
  - Ruby agent
  - Configuration
metaDescription: 'APM for Ruby: how to configure the Ruby agent, including editing the config file and setting environment variables.'
redirects:
  - /docs/agents/ruby-agent/configuration/ruby-agent-configuration
  - /docs/ruby/ruby-agent-configuration
  - /docs/agents/ruby-agent/installation-and-configuration/ruby-agent-configuration
  - /docs/agents/ruby-agent/installation-configuration/ruby-agent-configuration
---

<CONTRIBUTOR_NOTE>
  This file is automatically generated from values defined in `lib/new_relic/agent/configuration/default_source.rb`.
  Make all changes directly to `default_source.rb.`
  Submit PRs or raise issues at: https://github.com/newrelic/newrelic-ruby-agent
</CONTRIBUTOR_NOTE>

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 [#Options]

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](/docs/agents/manage-apm-agents/configuration/server-side-agent-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 [#Edit]

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 (`Development`, `Test`, `Staging`, 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 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:

```yaml
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
```

The Ruby agent looks for the following environment variables, in this order, to find the application environment:

1. `NEW_RELIC_ENV`
2. `RUBY_ENV`
3. `RAILS_ENV`
4. `APP_ENV`
5. `RACK_ENV`

If the Ruby agent doesn't 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`).

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 [#Updates]

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](/docs/agents/manage-apm-agents/troubleshooting/find-agent-root-directory#ruby-agent) to take advantage of new configuration options.

<Callout variant="important">
  Updating the gem does not automatically update `config/newrelic.yml`.
</Callout>

<% sections.each do |(section_key, section_name, section_description, configs)| %>
## <%=section_name%>

<%= "#{section_description}" unless section_description.nil? %>

<CollapserGroup>
  <% configs.each do |config|%>
  <Collapser id="<%= config[:key].gsub('.', '-') %>" title="<%=config[:key]%>">
    <table>
      <tbody>
        <tr><th>Type</th><td><%=config[:type]%></td></tr>
        <tr><th>Default</th><td>`<%=config[:default]%>`</td></tr>
        <tr><th>Environ variable</th><td>`<%=config[:env_var]%>`</td></tr>
      </tbody>
    </table>

  <%=config[:description]%>
  </Collapser>
  <% end %>
</CollapserGroup>
<% end %>