SolarWinds APM Ruby Configuration Guide

This guide covers all configuration options for the SolarWinds APM Ruby gem, an OpenTelemetry-based distribution that provides automatic instrumentation and observability features for Ruby applications.

Quick Start

To get started quickly, you only need to set your service key:

export SW_APM_SERVICE_KEY=<your-api-token>:<your-service-name>

By default, all applicable instrumentations are enabled and the gem works out-of-the-box with sensible defaults.

Minimal Example

# Set the service key (required)
ENV['SW_APM_SERVICE_KEY'] = 'your-api-token:my-ruby-app'

# Require the gem (typically done automatically by Bundler)
require 'solarwinds_apm'

# Your application code here

Configuration Precedence

Configuration can be set in multiple ways with the following precedence order (highest to lowest):

Environment Variables - Highest priority
Programmatic Configuration - Set in Ruby code
Configuration Files - Rails initializer or config file
Default Values - Built-in defaults

Environment Variables

Environment variables are the most flexible way to configure the SolarWinds APM gem, especially in containerized or cloud environments. All SolarWinds APM-specific settings are prefixed with SW_APM_. Standard OpenTelemetry environment variables are also supported where applicable.

Required Configuration

Variable	Description	Example
`SW_APM_SERVICE_KEY`	API token and service name (required)	`your-token:my-service`

Common Configuration

Variable	Description	Default	Example
`SW_APM_ENABLED`	Enable/disable the entire library	`true`	`false`
`SW_APM_DEBUG_LEVEL`	Logging verbosity (-1 to 6)	`3`	`5`
`SW_APM_COLLECTOR`	Collector endpoint override	`apm.collector.na-01.cloud.solarwinds.com:443`	`apm.collector.eu-01.cloud.solarwinds.com:443`

For more configuration options see Configuration Reference.

OpenTelemetry Integration

Exporters

This gem uses the OTLP exporter by default. You can configure additional exporters for debugging or multi-backend scenarios:

export OTEL_TRACES_EXPORTER=console          # Console Exporter (for debugging)
export OTEL_TRACES_EXPORTER=otlp,console     # Multiple Exporters
export OTEL_TRACES_EXPORTER=jaeger           # Third-party Exporters (e.g. jaeger, add gem opentelemetry-exporter-jaeger before solarwinds_apm)

Service Name

By default the service name portion of the service key is used, e.g. 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 will take precedence over the default. The precedence is as follows:

OTEL_SERVICE_NAME > OTEL_RESOURCE_ATTRIBUTES > SW_APM_SERVICE_KEY > SolarWindsAPM::Config[:service_key]

Service key format:

export SW_APM_SERVICE_KEY=<api-token>:<service-name>

Override with OpenTelemetry variables:

# Service name will be 'production-api', not 'my-service'
export SW_APM_SERVICE_KEY=<api-token>:my-service
export OTEL_SERVICE_NAME=production-api

Resource attributes:

export OTEL_RESOURCE_ATTRIBUTES=service.name=production-api,service.version=1.2.3

Instrumentation Control

Fine-tune individual instrumentation libraries using OpenTelemetry environment variables:

Disable specific instrumentation:

export OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED=false
export OTEL_RUBY_INSTRUMENTATION_REDIS_ENABLED=false

Configure instrumentation options:

# Include full SQL statements (disable obfuscation)
export OTEL_RUBY_INSTRUMENTATION_MYSQL2_CONFIG_OPTS='db_statement=include;'

# Configure HTTP instrumentation
export OTEL_RUBY_INSTRUMENTATION_NET_HTTP_CONFIG_OPTS='untraced_hosts=localhost,internal.service;'

Set inside file through ENV hash:

# Set before requiring solarwinds_apm
ENV['OTEL_RUBY_INSTRUMENTATION_MYSQL2_CONFIG_OPTS'] = 'db_statement=include;'
ENV['OTEL_RUBY_INSTRUMENTATION_NET_HTTP_CONFIG_OPTS'] = 'untraced_hosts=localhost,internal.service;'

See the OpenTelemetry Ruby instrumentation documentation for all available options.

Exporting Application Logs

The Logger instrumentation is a log appender for the Ruby logger that bridges messages into OTel log record format for export. By default this instrumentation is disabled; it can be enabled by setting the environment variable OTEL_RUBY_INSTRUMENTATION_LOGGER_ENABLED=true.

Programmatic Configuration

