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
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
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
sample_rate	Gobal sample rate for your application. Rate should be 1-100 serving as a percentage of requests to capture (ex: `80` to capture 80% of requests).	`100`	No
endpoint_sample_rate	Sample rate for all endpoints. `sample_endpoints` will override this rate for matching endpoints. Rate should be 1-100 serving as a percentage of requests to capture.	`100`	No
job_sample_rate	Sample rate for all jobs. `sample_jobs` will override this rate for matching jobs. Rate should be 1-100 serving as a percentage of requests to capture.	`100`	No
ignore_endpoints	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. Replaces old `ignore` configuration.	`[]`	No
ignore_jobs	An Array of job names that Scout should not instrument. Jobs with exact name match will be ignored by the agent.	`[]`	No
sample_endpoints	An Array of web endpoints that Scout should sample at the provided rate (ex: `['/busy_endpoint:50']`). Rate should be 1-100 serving as a percentage of requests to capture.	`[]`	No
sample_jobs	An Array of job names that Scout should sample at the provided rate (ex: `['MyJob:70']`). Rate should be 1-100 serving as a percentage of requests to capture.	`[]`	No
max_traces	The
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:

use_prepend - default: false. If set to true, all instrumentation which supports the Module#prepend method will use that.
alias_method_instruments - default: []. If use_prepend is set to true, you can still specify which particular instruments should use the alias_method approach with this configuration option.
prepend_instruments - default: []. If use_prepend is false, you can still specify which particular instruments should use the prepend approach with this configuration option.

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

ElasticSearch
HTTP
HTTPClient
Memcached
MongoDB (Moped)
Net::HTTP
Redis

Platform Docs

Agent Docs

Support Docs