Configuration

APPOPTICS_SERVICE_KEY is the only required configuration, everything else is optional.

Environment Variables

Note

  • The new, longer version of the Solarwinds API token only works with appoptics_apm gem versions >= 4.8.0. (Older tokens still work, they have the following characters: 0-9a-fA-F and are 64 characters long, new tokens have: 0-9a-zA-Z_- and are 71 characters long.)
  • 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 configuration file, usually found at /etc/ngingx/nginx.conf. Add a directive like env APPOPTICS_SERVICE_KEY=0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my_service
  • Starting with gem version 4.2.4 these variables can also be configured in the Configuration File. Settings as environment variables will take precedence over settings in the config file.

APPOPTICS_SERVICE_KEY

Service key used to identify your account and the service being instrumented. It should be in the form of <api token>:<service name>

  • Mandatory!
  • System environment variable: APPOPTICS_SERVICE_KEY
  • Config file variable: AppOpticsAPM::Config[:service_key]
  • Default: no default
  • Example: export APPOPTICS_SERVICE_KEY=0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my_service

APPOPTICS_HOSTNAME_ALIAS

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

  • System environment variable: APPOPTICS_HOSTNAME_ALIAS
  • Config file variable: AppOpticsAPM::Config[:hostname_alias]
  • Default: no default
  • Example: export APPOPTICS_HOSTNAME_ALIAS=apm-host-east

APPOPTICS_DEBUG_LEVEL

This changes the log level of the c-library and the appoptics_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 AppOpticsAPM.logger eg. AppOpticsAPM.logger.level = Logger::INFO.

  • System environment variable: APPOPTICS_DEBUG_LEVEL
  • Config file variable: AppOpticsAPM::Config[:debug_level]
  • Default: 3
  • Example: export APPOPTICS_DEBUG_LEVEL=1

APPOPTICS_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: APPOPTICS_GEM_VERBOSE
  • Config file variable: AppOpticsAPM::Config[:verbose]
  • Default: false
  • Example: export APPOPTICS_GEM_VERBOSE=true

APPOPTICS_APM_CONFIG_RUBY

This variable can be set to point to a configuration file. See Configuration File.

  • System environment variable: APPOPTICS_APM_CONFIG_RUBY
  • Config file variable: n/a
  • Default: Ruby or Rails default location (see Configuration File)
  • Example: export APPOPTICS_APM_CONFIG_RUBY=/deploy/app/config/appoptics_apm_config.rb

Configuration File

Location

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

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

It is recommended to set AppOpticsAPM configurations via a configuration 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 ‘appoptics_apm’ in your app, setting :enabled configurations to false in the code will not disable instrumentation and vice versa. Settings for :service_key, :hostname_alias, and :debug_level are only read at startup.

Template File

Rails application: The command bundle exec rails generate appoptics_apm:install will create a config file config/initializers/appoptics_apm.rb with all the default configurations.

Ruby application: Type bundle exec appoptics_apm_config to get a template file appopticcs_apm_config_tmp.rb with all the default configurations copied into the current directory. This file needs to be copied to <app startup directory>/appoptics_apm_config.rb or the path pointed to by APPOPTICS_APM_CONFIG_RUBY and can then be edited.

It is ok to remove configurations from the copied configuration file, the defaults are set independently.

AppOpticsAPM Configurations

The appoptics_apm gem uses a nested hash to store configuration values in AppOpticsAPM::Config. Each key/value pair represents a config option. Most accept only ‘true’ or ‘false’, making config changes a simple operation. The settings can be checked by calling AppOpticsAPM::Config.print_config

All configuration options

# :service_key, :hostname_alias, and :debug_level are startup settings and can't be changed afterwards.
#
# Set APPOPTICS_SERVICE_KEY
# This setting will be overridden if APPOPTICS_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
#
# AppOpticsAPM::Config[:service_key] = '0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my_service'

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

#
# Set APPOPTICS_DEBUG_LEVEL
# This setting will be overridden if APPOPTICS_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).
#
AppOpticsAPM::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:
# AppOpticsAPM.logger.level = Logger::INFO

