--- title: Configuration overview source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-overview --- 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: 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](https://docs.newrelic.com/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 find 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 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 [#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](https://docs.newrelic.com/docs/agents/manage-apm-agents/troubleshooting/find-agent-root-directory#ruby-agent) to take advantage of new configuration options. > #### ⚠️ IMPORTANT > > Updating the gem does not automatically update `config/newrelic.yml`. > #### ⚠️ IMPORTANT > > The two settings you **must** configure are your app name and license key — set via `app_name` and `license_key` in `newrelic.yml` (or the `NEW_RELIC_APP_NAME` and `NEW_RELIC_LICENSE_KEY` environment variables). All other settings are optional. ## Settings reference [#settings-reference] All configuration settings are documented in the sub-pages below. Each setting shows its type, default value, and environment variable equivalent. | Settings page | What it covers | | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | [General settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-general-settings) | Core agent behavior: app name, license key, proxy, logging, and general agent behavior | | [Transaction tracer settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-transaction-tracer-settings) | Slow transaction capture, SQL recording, and explain plans | | [Error collector settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-error-collector-settings) | Which errors are captured, ignored, or marked as expected | | [Browser monitoring settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-browser-monitoring-settings) | Page load timing injection and Content Security Policy nonce support | | [Distributed tracing settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-distributed-tracing-settings) | Distributed tracing, Infinite Tracing, and span event collection | | [Logs in context settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-logs-in-context-settings) | Log forwarding, local decoration, custom attributes on log events, and log metrics | | [AI monitoring settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-ai-monitoring-settings) | LLM instrumentation and input/output content capture | | [Attributes settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-attributes-settings) | Which key-value pairs are captured and sent to each destination | | [Other settings](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration-other-settings) | Transaction events, audit log, autostart, cloud integration, Sidekiq, serverless, and more |