AppSignal Ruby configuration

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
• Application environment - environment (automatically detected or set with an environment variable)
• Application push API key - push_api_key option
• AppSignal to be active - active option

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, the environment is detected automatically.

# 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

# Environment variables
export APPSIGNAL_APP_NAME="My app"
export APPSIGNAL_APP_ENV="production"
export APPSIGNAL_PUSH_API_KEY="1234-1234-1234"

# config/appsignal.yml
# Legacy config method
production:
  active: true
  name: "My app"
  push_api_key: "1234-1234-1234"

Configuration methods

Ruby configuration file

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. Please read the integrating AppSignal instructions if Appsignal.start is not automatically called.

The configuration file configures our Ruby gem using the Appsignal.configure helper. Please read the the Appsignal.configure helper section for more details on how to use it.

The YAML configuration file will not be read when this file is present.

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

Appsignal.configure helper

The Appsignal.configure helper can be used to configure AppSignal using Ruby code. The 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, please read this section on the differences in behavior this has.

Set configuration options inside the Appsignal.configure block by calling the writer methods on the config object. Configuration options can be set using the "Config file key" listed for the configuration options. For example, the send_params option can be set using: config.send_params = false.

# 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

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.

Appsignal.configure do |config|
  config.activejob_report_errors = :discard
 
  config.activejob_report_errors
  # => "discard"
end

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 and the automatic environment detection.

# Configure the application environment explicitly to be "production"
Appsignal.configure(:production) do |config|
  # Some config
end

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 to true.

Appsignal.configure do |config|
  # Enable AppSignal for the following environments
  config.activate_if_environment(:development, :staging, :production)
end

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:

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

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.

Appsignal.configure do |config|
  # Add this configuration only for the staging environment
  if config.env?(:staging)
    config.ignore_actions << "My staging action"
  end
end

Using the Appsignal.configure helper in your application

We recommend configuring the AppSignal Ruby gem using the 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, otherwise the config set with Appsignal.configure is ignored when called in a Rails initializer like config/initializers/appsignal.rb.

Example Rails initializer:

# 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

Example inline configuration:

# 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

System environment variable

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.

export APPSIGNAL_APP_NAME="My app"

YAML configuration file

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.

# 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

Multiple app environments

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

# 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

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

# 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"

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

# 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
  # Enable more logging in the `appsignal.log` file. Optional
  log_level: true
 
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"