Documentation forSolarWinds Observability SaaS

Configure the Ruby Library (legacy)

This topic applies to versions earlier than version 6 of the Ruby Library. If you are using version 6, see Configure the Ruby Library.

SW_APM_SERVICE_KEY is the only required configuration. All other configuration options available for environment variables or in the config file are optional.

Environment variables

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

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

System environment variable

SW_APM_SERVICE_KEY

Default

no default

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_SERVICE_KEY=ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:my_service

SW_APM_TRUSTEDPATH

The library uses the trusted CA certificates configured for the Ruby core library 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

Required

No

History

Introduced with version 5.1.3 of the Ruby Instrumentation Library.

Example

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

SW_APM_COLLECTOR

The collector is the ingestion endpoint the library connects to and exports data to. 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

Required

No

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

SW_APM_HOSTNAME_ALIAS

If configured, the hostname alias will be displayed and available to be used as a filter in the Traces Explorer.

System environment variable

SW_APM_HOSTNAME_ALIAS

Default

no default

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_HOSTNAME_ALIAS=apm-host-east

SW_APM_DEBUG_LEVEL

This changes the log level of the c-library and the solarwinds_apm gem. It takes the following values: 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 only change the log level of them gem, change the level of SolarWindsAPM.logger. For example:

SolarWindsAPM.logger.level = Logger::INFO

System environment variable:

SW_APM_DEBUG_LEVEL

Default

3

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_DEBUG_LEVEL=1

SW_APM_GEM_VERBOSE

Setting this to true will show information about which gems are being instrumented during initialization. This is distinct from the log level (see below).

System environment variable

SW_APM_GEM_VERBOSE

Default

false

History

Introduced with version 5.0.0 of the Ruby Instrumentation Library.

Example

export SW_APM_GEM_VERBOSE=true

SW_APM_CONFIG_RUBY

This variable can be set to point to a config file. See Config file.

System environment variable

SW_APM_CONFIG_RUBY

Default