For advanced use cases, you can configure OpenTelemetry instrumentation libraries programmatically using the SolarWindsAPM::OTelConfig.initialize_with_config block.

Prerequisites

⚠️ Important: Programmatic configuration requires disabling auto-configuration:

export SW_APM_AUTO_CONFIGURE=false

Basic Example

Below 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

Advanced Configuration

SolarWindsAPM::OTelConfig.initialize_with_config do |config|
  # HTTP client configuration
  config["OpenTelemetry::Instrumentation::Net::HTTP"] = {
    untraced_hosts: ['localhost', 'internal.service.com'],
    untraced_requests: ->(uri, req) { uri.path == '/health' }
  }

  # Rails configuration
  config["OpenTelemetry::Instrumentation::Rails"] = {
    enable_recognize_route: true,
    enable_dependency_tracking: true
  }

  # Redis configuration
  config["OpenTelemetry::Instrumentation::Redis"] = {
    peer_service: 'redis-cluster',
    db_statement_serializer: ->(stmt) { stmt.truncate(100) }
  }
end

Reference: Consult individual instrumentation README files for complete configuration options.

Configuration Files

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 Configuration Reference section.

How to install the file

Rails Applications

For Rails applications, use the built-in generator to create a configuration file:

bundle exec rails generate solarwinds_apm:install

This creates config/initializers/solarwinds_apm.rb with documented configuration options.

Non-Rails Applications

Create a file named solarwinds_apm_config.rb in your application's root directory:

# solarwinds_apm_config.rb
SolarWindsAPM::Config[:service_key] = 'your-token:your-service'
SolarWindsAPM::Config[:debug_level] = 3
SolarWindsAPM::Config[:tag_sql] = true

Custom Location

Override the default configuration file location:

export SW_APM_CONFIG_RUBY=/path/to/your/config.rb

Configuration Topics

Transaction Filtering

Specific transactions can be disabled from tracing (suppressing both spans and metrics) using the :transaction_settings configuration. An example that filters out static assets, health check requests, and a background job consumer:

SolarWindsAPM::Config[:transaction_settings] = [
  {
    regexp: '\.(css|js|png|jpg|gif|ico|woff2?)$',
    opts: Regexp::IGNORECASE,
    tracing: :disabled
  },
  {
    regexp: '/health|/status|/ping',
    tracing: :disabled
  },
  {
    regexp: 'CONSUMER:.*process',  # Background job patterns
    tracing: :disabled
  }
]

SQL Query Tagging

Append trace context to database queries as SQL comments for correlation between traces and database logs.

export SW_APM_TAG_SQL=true        # Enable SQL tagging

Output:

-- Before (without tagging)
SELECT * FROM users WHERE id = 1;

-- After (with tagging)
SELECT * FROM users WHERE id = 1; /* traceparent=7435a9fe510ae4533414d425dadf4e18-49e60702469db05f-01 */

Supported Operations:

MySQL2: query operations
PostgreSQL: the "exec-ish" operations like exec and query are supported.

⚠️ Limitation: Currently does not support prepared statements.

Log Trace Context Integration

Include trace context in your application logs for better correlation:

SolarWindsAPM::Config[:log_traceId] = :traced

This adds trace and span IDs to log entries when using supported logging frameworks. See also Exporting Application Logs on how to send logs to SolarWinds Observability.

Background Job Configuration: Resque

When starting the Resque worker, it is necessary to set RUN_AT_EXIT_HOOKS=1. For example:

RUN_AT_EXIT_HOOKS=1 QUEUE=myqueue bundle exec rake resque:work

The RUN_AT_EXIT_HOOKS=1 ensures background processes complete before worker shutdown. This allows the background processes that handle signal (trace, metrics, etc.) transmission to complete their tasks.

Proxy Configuration

Starting with version 7.0.0, the environment variable SW_APM_PROXY and configuration file option :http_proxy are deprecated since telemetry is exported with standard OTLP exporters. These exporters use Ruby 's Net::HTTP, which supports configuring an HTTP proxy. The examples below set the http_proxy environment variable for the Ruby process to configure the proxy:

# proxy server with no authentication
http_proxy=http://<proxyHost>:<proxyPort> ruby my.app

# proxy server that requires basic authentication
http_proxy=http://<username>:<password>@<proxyHost>:<proxyPort> ruby my.app

Note: Starting with version 7.0.0, SW_APM_PROXY is deprecated in favor of standard HTTP proxy environment variables.