#
# Set APPOPTICS_GEM_VERBOSE
# This setting will be overridden if APPOPTICS_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
#
AppOpticsAPM::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
#
AppOpticsAPM::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)
#
AppOpticsAPM::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: "ao.traceId=7435A9FE510AE4533414D425DADF4E180D2B4E36-0"
# It ends in '-1' if the request is sampled and in '-0' otherwise.
#
# 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 '0000000000000000000000000000000000000000-0'
#           when there is no tracing context.
#
AppOpticsAPM::Config[:log_traceId] = :never

#
# 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.
#
AppOpticsAPM::Config[:transaction_name][:prepend_domain] = false

#
# Sanitize SQL Statements
#
# The AppOpticsAPM 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 AppOpticsAPM.
#
AppOpticsAPM::Config[:sanitize_sql] = true
AppOpticsAPM::Config[:sanitize_sql_regexp] = '(\'[^\']*\'|\d*\.\d+|\d+|NULL)'
AppOpticsAPM::Config[:sanitize_sql_opts]   = Regexp::IGNORECASE

#
# 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 appoptics 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)
#
AppOpticsAPM::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}$'
AppOpticsAPM::Config[:dnt_opts] = Regexp::IGNORECASE
#

#
# 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.
#
AppOpticsAPM::Config[:transaction_settings] = {
  url: [
  #   {
  #     extensions: %w['long_job'],
  #     tracing: :disabled
  #   },
  #   {
  #     regexp: '^.*\/long_job\/.*$',
  #     opts: Regexp::IGNORECASE,
  #     tracing: :disabled
  #   },
  #   {
  #     regexp: /batch/,
  #   }
  ]
}
#

#
# Blacklist urls
#
# This configuration is used by outbound calls. If the call
# goes to a blacklisted url then we won't add any
# tracing information to the headers.
#
# The list has to an array of strings, even if only one url is blacklisted
#
# Example: AppOpticsAPM::Config[:blacklist] = ['google.com']
#
AppOpticsAPM::Config[:blacklist] = []
#

