Configure the Ruby Library

This topic applies to version 6 of the Ruby Library. If you are using an earlier version, see Configure the Ruby Library (legacy).

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:

Environmental variable
Programmatic configuration
Configuration file
Default value

Environment variables

Settings specific to solarwinds_apm are prefixed by SW_APM_. They are described below, under Complete list of configuration options. Standard OpenTelemetry environment variables that impact this library's functionality are described in the following sections.

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.pre'

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

Instrumentation libraries

You can use OpenTelemetry Ruby instrumentation environment variables to disable or configure certain instrumentation. See the OpenTelemetry documentation for details.

For example, to disable sinatra instrumentation and disable mysql2 instrumentation's obfuscation of db.statement:

export OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED=false
export OTEL_RUBY_INSTRUMENTATION_MYSQL2_CONFIG_OPTS='db_statement=include;'

Or in your initialization step:


ENV['OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED'] = 'false'
ENV['OTEL_RUBY_INSTRUMENTATION_MYSQL2_CONFIG_OPTS'] = 'db_statement=include;'

Programmatic configuration

Many instrumentation library configurations can be set within the SolarWindsAPM::OTelConfig.initialize_with_config block. Consult the individual instrumentation README pages for the available options. Note that this takes lower precedence than the environment variable settings.

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

Configuration file

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

config/initializers/solarwinds_apm.rb for Rails applications, which you can create by running the provided generator:

bundle exec rails generate solarwinds_apm:install
solarwinds_apm_config.rb for non-Rails applications

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

export SW_APM_CONFIG_RUBY=config/file/location.rb

The configuration file should be Ruby code that sets key/values in the hash exposed by SolarWindsAPM::Config. The bundled Rails generator template file serves as an example of the supported values. See also the Complete list of configuration options.

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
  }
]

Complete list of configuration options

The following environment variables and configuration file keys supported by the Ruby Library are specific to solarwinds_apm. The bundled Rails generator template file serves as an example of the supported values.

Auto-configure

By default, the library is configured to work out-of-the-box with all automatic instrumentation libraries enabled. Set this to false to custom initialize the library with configuration options for instrumentation. See Programmatic configuration for details.

System environment variable

SW_APM_AUTO_CONFIGURE

Config file key

N/A

Required

Default

true

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Collector

The collector is the ingestion endpoint the library connects to and exports data to. You can use this option to override the default collector. It should be defined using the format host:port. To determine the endpoint for your organization, see Data centers and endpoint URIs. Port is optional and defaults to 443.

System environment variable

SW_APM_COLLECTOR

Config file key

N/A

Required

Default

apm.collector.na-01.cloud.solarwinds.com:443

History

Introduced with version 5.1.3 of the Ruby Instrumentation Library.

Example

export SW_APM_COLLECTOR=YourHost:PortNumber

Config Ruby

This option can override the default location for the configuration file. This can be an absolute or relative file name, or the directory under which the solarwinds_apm_config.rb file would be looked for. See Ruby Library configuration file.

System environment variable

SW_APM_CONFIG_RUBY

Config file key

N/A

Required

Default

Ruby or Rails default location (see Configuration file)

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_CONFIG_RUBY=/deploy/app/config/solarwinds_apm_config.rb

Debug level

This changes the log level of the c-library and the solarwinds_apm gem. It takes the following values, which go from least to most verbose.

Value	Log level
`-1`	Disables logging from the library
`0`	Fatal
`1`	Error
`2`	Warning
`3`	Info (the default)
`4`	Debug low
`5`	Debug medium
`6`	Debug high

Increase the logging verbosity to one of the debug levels to get more detailed information sent to STDOUT. To change the log level of only the gem, change the level of SolarWindsAPM.logger. For example:

SolarWindsAPM.logger.level = Logger::INFO

System environment variable

SW_APM_DEBUG_LEVEL

Required

Config file key

:debug_level

Default

3

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_DEBUG_LEVEL=1

EC2 metadata timeout

This specifies the timeout value for AWS IMDS metadata retrieval in milliseconds.

System environment variable

SW_APM_EC2_METADATA_TIMEOUT

Config file key

:ec2_metadata_timeout

Required

Default

1000

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Enabled

This enables or disables the library. Setting it to false prevents the library from loading, which is an alternative to uninstalling solarwinds_apm.

System environment variable

SW_APM_ENABLED

Config file key

N/A

Required

Default

