> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AppSignal Ruby configuration

export const Compatibility = ({versions = [], label = "Available in"}) => {
  if (!Array.isArray(versions) || versions.length === 0) {
    return null;
  }
  const defaultPillStyle = {
    borderColor: "#d4d4d8",
    background: "#f4f4f5",
    color: "#3f3f46"
  };
  const pillStyles = {
    "AppSignal for Elixir": {
      background: "#f3e8ff",
      borderColor: "#d8b4fe",
      color: "#6b21a8"
    },
    "AppSignal for Front-end": {
      background: "#fef9c3",
      borderColor: "#fde047",
      color: "#854d0e"
    },
    "AppSignal for Go": {
      background: "#ccfbf1",
      borderColor: "#5eead4",
      color: "#115e59"
    },
    "AppSignal for JavaScript": {
      background: "#fef9c3",
      borderColor: "#fde047",
      color: "#854d0e"
    },
    "AppSignal for Node.js": {
      background: "#dcfce7",
      borderColor: "#86efac",
      color: "#166534"
    },
    "AppSignal for Python": {
      background: "#dbeafe",
      borderColor: "#93c5fd",
      color: "#1e40af"
    },
    "AppSignal for Ruby": {
      background: "#fee2e2",
      borderColor: "#fca5a5",
      color: "#991b1b"
    },
    "AppSignal for Rust": {
      background: "#ffedd5",
      borderColor: "#fdba74",
      color: "#9a3412"
    }
  };
  const getPillStyle = name => ({
    ...defaultPillStyle,
    ...pillStyles[name] || ({})
  });
  return <div className="not-prose my-4 rounded-lg border border-zinc-200 bg-zinc-50 px-4 py-3 text-sm dark:border-white/10 dark:bg-white/5">
      <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
        <span className="font-semibold text-zinc-700 dark:text-zinc-200">
          {label}:
        </span>
        {versions.map((v, i) => <span key={`${v.name}-${v.version}-${i}`} className="inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium" style={getPillStyle(v.name)}>
            <span>{v.name}</span>
            <span className="opacity-70">
              {v.version}
              {v.exact ? "" : "+"}
            </span>
          </span>)}
      </div>
    </div>;
};

Configuration. Important, because without it the AppSignal Ruby gem won't
know which application it's instrumenting or in which environment.

In this topic we'll explain how to configure AppSignal, what can be configured
in the Ruby gem, what's the minimal configuration needed and how the
configuration is loaded.

## Minimal required configuration

For applications to report data to AppSignal the following configuration is required. All other configuration is optional.

