Ruby Configuration

Configuration Options

The Ruby agent can be configured via the config/scout_apm.yml Yaml file and/or environment variables. A config file with your organization key is available for download as part of the install instructions.

Heroku users should use environment variables instead of the scout_apm.yml.

ERB evaluation

ERB is evaluated when loading the config file. For example, you can set the app name based on the hostname:

common: &defaults
  name: <%= "ProjectPlanner.io (#{Rails.env})" %>

Environment Variables

You can also configure Scout APM via environment variables. Environment variables override settings provided in scout_apm.yml. To configure Scout via enviroment variables, uppercase the config key and prefix it with SCOUT_. For example, to set the key via environment variables: export SCOUT_KEY=YOURKEY

Common Configurations

The following configuration settings are available:

Setting Name Description Default Required
name Name of the application (ex: ‘Photos App’). Rails.application.class.to_s. sub(/::Application$/, '') Yes
key The organization API key. Yes
monitor Whether monitoring should be enabled. false Yes
errors_enabled Whether Error Monitoring should be enabled. false No
auto_instruments Instrument custom code with Auto Instruments. false No
log_level The logging level of the agent. INFO No

Additional Configurations

Setting Name Description Default Required
dev_trace Indicates if DevTrace, the Scout development profiler, should be enabled. Note this setting only applies to the development environment. false No
detailed_middleware When true, the time spent in each middleware is visible in transaction traces vs. an aggregrate across all middlewares. This adds additional overhead and is disabled by default as middleware is an uncommon bottleneck. false No
hostname Allows renaming of the node/host name Socket.gethostname No
revision_sha The Git SHA that corresponds to the version of the app being deployed. See docs No
scm_subdirectory The relative path from the base of your Git repo to the directory which contains your application code. No
ignore An Array of web endpoints that Scout should not instrument. Routes that match the prefixed path (ex: ['/health', '/status']) will be ignored by the agent. [] No
enable_background_jobs Indicates if background jobs should be monitored. true No
collect_remote_ip Automatically capture end user IP addresses as part of each trace’s context. true No
record_queue_time Automatically capture request queue time when a queuing request header is found. true No
auto_instruments_ignore Excludes the listed files names from being auto instrumented. Ex: ['application_controller']. [] No
errors_ignored_exceptions Excludes certain exceptions from being reported [ActiveRecord::RecordNotFound, ActionController::RoutingError] No
errors_filtered_params Filtered parameters in exceptions [password, s3-key] No
log_file_path The path to the scout_apm.log log file directory. Use stdout to log to STDOUT. Environment#root+log/ or STDOUT if running on Heroku. No
proxy Specify the proxy URL (ex: https://proxy) if a proxy is required. No
host The protocol + domain where the agent should report. https://scoutapm.com No
uri_reporting By default Scout reports the URL and filtered query parameters with transaction traces. Sensitive parameters in the URL will be redacted. To exclude query params entirely, use path. filtered_params No
disabled_instruments An Array of instruments that Scout should not install. Each Array element should should be a string-ified, case-sensitive class name (ex: ['Elasticsearch','HttpClient']). The default installed instruments can be viewed in the agent source. [] No
timeline_traces Send traces in both the summary and timeline formats. true No
use_prepend Where supported, use Method#prepend for instrumentation. false No
alias_method_instruments If use_prepend is set to true, specify which particular instruments should still use the alias_method approach. Each Array element should should be a string-ified, case-sensitive class name (ex: ['Elasticsearch','HttpClient']). The default installed instruments can be viewed in the agent source. [] No
prepend_instruments If use_prepend is set to false, specify which particular instruments should use the prepend approach. Each Array element should should be a string-ified, case-sensitive class name (ex: ['Elasticsearch','HttpClient']). The default installed instruments can be viewed in the agent source. [] No

Environments

It typically makes sense to treat each environment (production, staging, etc) as a separate application within Scout and ignore the development and test environments. Configure a unique app name for each environment as Scout aggregates data by the app name.

Ex:

export SCOUT_KEY=YOURKEY
export SCOUT_NAME=YOURAPPNAME (Production)

Library Instrumentation Method

For many of our instruments, the Scout Ruby agent has historically used Module#alias_method to monkeypatch specific library methods to gather telemetry. The more modern approach is to use Module#prepend, which many other gems now use as default. In certain cases, if a gem that uses Module#prepend and another gem that uses Module#alias_method have applied their instrumentation to the same library, an infinite loop can occur resulting in a StackLevelTooDeep exception.

Moving from alias_method to prepend has caused major headaches for nearly all gems which made the switch, despite making the change in a major version semantic version bump. In order to allow a less disruptive upgrade path, Scout will continue to use alias_method as the default, but with available configuration option to move either all instrumentation to prepend, or selectively move instrumentation to prepend.

With Scout APM Version 5.3.0 and above, use the following configuration options to control the instrumentation method:

The Scout instrumentation for the following libraries support Module#prepend in addition to Module#alias_method in scout_apm >= 5.3.0 :