true

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Log file path

This configures the log file path for the C extension. If it is set, messages from the C extension are written to the specified file instead of STDERR.

System environment variable

SW_APM_LOG_FILEPATH

Config file key

N/A

Required

Default

No default

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Example

export SW_APM_LOG_FILEPATH=/path/file_path.log

Proxy

Configure this if a proxy needs to be used to communicate with the SolarWinds APM collector. The format should either be http://<proxyHost>:<proxyPort> for a proxy server that does not require authentication, or http://<username>:<password>@<proxyHost>:<proxyPort> for a proxy server that requires basic authentication.

While HTTP is the only type of connection supported, the traffic to SolarWinds APM collector is still encrypted using SSL/TLS.

System environment variable

SW_APM_PROXY

Config file key

:http_proxy

Required

Default

No default

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_PROXY=http://proxy.example.com:8080

Service key

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

It is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

See Service name.

System environment variable

SW_APM_SERVICE_KEY

Config file key

:service_key

Required

Yes

Default

No default

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_SERVICE_KEY=ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:my_service

Tag SQL

This feature should only be enabled when using APM library version 6.1.2 or above.

This enables or disables injecting trace context into supported SQL statements. Set it to true to enable this function. See Ruby trace context in queries for details and the support matrix.

System environment variable

SW_APM_TAG_SQL

Config file key

tag_sql

Required

Default

false

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Trigger tracing mode

This enables or disables trigger tracing for the service. Setting it to disabled turns off support for trigger trace, which might affect DEM visibility into the service.

System environment variable

SW_APM_TRIGGER_TRACING_MODE

Config file key

:trigger_tracing_mode

Required

Default

enabled

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Trusted path

The library uses the host system's default trusted CA certificates to verify the TLS connection to the collector. To override the default, define the trusted certificate path configuration option with an absolute path to a specific trusted certificate file in PEM format.

System environment variable

SW_APM_TRUSTEDPATH

Config file key

N/A

Required

Default

No default

History

Introduced with version 5.1.3 of the Ruby Instrumentation Library.

Example

export SW_APM_TRUSTEDPATH=/the/location/of/your/certificate

Lambda preload dependencies

This option only takes effect in the AWS Lambda runtime. Set to false to disable the attempt to preload function dependencies and install instrumentations.

System environment variable

SW_APM_LAMBDA_PRELOAD_DEPS

Config file key

N/A

Required

Default

true

History

Introduced with version 6.1.0 of the Ruby Instrumentation Library.

Example

export SW_APM_LAMBDA_PRELOAD_DEPS=false

Transaction name

Customize the transaction name for all traces, typically used to target specific instrumented Lambda functions. Precedence order: custom SDK > SW_APM_TRANSACTION_NAME > automatic naming

System environment variable

SW_APM_TRANSACTION_NAME

Config file key

N/A

Required

Default

No default

History

Introduced with version 6.1.0 of the Ruby Instrumentation Library.

Example

export SW_APM_TRANSACTION_NAME=lambda-transaction-name

Log arguments

This enables or disables the collection of URL query parameters. Set it to false to disable collection.

System environment variable

N/A

Config file key

:log_args

Required

Default

true

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Log trace ID

Use this to configure the insertion of trace context into application logs. Setting the value to :traced includes the available context fields such as trace_id and span_id into log messages. For all values, see the trace context Configuration section.

System environment variable

N/A

Config file key

:log_traceId

Required

Default

:never

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Tracing mode

This enables or disables the tracing mode for this service. Setting this value to :disabled suppresses all trace spans and metrics.

System environment variable

N/A

Config file key

:tracing_mode

Required

Default

:enabled

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

Transaction settings

This configures the tracing mode per transaction, sometimes called transaction filtering.

System environment variable

N/A

Config file key

:transaction_settings

Required

Default

No default

History

Introduced with version 6.0 of the Ruby Instrumentation Library.

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.

Search SolarWinds Support

Configure the Ruby Library

Required configuration

Precedence

Environment variables

Exporter

Service name

Instrumentation libraries

Programmatic configuration

Configuration file

Transaction filtering

Complete list of configuration options

Auto-configure

Collector

Config Ruby

Debug level

EC2 metadata timeout

Enabled

Log file path

Proxy

Service key

Tag SQL

Trigger tracing mode

Trusted path

Lambda preload dependencies

Transaction name

Log arguments

Log trace ID

Tracing mode

Transaction settings