* Application name - [name option](/ruby/configuration/options#option-name)
* Application environment - [environment](/ruby/configuration/options#option-appsignal_app_env) (automatically detected or set with an environment variable)
* Application push API key - [push\_api\_key option](/ruby/configuration/options#option-push_api_key)
* AppSignal to be active - [active option](/ruby/configuration/options#option-active)

For Rails apps you do not have to configure your application name, AppSignal will use the name of your application by default.

If you use a framework that is aware of environments and [is supported by the AppSignal gem](/ruby/integrations), the environment is detected automatically.

<CodeGroup>
  ```ruby Ruby theme={null}
  # config/appsignal.rb
  Appsignal.configure do |config|
    config.activate_if_environment(:development, :staging, :production)
    config.name = "My app"
    config.push_api_key = "1234-1234-1234"
  end
  ```

  ```bash Bash theme={null}
  # Environment variables
  export APPSIGNAL_APP_NAME="My app"
  export APPSIGNAL_APP_ENV="production"
  export APPSIGNAL_PUSH_API_KEY="1234-1234-1234"
  ```

  ```yaml YAML theme={null}
  # config/appsignal.yml
  # Legacy config method
  production:
    active: true
    name: "My app"
    push_api_key: "1234-1234-1234"
  ```
</CodeGroup>

## Configuration methods

There are several different configuration methods available in our Ruby gem.
To see in which order they're loaded and which configuration method overrides values from other sources, see our [configuration load order](/ruby/configuration/load-order) page.

### Ruby configuration file

<Compatibility versions={[{ name: "AppSignal for Ruby", version: "4.2.0" }]} />

The AppSignal Ruby gem can be configured using a Ruby configuration file. When selected, the installer automatically creates a `config/appsignal.rb` file. This file includes default configuration settings that can be customized to meet your application's specific needs.

This configuration file is read when `Appsignal.start` is called, which is called automatically for most of our [integrations](/ruby/integrations). Please read the [integrating AppSignal instructions](/ruby/instrumentation/integrating-appsignal) if `Appsignal.start` is not automatically called.

The configuration file configures our Ruby gem using [the `Appsignal.configure` helper](#appsignalconfigure-helper). Please read the [the `Appsignal.configure` helper](#appsignalconfigure-helper) section for more details on how to use it.

The [YAML configuration file](#yaml-configuration-file) will not be read when this file is present.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Enable AppSignal for the following environments
    config.activate_if_environment(:development, :staging, :production)

    # Ignore this action for all environments
    config.ignore_actions << "My global action"

    # Ignore this action for only the production environment
    if config.env?(:production)
      config.ignore_actions << "My production action"
    end

    # Ignore this action for only the staging environment
    if config.env?(:staging)
      config.ignore_actions << "My staging action"
    end
  end
  ```
</CodeGroup>

### `Appsignal.configure` helper

The `Appsignal.configure` helper can be used to configure AppSignal using Ruby code. The [Ruby configuration file](#ruby-configuration-file) uses this helper and it can also be used directly in your application.

If your app uses `Appsignal.configure` outside the `config/appsignal.rb` file, like a Rails initializer, please read [this section on the differences in behavior](#using-the-appsignalconfigure-helper-in-your-application) this has.

Set configuration options inside the `Appsignal.configure` block by calling the writer methods on the `config` object. [Configuration options](/ruby/configuration/options) can be set using the "Config file key" listed for the configuration options. For example, the [`send_params` option](/ruby/configuration/options#option-send_params) can be set using: `config.send_params = false`.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Some examples on how to configure config options
  Appsignal.configure do |config|
    # Enable AppSignal for the following environments
    config.activate_if_environment(:development, :staging, :production)

    # Configure String config options
    config.name = "My app name"
    # Read a value from an environment variable
    config.hostname = ENV.fetch("HOSTNAME", "default hostname value")

    # Append values to Array config options
    config.ignore_actions += ["My ignored action", "My other ignored action"]
    config.request_headers << "MY_HTTP_HEADER"

    # Configure Boolean config options
    config.send_params = true
    config.enable_host_metrics = false
  end
  ```
</CodeGroup>

Read the rest of this section for more details on how the `Appsignal.configure` helper works and what other helpers it has.

#### String config options

Configuration options of the type String can be set using both Strings and Symbols. When set, we will convert Symbols to Strings.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    config.activejob_report_errors = :discard

    config.activejob_report_errors
    # => "discard"
  end
  ```
</CodeGroup>

#### Array config options

Configuration options of the type Array can be modified as a normal array:

* Use an assignment to override defaults and previously read values from environment variables.
  * For example: `config.array_option = ["value 1", "value 2"]`
  * Option value: `["value 1", "value 2"]`
* Use the *addition assignment operator* `+=` to merge a new array of values with the defaults and previously read values from environment variables.
  * For example: `config.array_option += ["value 1", "value 2"]`
  * Option value: `["DUMMY default value", "value 1", "value 2"]`
* Use the *append operator* `<<` to append a single value to the list of the defaults and previously read values from environment variables.
  * For example: `config.array_option << "value 1"`
  * Option value: `["DUMMY default value", "value 1"]`

#### Automatic environment detection

The AppSignal Ruby gem detects the application's environment automatically. We integrate with gems like Rails, Sinatra, Rack, and others to detect which environment the application has started in. For this reason, it should not be necessary to configure the environment manually.

If you need to configure the application environment manually, pass the environment name as the first argument to the `Appsignal.configure` helper. This argument will override the [`APPSIGNAL_APP_ENV` environment variable value](/ruby/configuration/options#option-appsignal_app_env) and the automatic environment detection.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Configure the application environment explicitly to be "production"
  Appsignal.configure(:production) do |config|
    # Some config
  end
  ```
</CodeGroup>

#### `activate_if_environment` helper

The `Appsignal.configure` helper has a helper to configure which environments should be active and report data to AppSignal.com.

Call the `activate_if_environment` with a list of environments (Strings and/or Symbols).
AppSignal detects the environment when the `Appsignal.configure` helper is called without an environment argument. It will then check if the environment matches any of the given values, and if so, set the [active config option](/ruby/configuration/options#option-active) to `true`.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Enable AppSignal for the following environments
    config.activate_if_environment(:development, :staging, :production)
  end
  ```
</CodeGroup>

The `activate_if_environment` helper is a convenience helper to prevent applications from having to add their own checks on when AppSignal should be active, like:

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Example of a manual check for which environments AppSignal should be active
    config.active = Rails.env.development? || Rails.env.staging? || Rails.env.production?
  end
  ```
</CodeGroup>

#### `env?` helper

The `Appsignal.configure` helper has a helper to check which environment AppSignal has detected. Use this helper to check which environment is active to set the configuration options that should only apply to this environment.

Call the `env?` helper with an environment name (String or Symbol), and it will return `true` if the environment name matches the currently active environment.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Add this configuration only for the staging environment
    if config.env?(:staging)
      config.ignore_actions << "My staging action"
    end
  end
  ```
</CodeGroup>

#### Using the `Appsignal.configure` helper in your application

We recommend configuring the AppSignal Ruby gem using the [Ruby configuration file](#ruby-configuration-file) at `config/appsignal.rb`. If a Rails initializer or inline configuration is preferred, please read this section for the changes in behavior this has.

If the `Appsignal.configure` helper is called before the `config/appsignal.rb` Ruby config file is read when `Appsignal.start` is called, it will not read the Ruby configuration file.

In Rails apps, make sure to [configure the AppSignal gem to start after Rails is initialized](/ruby/integrations/rails#configure-appsignal-in-an-initializer), otherwise the config set with `Appsignal.configure` is ignored when called in a Rails initializer like `config/initializers/appsignal.rb`.

<Warning>
  In Ruby gem version 3.12 and newer, if a [YAML configuration file](#yaml-configuration-file) is present, it will be read when `Appsignal.configure` is called in a Rails initializer or inline in an application. This is deprecated behavior. Please move all configuration to the `Appsignal.configure` helper.

  We will remove this behavior in the next major version of the Ruby gem.
</Warning>

Example Rails initializer:

<CodeGroup>
  ```ruby Ruby theme={null}
  # Example file: config/initializers/appsignal.rb

  # WARNING: In this example the `config/appsignal.rb` config file is not read!
  Appsignal.configure do |config|
    # Set some config
  end
  ```
</CodeGroup>

Example inline configuration:

<CodeGroup>
  ```ruby Ruby theme={null}
  # Example file: app.rb
  require "appsignal"
  require "web_framework"

  # WARNING: In this example the `config/appsignal.rb` config file is not read!
  Appsignal.configure do |config|
    # Set some config
  end
  Appsignal.start

  run WebFramework.app
  ```
</CodeGroup>

### System environment variables

AppSignal can also be configured using system environment variables on the host the application AppSignal is monitoring. This is common on platforms such as Heroku.

Make sure these environment variables are configured in the way that's compatible with your Operating System and that the values get loaded before your app with AppSignal is started.

<CodeGroup>
  ```sh Shell theme={null}
  export APPSIGNAL_APP_NAME="My app"
  ```
</CodeGroup>

### YAML configuration file

<Tip>
  This configuration method is a legacy method and will be removed in the next major version of the Ruby gem.

  Please use the [Ruby configuration file](#ruby-configuration-file) instead.
</Tip>

The AppSignal Ruby gem can be configured with a YAML configuration file. During installation the Ruby gem will create a `config/appsignal.yml` file, if selected. In this file some default configuration is supplied and can be modified to fit your application's needs. This `config/appsignal.yml` file supports ERB tags so that system environment variables can also be loaded in this file.

The `config/appsignal.yml` configuration examples shown for configuration options will use the `default` YAML anchor. The AppSignal installer will create an `config/appsignal.yml` file with this anchor by default. If not present, make sure you add the config option to the correct environment.

<CodeGroup>
  ```yaml YAML theme={null}
  # config/appsignal.yml
  # Define the "defaults" anchor
  default: &defaults
    name: "My app"
    # Supports ERB
    push_api_key: "<%= ENV['APPSIGNAL_PUSH_API_KEY'] %>"

  production:
    # Loads the defaults in the production environment by referencing the anchor
    <<: *defaults
    # production environment specific configuration
    active: true
  ```
</CodeGroup>

#### Multiple app environments

Multiple app environments can be configured in this file using root-level keys.

<CodeGroup>
  ```yaml YAML theme={null}
  # Example: config/appsignal.yml
  development: # Development app environment
    active: true

  production: # Production app environment
    active: true

  test: # Testing app environment
    active: false # Disabled for test environment
  ```
</CodeGroup>

To avoid having to repeat the configuration for every app environment, we can use YAML anchors to extend YAML objects.

<CodeGroup>
  ```yaml YAML theme={null}
  # Example: config/appsignal.yml
  default: &defaults
    active: true

  development: # Development app environment
    <<: *defaults

  production: # Production app environment
    <<: *defaults

  test: # Testing app environment
    <<: *defaults
    active: false # Overwrites the inherited active config option from "defaults"
  ```
</CodeGroup>

It's not possible to only configure a `defaults` anchor and have it apply to all environments automatically. Every environment needs to be configured in the YAML file with a root-level key and extend from this `defaults` anchor.

#### Example YAML configuration file

Here's an example of an `appsignal.yml` configuration file. It's recommended
you only add the configuration you need to your configuration file.

For the full list of options, please see the [configuration
options](/ruby/configuration/options) page.

<CodeGroup>
  ```yaml YAML theme={null}
  # config/appsignal.yml
  default: &defaults
    # Your Push API Key, it is possible to set this dynamically using ERB. Required
    push_api_key: "<%= ENV['APPSIGNAL_PUSH_API_KEY'] %>"

    # Your app's name as reported on AppSignal.com. Required
    name: "My App"

    # Your server's hostname. Optional, auto detected
    hostname: "frontend1.myapp.com"

    # Add default instrumentation of net/http. Default: true
    instrument_net_http: true

    # Skip session data, if it contains private information. Default: false
    skip_session_data: true

    # Ignore these errors (Optional)
    ignore_errors:
      - SystemExit

    # Ignore these actions, used by our Loadbalancer. Optional
    ignore_actions:
      - IsUpController#index

    # Enable allocation tracking for memory metrics. Default: true
    enable_allocation_tracking: true

  # Configuration per environment, leave out an environment or set active
  # to false to not push metrics for that environment.
  development:
    <<: *defaults
    active: true
    # Set the severity level of AppSignal's internal logger. Optional
    # Supported values are error, warning, info, debug, trace
    log_level: debug

  staging:
    <<: *defaults
    # Configure AppSignal to be active for this environment. Required
    active: true

  production:
    <<: *defaults
    # Configure AppSignal to be active for this environment. Required
    active: true

    # Set different path for the log file. Optional, auto detected
    log_path: "/home/my_app/app/shared/log"

    # Set AppSignal working dir. Optional, auto detected
    working_directory_path: "/tmp/appsignal"

    # When it's not possible to connect to the outside world without a proxy.
    # Optional
    http_proxy: "proxy.mydomain.com:8080"
  ```
</CodeGroup>