Configure the Ruby Library

Required configuration

By default, all applicable instrumentations are enabled. The only required configuration is the service key. All other configuration options available for environment variables or in the config file are optional. The following is an example of the minimum requirement to get started.

export SW_APM_SERVICE_KEY=<set-service-key-here>
ruby application.rb

Precedence

Configuration can be set in several ways. If the same option is configured in multiple places, the following precedence determines which value is used:

1. In-code configuration

2. Environmental variable

3. Configuration file

4. Default value

In-code configuration

Many OpenTelemetry instrumenter configurations can be set within the SolarWindsAPM::OTelConfig.initialize_with_config block, which overrides the same options set through environment variables or a configuration file. Consult the individual instrumenter README pages for the available options.

This feature is enabled only if auto-config is disabled through SW_APM_AUTO_CONFIGURE=false.

The following is an example that disables Dalli instrumentation and sets the Rack instrumentation to capture certain headers as Span attributes:

# note auto-configure must be disabled, e.g.
# export SW_APM_AUTO_CONFIGURE=false

require 'solarwinds_apm'

SolarWindsAPM::OTelConfig.initialize_with_config do |config|
  config["OpenTelemetry::Instrumentation::Dalli"] = {:enabled => false}
  config["OpenTelemetry::Instrumentation::Rack"]  = {:allowed_request_headers => ['header1', 'header2']}
end

Environment variables

Settings specific to solarwinds_apm are prefixed by SW_APM_. They are described in Ruby Library configuration reference. Standard OpenTelemetry environment variables that impact this library's functionality are described in the following sections.

Applications running on Linux servers will read the system variables from the current env settings.

For applications started through nginx, the environment variables need to be configured in the nginx config file, usually found at /etc/ngingx/nginx.conf. For example, to set the Service key, add a directive like: 

env
SW_APM_SERVICE_KEY=ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:my_service

Exporter

The default solarwinds exporter, which communicates with the SolarWinds Observability backend, is always configured. Additional exporters can be configured with the OTEL_TRACES_EXPORTER environment variable. For example, the console exporter is part of the standard installation and can be enabled as shown below:

export OTEL_TRACES_EXPORTER=console

Other exporters must first be installed and required before loading solarwinds_apm. For example, if dependencies are loaded by Bundler.require, first add the OTLP exporter to the Gemfile:

# application dependencies, eg
# gem "rails", "~> 7.0.5", ">= 7.0.5.1"

gem "opentelemetry-exporter-otlp"

# end of Gemfile
gem 'solarwinds_apm', '>=6.0.0'

Then set the environment variable:

export OTEL_TRACES_EXPORTER=otlp

Service name

By default, the service name portion of the service key is used. For example, the service name is my-service if the service key is SW_APM_SERVICE_KEY=api-token:my-service. If the OTEL_SERVICE_NAME or OTEL_RESOURCE_ATTRIBUTES environment variable is used to specify a service name, it takes precedence over the default.

export SW_APM_SERVICE_KEY=<api-token>:foo
export OTEL_SERVICE_NAME=bar

# service name for instrumented app will be "bar"
ruby application.rb

Config file

Location

On startup, the library looks for the configuration file in the following locations under the application's current working directory:

• Default location for Rails applications: config/initializers/solarwinds_apm_config.rb

• Default location for non-Rails applications: solarwinds_apm_config.rb

You can override the default location with the environment variable SW_APM_CONFIG_RUBY:

export SW_APM_CONFIG_RUBY=config/file/location.rb

Create a config file for a Rails application

Run the following command to create a template config file config/initializers/solarwinds_apm_tmp.rb with all the default configurations:

bundle exec rails generate solarwinds_apm:install

Create a config file for a non-Rails application

Run the following command to create a template config file solarwinds_apm_config_tmp.rb with all the default configurations copied into the current directory.

bundle exec solarwinds_apm_config

Copy the template config file to the application's startup directory or the path defined in SW_APM_CONFIG_RUBY.

About configuration file values

The solarwinds_apm gem uses a nested hash to store configuration values in SolarWindsAPM::Config. Each key/value pair represents a config option. Most accept only true or false, making config changes a simple operation.

To check your settings, call SolarWindsAPM::Config.print_config

For an example of the supported settings, see All configuration options in the reference topic. For more information about keys specific to solarwinds_apm, see Environment variables and configuration file keys in that topic.

Transaction filtering

Specific transactions can be disabled from tracing (suppressing both spans and metrics) using the :transaction_settings configuration. The following example filters out static assets and a message consumer:

SolarWindsAPM::Config[:transaction_settings] = [
  {
    regexp: '\.(css|js|png)$',
    opts: Regexp::IGNORECASE,
    tracing: :disabled
  },
  {
    regexp: 'CONSUMER:mytopic process',
    tracing: :disabled
  }
]

Update the config file

Configurations can be removed from the config file because default values for configurations are defined in the gem.

To define a configuration option that does not exist in the current solarwinds_apm_config.rb file, it must be added manually. See All Configuration Options for all currently available configurations.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.