Lambda Configuration

For AWS Lambda deployments:

# Disable dependency preloading if needed
export SW_APM_LAMBDA_PRELOAD_DEPS=false

# Set custom transaction names
export SW_APM_TRANSACTION_NAME=my-lambda-function

Configuration Reference

Environment Variable	Config File Key	Description	Default
`SW_APM_AUTO_CONFIGURE`	N/A	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.	`true`
`SW_APM_COLLECTOR`	N/A	Override the default collector endpoint to which the library connects and exports data. It should be defined using the format host:port.	`apm.collector.na-01.cloud.solarwinds.com:443`
`SW_APM_CONFIG_RUBY`	N/A	Override the default location for the configuration file. This can be an absolute or relative filename, or the directory under which the `solarwinds_apm_config.rb` file would be looked for.	None
`SW_APM_DEBUG_LEVEL`	`:debug_level`	Set the library's logging level, valid values are -1 through 6 (least to most verbose). Setting -1 disables logging from the library.	3
`SW_APM_ENABLED`	N/A	Enable/disable the library, setting `false` is an alternative to uninstalling `solarwinds_apm` since it will prevent the library from loading.	`true`
`SW_APM_SERVICE_KEY`	`:service_key`	API token and service name in the form of `token:service_name`, required.	None
`SW_APM_TAG_SQL`	`:tag_sql`	Enable/disable injecting trace context into supported SQL statements. Set to boolean true or (or string `true` in env var) to enable, see Tag Query with Trace Context for details.	`false`
`SW_APM_TRIGGER_TRACING_MODE`	`:trigger_tracing_mode`	Enable/disable trigger tracing for the service. Setting to `disabled` may impact DEM visibility into the service.	`enabled`
`SW_APM_LAMBDA_PRELOAD_DEPS`	N/A	This option only takes effect in the AWS Lambda runtime. Set to `false` to disable the attempt to preload function dependencies and install instrumentations.	`true`
`SW_APM_TRANSACTION_NAME`	N/A	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	None
N/A	`:log_traceId`	Configure the insertion of trace context into application logs, setting `:traced` would include the available context fields such as trace_id, span_id into log messages.	`:never`
N/A	`:tracing_mode`	Enable/disable the tracing mode for this service, setting `:disabled` would suppress all trace spans and metrics.	`:enabled`
N/A	`:transaction_settings`	Configure tracing mode per transaction, aka transaction filtering. See Transaction Filtering for details.	None

Debug Levels

Level	Description
`-1`	Logging disabled
`0`	Fatal errors only
`1`	Errors
`2`	Warnings
`3`	Info (default)
`4`	Debug
`5`	Verbose
`6`	Maximum verbosity

Troubleshooting

Log Analysis

Enable debug logging and look for:

Service key validation
Collector connection status
Instrumentation loading
Span creation and export

# Enable detailed logging
export SW_APM_DEBUG_LEVEL=5
# Or use otel debug level
export OTEL_LOG_LEVEL=debug

For additional help, see the SolarWinds documentation or contact support.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SolarWinds APM Ruby Configuration Guide

Quick Start

Minimal Example

Configuration Precedence

Environment Variables

OpenTelemetry Integration

Exporters

Service Name

Instrumentation Control

Exporting Application Logs

Programmatic Configuration

Prerequisites

Basic Example

Configuration Files

How to install the file

Rails Applications

Non-Rails Applications

Custom Location

Configuration Topics

Transaction Filtering

SQL Query Tagging

Log Trace Context Integration

Background Job Configuration: Resque

Proxy Configuration

Lambda Configuration

Configuration Reference

Debug Levels

Troubleshooting

Log Analysis

FilesExpand file tree

CONFIGURATION.md

Latest commit

History

CONFIGURATION.md

File metadata and controls

SolarWinds APM Ruby Configuration Guide

Quick Start

Minimal Example

Configuration Precedence

Environment Variables

OpenTelemetry Integration

Exporters

Service Name

Instrumentation Control

Exporting Application Logs

Programmatic Configuration

Prerequisites

Basic Example

Configuration Files

How to install the file

Rails Applications

Non-Rails Applications

Custom Location

Configuration Topics

Transaction Filtering

SQL Query Tagging

Log Trace Context Integration

Background Job Configuration: Resque

Proxy Configuration

Lambda Configuration

Configuration Reference

Debug Levels

Troubleshooting

Log Analysis