Ruby or Rails default location (see Config 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

SW_APM_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

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

Config file

Location

The config file can either be in a default location or defined by SW_APM_CONFIG_RUBY. It will be loaded automatically according to the following order of precedence:

  1. Rails default path: config/initializers/solarwinds_apm_config.rb
  2. Environment variable: SW_APM_CONFIG_RUBY
  3. Ruby default path: <app startup directory>/solarwinds_apm_config.rb

It is recommended to set SolarWindsAPM configurations via a config file, but it is also possible to set them in code. Keep in mind that certain configurations cannot be changed in code. For example, once you require solarwinds_apm in your app, setting :enabled instrumentations to false in the code will not disable them; likewise, disabled instrumentations cannot be enabled after the gem is loaded. Settings for :service_key, :hostname_alias, and :debug_level are only read at startup.

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

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.

SolarWindsAPM configurations

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

All configuration options

# frozen_string_literal: true

# Copyright (c) 2019 SolarWinds, LLC.
# All rights reserved.

# SolarWindsAPM Configuration for the Ruby Library aka solarwinds_apm gem
# https://cloud.solarwinds.com/
#
# More information on configuring the Ruby Library can be found here:
# https://documentation.solarwinds.com/en/success_center/observability/default.htm#cshid=config-ruby-agent
#
# The initial settings in this file represent the defaults

if defined?(SolarWindsAPM::Config)

  # :service_key, :hostname_alias, :http_proxy, and :debug_level
  # are startup settings and can't be changed afterwards.

  #
  # Set SW_APM_SERVICE_KEY
  # This setting will be overridden if SW_APM_SERVICE_KEY is set as an environment variable.
  # This is a required setting. If the service key is not set here it needs to be set as environment variable.
  #
  # The service key is a combination of the API token plus a service name.
  # E.g.: 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my_service
  #
  # SolarWindsAPM::Config[:service_key] = '0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my_service'

  #
  # Set SW_APM_HOSTNAME_ALIAS
  # This setting will be overridden if SW_APM_HOSTNAME_ALIAS is set as an environment variable
  #
  # SolarWindsAPM::Config[:hostname_alias] = 'alias_name'

  #
  # Set Proxy for SolarWinds   # This setting will be overridden if SW_APM_PROXY is set as an environment variable.
  #
  # Please configure http_proxy 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.
  #
  # Note that while HTTP is the only type of connection supported, the traffic
  # to SolarWinds is still encrypted using SSL/TLS.
  #
  # It is recommended to configure the proxy in this file or as SW_APM_PROXY
  # environment variable. However, the underlying network library for the Ruby
  # Instrumentation Library will use a system-wide proxy defined in the environment
  # variables grpc_proxy, https_proxy or http_proxy if no SolarWindsAPM-specific
  # configuration is set.
  #
  # Please refer to gRPC environment variables for more information.
  #
  # SolarWindsAPM::Config[:http_proxy] = http://<proxyHost>:<proxyPort>

  #
  # Set SW_APM_DEBUG_LEVEL
  # This setting will be overridden if SW_APM_DEBUG_LEVEL is set as an environment variable.
  #
  # It sets the log level and takes the following values:
  # -1 disabled, 0 fatal, 1 error, 2 warning, 3 info (the default), 4 debug low, 5 debug medium, 6 debug high.
  # Values out of range (< -1 or > 6) are ignored and the log level is set to the default (info).
  #
  SolarWindsAPM::Config[:debug_level] = 3

  #
  # :debug_level will be used in the c-extension of the gem and also mapped to the
  # Ruby logger as DISABLED, FATAL, ERROR, WARN, INFO, or DEBUG
  # The Ruby logger can afterwards be changed to a different level, e.g:
  # SolarWindsAPM.logger.level = Logger::INFO

  #
  # Set SW_APM_GEM_VERBOSE
  # This setting will be overridden if SW_APM_GEM_VERBOSE is set as an environment variable
  #
  # On startup the components that are being instrumented will be reported if this is set to true.
  # If true and the log level is 4 or higher this may create extra debug log messages
  #
  SolarWindsAPM::Config[:verbose] = false

  #
  # Turn Tracing on or off
  #
  # By default tracing is set to :enabled, the other option is :disabled.
  # :enabled means that sampling will be done according to the current
  # sampling rate and metrics are reported.
  # :disabled means that there is no sampling and metrics are not reported.
  #
  # The values :always and :never are deprecated
  #
  SolarWindsAPM::Config[:tracing_mode] = :enabled

  #
  # Turn Trigger Tracing on or off
  #
  # By default trigger tracing is :enabled, the other option is :disabled.
  # It allows to use the X-Trace-Options header to force a request to be
  # traced (within rate limits set for trigger tracing)
  #
  SolarWindsAPM::Config[:trigger_tracing_mode] = :enabled

  #
  # Trace Context in Logs
  #
  # Configure if and when the Trace ID should be included in application logs.
  # Common Ruby and Rails loggers are auto-instrumented, so that they can include
  # the current Trace ID in log messages.
  #
  # The added string will look like:
  # "trace_id=7435a9fe510ae4533414d425dadf4e18 span_id=49e60702469db05f trace_flags=00"
  #
  # The following options are available:
  # :never    (default)
  # :sampled  only include the Trace ID of sampled requests
  # :traced   include the Trace ID for all traced requests
  # :always   always add a Trace ID, it will be
  #           "trace_id=00000000000000000000000000000000 span_id=0000000000000000 trace_flags=00"
  #           when there is no tracing context.
  #
  SolarWindsAPM::Config[:log_traceId] = :never

  #
  # Trace Context in Queries (sql only)
  #
  # Configure to add the trace context to sql queries so that queries and
  # transactions can be linked in the SolarWinds dashboard
  #
  # This option can add a small overhead for queries that use prepared
  # statements as those statements will be recompiled whenever the trace context
  # is added (about 10% of the requests)
  #
  # the options are:
  # - true   (default) no trace context is added
  # - false  the tracecontext is added as comment to the start of the query, e.g:
  #          "/*traceparent='00-268748089f148899e29fc5711aca7760-7c6c704dcbba6682-01'*/SELECT `widgets`.* FROM `widgets` WHERE ..."
  #
  SolarWindsAPM::Config[:tag_sql] = false

  #
  # Sanitize SQL Statements
  #
  # The SolarWindsAPM Ruby client has the ability to sanitize query literals
  # from SQL statements.  By default this is enabled.  Disable to
  # collect and report query literals to SolarWindsAPM.
  #
  SolarWindsAPM::Config[:sanitize_sql] = true
  SolarWindsAPM::Config[:sanitize_sql_regexp] = '(\'[^\']*\'|\d*\.\d+|\d+|NULL)'
  SolarWindsAPM::Config[:sanitize_sql_opts]   = Regexp::IGNORECASE

  #
  # Prepend Domain to Transaction Name
  #
  # If this is set to `true` transaction names will be composed as
  # `my.host.com/controller.action` instead of `controller.action`.
  # This configuration applies to all transaction names, whether deduced by the
  # instrumentation or implicitly set.
  #
  SolarWindsAPM::Config[:transaction_name][:prepend_domain] = false

  #
  # Do Not Trace - DNT
  #
  # DEPRECATED
  # Please comment out if no filtering is desired, e.g. your static
  # assets are served by the web server and not the application
  #
  # This configuration allows creating a regexp for paths that should be excluded
  # from solarwinds_apm processing.
  #
  # For example:
  # - static assets that aren't served by the web server, or
  # - healthcheck endpoints that respond to a heart beat.
  #
  # :dnt_regexp is the regular expression that is applied to the incoming path
  # to determine whether the request should be measured and traced or not.
  #
  # :dnt_opts can be commented out, nil, or Regexp::IGNORECASE
  #
  # The matching happens before routes are applied.
  # The path originates from the rack layer and is retrieved as follows:
  #   req = ::Rack::Request.new(env)
  #   path = URI.unescape(req.path)
  #
  SolarWindsAPM::Config[:dnt_regexp] = '\.(jpg|jpeg|gif|png|ico|css|zip|tgz|gz|rar|bz2|pdf|txt|tar|wav|bmp|rtf|js|flv|swf|otf|eot|ttf|woff|woff2|svg|less)(\?.+){0,1}$'
  SolarWindsAPM::Config[:dnt_opts] = Regexp::IGNORECASE

  #
  # GraphQL
  #
  # Enable tracing for GraphQL.
  # (true | false, default: true)
  SolarWindsAPM::Config[:graphql][:enabled] = true
  # Replace query arguments with a '?' when sent with a trace.
  # (true | false, default: true)
  SolarWindsAPM::Config[:graphql][:sanitize] = true
  # Remove comments from queries when sent with a trace.
  # (true | false, default: true)
  SolarWindsAPM::Config[:graphql][:remove_comments] = true
  # Create a transaction name by combining
  # "query" or "mutation" with the first word of the query.
  # This overwrites the default transaction name, which is a combination of
  # controller + action and would be the same for all graphql queries.
  # (true | false, default: true)
  SolarWindsAPM::Config[:graphql][:transaction_name] = true

  #
  # Rack::Cache
  #
  # Create a transaction name like `rack-cache.<cache-store>`,
  # e.g. `rack-cache.memcached`
  # This can reduce the number of transaction names, when many requests are
  # served directly from the cache without hitting a controller action.
  # When set to `false` the path will be used for the transaction name.
  #
  SolarWindsAPM::Config[:rack_cache] = { transaction_name: true }

  #
  # Transaction Settings
  #
  # Use this configuration to add exceptions to the global tracing mode and
  # disable/enable metrics and traces for certain transactions.
  #
  # Currently allowed hash keys:
  # :url to apply listed filters to urls.
  #      The matching of settings to urls happens before routes are applied.
  #      The url is extracted from the env argument passed to rack: `env['PATH_INFO']`
  #
  # and the hashes within the :url list either:
  #   :extensions  takes an array of strings for filtering (not regular expressions!)
  #   :tracing     defaults to :disabled, can be set to :enabled to override
  #              the global :disabled setting
  # or:
  #   :regexp      is a regular expression that is applied to the incoming path
  #   :opts        (optional) nil(default) or Regexp::IGNORECASE (options for regexp)
  #   :tracing     defaults to :disabled, can be set to :enabled to override
  #              the global :disabled setting
  #
  # Be careful not to add too many :regexp configurations as they will slow
  # down execution.
  #
  SolarWindsAPM::Config[:transaction_settings] = {
    url: [
      #   {
      #     extensions: %w['long_job'],
      #     tracing: :disabled
      #   },
      #   {
      #     regexp: '^.*\/long_job\/.*$',
      #     opts: Regexp::IGNORECASE,
      #     tracing: :disabled
      #   },
      #   {
      #     regexp: /batch/,
      #   }
    ]
  }

  #
  # Rails Exception Logging
  #
  # In Rails, raised exceptions with rescue handlers via
  # <tt>rescue_from</tt> are not reported to the SolarWinds   # dashboard by default.  Setting this value to true will
  # report all raised exceptions regardless.
  #
  SolarWindsAPM::Config[:report_rescued_errors] = false

  #
  # EC2 Metadata Fetching Timeout
  #
  # The timeout can be in the range 0 - 3000 (milliseconds)
  # Setting to 0 milliseconds effectively disables fetching from
  # the metadata URL (not waiting), and should only be used if
  # not running on EC2 / Openstack to minimize agent start up time.
  #
  SolarWindsAPM::Config[:ec2_metadata_timeout] = 1000


  #############################################
  ## SETTINGS FOR INDIVIDUAL GEMS/FRAMEWORKS ##
  #############################################

  #
  # Bunny Controller and Action
  #
  # The bunny (Rabbitmq) instrumentation can optionally report
  # Controller and Action values to allow filtering of bunny
  # message handling in # the UI.  Use of Controller and Action
  # for filters is temporary until the UI is updated with
  # additional filters.
  #
  # These values identify which properties of
  # Bunny::MessageProperties to report as Controller
  # and Action.  The defaults are to report :app_id (as
  # Controller) and :type (as Action).  If these values
  # are not specified in the publish, then nothing
  # will be reported here.
  #
  SolarWindsAPM::Config[:bunnyconsumer][:controller] = :app_id
  SolarWindsAPM::Config[:bunnyconsumer][:action] = :type

  #
  # Enabling/Disabling Instrumentation
  #
  # If you're having trouble with one of the instrumentation libraries, they
  # can be individually disabled here by setting the :enabled
  # value to false.
  #
  # :enabled settings are read on startup and can't be changed afterwards
  #
  SolarWindsAPM::Config[:action_controller][:enabled] = true
  SolarWindsAPM::Config[:action_controller_api][:enabled] = true
  SolarWindsAPM::Config[:action_view][:enabled] = true
  SolarWindsAPM::Config[:active_record][:enabled] = true
  SolarWindsAPM::Config[:bunnyclient][:enabled] = true
  SolarWindsAPM::Config[:bunnyconsumer][:enabled] = true
  SolarWindsAPM::Config[:curb][:enabled] = true
  SolarWindsAPM::Config[:dalli][:enabled] = true
  SolarWindsAPM::Config[:delayed_jobclient][:enabled] = true
  SolarWindsAPM::Config[:delayed_jobworker][:enabled] = true
  SolarWindsAPM::Config[:excon][:enabled] = true
  SolarWindsAPM::Config[:faraday][:enabled] = true
  SolarWindsAPM::Config[:grpc_client][:enabled] = true
  SolarWindsAPM::Config[:grpc_server][:enabled] = true
  SolarWindsAPM::Config[:grape][:enabled] = true
  SolarWindsAPM::Config[:httpclient][:enabled] = true
  SolarWindsAPM::Config[:memcached][:enabled] = true
  SolarWindsAPM::Config[:mongo][:enabled] = true
  SolarWindsAPM::Config[:moped][:enabled] = true
  SolarWindsAPM::Config[:nethttp][:enabled] = true
  SolarWindsAPM::Config[:padrino][:enabled] = true
  SolarWindsAPM::Config[:rack][:enabled] = true
  SolarWindsAPM::Config[:redis][:enabled] = true
  SolarWindsAPM::Config[:resqueclient][:enabled] = true
  SolarWindsAPM::Config[:resqueworker][:enabled] = true
  SolarWindsAPM::Config[:rest_client][:enabled] = true
  SolarWindsAPM::Config[:sequel][:enabled] = true
  SolarWindsAPM::Config[:sidekiqclient][:enabled] = true
  SolarWindsAPM::Config[:sidekiqworker][:enabled] = true
  SolarWindsAPM::Config[:sinatra][:enabled] = true
  SolarWindsAPM::Config[:typhoeus][:enabled] = true

  #
  # Argument logging
  #
  #
  # For http requests:
  # By default the query string parameters are included in the URLs reported.
  # Set :log_args to false and instrumentation will stop collecting
  # and reporting query arguments from URLs.
  #
  SolarWindsAPM::Config[:bunnyconsumer][:log_args] = true
  SolarWindsAPM::Config[:curb][:log_args] = true
  SolarWindsAPM::Config[:excon][:log_args] = true
  SolarWindsAPM::Config[:httpclient][:log_args] = true
  SolarWindsAPM::Config[:mongo][:log_args] = true
  SolarWindsAPM::Config[:nethttp][:log_args] = true
  SolarWindsAPM::Config[:rack][:log_args] = true
  SolarWindsAPM::Config[:resqueclient][:log_args] = true
  SolarWindsAPM::Config[:resqueworker][:log_args] = true
  SolarWindsAPM::Config[:sidekiqclient][:log_args] = true
  SolarWindsAPM::Config[:sidekiqworker][:log_args] = true
  SolarWindsAPM::Config[:typhoeus][:log_args] = true

  #
  # Enabling/Disabling Backtrace Collection
  #
  # Instrumentation can optionally collect backtraces as they collect
  # performance metrics.  Note that this has a negative impact on
  # performance but can be useful when trying to locate the source of
  # a certain call or operation.
  #
  SolarWindsAPM::Config[:action_controller][:collect_backtraces] = true
  SolarWindsAPM::Config[:action_controller_api][:collect_backtraces] = true
  SolarWindsAPM::Config[:action_view][:collect_backtraces] = true
  SolarWindsAPM::Config[:active_record][:collect_backtraces] = true
  SolarWindsAPM::Config[:bunnyclient][:collect_backtraces] = false
  SolarWindsAPM::Config[:bunnyconsumer][:collect_backtraces] = false
  SolarWindsAPM::Config[:curb][:collect_backtraces] = true
  SolarWindsAPM::Config[:dalli][:collect_backtraces] = false
  SolarWindsAPM::Config[:delayed_jobclient][:collect_backtraces] = false
  SolarWindsAPM::Config[:delayed_jobworker][:collect_backtraces] = false
  SolarWindsAPM::Config[:excon][:collect_backtraces] = true
  SolarWindsAPM::Config[:faraday][:collect_backtraces] = false
  SolarWindsAPM::Config[:grape][:collect_backtraces] = true
  SolarWindsAPM::Config[:grpc_client][:collect_backtraces] = false
  SolarWindsAPM::Config[:grpc_server][:collect_backtraces] = false
  SolarWindsAPM::Config[:httpclient][:collect_backtraces] = true
  SolarWindsAPM::Config[:memcached][:collect_backtraces] = false
  SolarWindsAPM::Config[:mongo][:collect_backtraces] = true
  SolarWindsAPM::Config[:moped][:collect_backtraces] = true
  SolarWindsAPM::Config[:nethttp][:collect_backtraces] = true
  SolarWindsAPM::Config[:padrino][:collect_backtraces] = true
  SolarWindsAPM::Config[:rack][:collect_backtraces] = true
  SolarWindsAPM::Config[:redis][:collect_backtraces] = false
  SolarWindsAPM::Config[:resqueclient][:collect_backtraces] = true
  SolarWindsAPM::Config[:resqueworker][:collect_backtraces] = true
  SolarWindsAPM::Config[:rest_client][:collect_backtraces] = true
  SolarWindsAPM::Config[:sequel][:collect_backtraces] = true
  SolarWindsAPM::Config[:sidekiqclient][:collect_backtraces] = false
  SolarWindsAPM::Config[:sidekiqworker][:collect_backtraces] = false
  SolarWindsAPM::Config[:sinatra][:collect_backtraces] = true
  SolarWindsAPM::Config[:typhoeus][:collect_backtraces] = false

end

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.