#
# Rails Exception Logging
#
# In Rails, raised exceptions with rescue handlers via
# <tt>rescue_from</tt> are not reported to the AppOptics
# dashboard by default.  Setting this value to true will
# report all raised exceptions regardless.
#
AppOpticsAPM::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.
#
AppOpticsAPM::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.
#
AppOpticsAPM::Config[:bunnyconsumer][:controller] = :app_id
AppOpticsAPM::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
#
AppOpticsAPM::Config[:action_controller][:enabled] = true
AppOpticsAPM::Config[:action_controller_api][:enabled] = true
AppOpticsAPM::Config[:action_view][:enabled] = true
AppOpticsAPM::Config[:active_record][:enabled] = true
AppOpticsAPM::Config[:bunnyclient][:enabled] = true
AppOpticsAPM::Config[:bunnyconsumer][:enabled] = true
AppOpticsAPM::Config[:cassandra][:enabled] = true
AppOpticsAPM::Config[:curb][:enabled] = true
AppOpticsAPM::Config[:dalli][:enabled] = true
AppOpticsAPM::Config[:delayed_jobclient][:enabled] = true
AppOpticsAPM::Config[:delayed_jobworker][:enabled] = true
AppOpticsAPM::Config[:excon][:enabled] = true
AppOpticsAPM::Config[:faraday][:enabled] = true
AppOpticsAPM::Config[:grpc_client][:enabled] = true
AppOpticsAPM::Config[:grpc_server][:enabled] = true
AppOpticsAPM::Config[:grape][:enabled] = true
AppOpticsAPM::Config[:httpclient][:enabled] = true
AppOpticsAPM::Config[:memcached][:enabled] = true
AppOpticsAPM::Config[:mongo][:enabled] = true
AppOpticsAPM::Config[:moped][:enabled] = true
AppOpticsAPM::Config[:nethttp][:enabled] = true
AppOpticsAPM::Config[:padrino][:enabled] = true
AppOpticsAPM::Config[:rack][:enabled] = true
AppOpticsAPM::Config[:redis][:enabled] = true
AppOpticsAPM::Config[:resqueclient][:enabled] = true
AppOpticsAPM::Config[:resqueworker][:enabled] = true
AppOpticsAPM::Config[:rest_client][:enabled] = true
AppOpticsAPM::Config[:sequel][:enabled] = true
AppOpticsAPM::Config[:sidekiqclient][:enabled] = true
AppOpticsAPM::Config[:sidekiqworker][:enabled] = true
AppOpticsAPM::Config[:sinatra][:enabled] = true
AppOpticsAPM::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.
#
AppOpticsAPM::Config[:bunnyconsumer][:log_args] = true
AppOpticsAPM::Config[:curb][:log_args] = true
AppOpticsAPM::Config[:excon][:log_args] = true
AppOpticsAPM::Config[:httpclient][:log_args] = true
AppOpticsAPM::Config[:mongo][:log_args] = true
AppOpticsAPM::Config[:nethttp][:log_args] = true
AppOpticsAPM::Config[:rack][:log_args] = true
AppOpticsAPM::Config[:resqueclient][:log_args] = true
AppOpticsAPM::Config[:resqueworker][:log_args] = true
AppOpticsAPM::Config[:sidekiqclient][:log_args] = true
AppOpticsAPM::Config[:sidekiqworker][:log_args] = true
AppOpticsAPM::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.
#
AppOpticsAPM::Config[:action_controller][:collect_backtraces] = true
AppOpticsAPM::Config[:action_controller_api][:collect_backtraces] = true
AppOpticsAPM::Config[:action_view][:collect_backtraces] = true
AppOpticsAPM::Config[:active_record][:collect_backtraces] = true
AppOpticsAPM::Config[:bunnyclient][:collect_backtraces] = false
AppOpticsAPM::Config[:bunnyconsumer][:collect_backtraces] = false
AppOpticsAPM::Config[:cassandra][:collect_backtraces] = true
AppOpticsAPM::Config[:curb][:collect_backtraces] = true
AppOpticsAPM::Config[:dalli][:collect_backtraces] = false
AppOpticsAPM::Config[:delayed_jobclient][:collect_backtraces] = false
AppOpticsAPM::Config[:delayed_jobworker][:collect_backtraces] = false
AppOpticsAPM::Config[:excon][:collect_backtraces] = true
AppOpticsAPM::Config[:faraday][:collect_backtraces] = false
AppOpticsAPM::Config[:grape][:collect_backtraces] = true
AppOpticsAPM::Config[:grpc_client][:collect_backtraces] = false
AppOpticsAPM::Config[:grpc_server][:collect_backtraces] = false
AppOpticsAPM::Config[:httpclient][:collect_backtraces] = true
AppOpticsAPM::Config[:memcached][:collect_backtraces] = false
AppOpticsAPM::Config[:mongo][:collect_backtraces] = true
AppOpticsAPM::Config[:moped][:collect_backtraces] = true
AppOpticsAPM::Config[:nethttp][:collect_backtraces] = true
AppOpticsAPM::Config[:padrino][:collect_backtraces] = true
AppOpticsAPM::Config[:rack][:collect_backtraces] = true
AppOpticsAPM::Config[:redis][:collect_backtraces] = false
AppOpticsAPM::Config[:resqueclient][:collect_backtraces] = true
AppOpticsAPM::Config[:resqueworker][:collect_backtraces] = true
AppOpticsAPM::Config[:rest_client][:collect_backtraces] = true
AppOpticsAPM::Config[:sequel][:collect_backtraces] = true
AppOpticsAPM::Config[:sidekiqclient][:collect_backtraces] = false
AppOpticsAPM::Config[:sidekiqworker][:collect_backtraces] = false
AppOpticsAPM::Config[:sinatra][:collect_backtraces] = true
AppOpticsAPM::Config[:typhoeus][:collect_backtraces] = false