Scout APM Ruby Agent

To develop or test the gem locally, point your Gemfile to your local checkout directory and compile the native code using rake compile.

# Gemfile
gem 'scout_apm', path: '/path/to/scout_apm_ruby'

cd /path/to/scout_apm_ruby && bundle exec rake compile

DevTrace is a free, no-signup, in-browser development profiler. To use it, ensure scout_apm is in your Gemfile, then start your Rails server with the SCOUT_DEV_TRACE environment variable set to true.

SCOUT_DEV_TRACE=true rails server

To install the ScoutApm agent in a Rails application, add the scout_apm gem to your Gemfile. You must also include a version of the parser gem that is compatible with your Ruby version. After updating your Gemfile, run bundle install.

# Gemfile
gem 'scout_apm'

# Example for Ruby 3.3.0
gem 'parser', '~> 3.3.0.0'

The repository provides specialized Gemfiles in the gems/ directory to simulate specific customer environments (e.g., different Rails versions). To run tests using a specific configuration, set the BUNDLE_GEMFILE environment variable to the path of the desired gemfile.

To install the dependencies for a specific configuration:

BUNDLE_GEMFILE=gems/rails5.gemfile bundle install

To execute the test suite using that configuration:

BUNDLE_GEMFILE=gems/rails5.gemfile bundle exec rake

Error monitoring is included in all accounts (up to 5000 errors/month free). To enable error reporting, add errors_enabled: true to your scout_apm.yml configuration file.

# In scout_apm.yml
errors_enabled: true

The monitor configuration key is critical for the agent's behavior:

• If monitor is true: The agent will load instruments (instrumentation) and start background workers to report data to Scout.
• If monitor is false: The agent will not load instruments or start the background worker, effectively disabling APM monitoring.

Exception: If dev_trace is enabled in your configuration, the agent will load instruments even if monitor is false. This is intended for local development/debugging (DevTrace) where you want to see data in your browser without reporting to Scout's APM servers.

To allow short-lived forked processes (like those used in Resque instrumentation) to communicate telemetry back to a parent process, Scout APM uses a Remote Server/Client model.

1. In the Parent Process (Pre-fork): Call start_remote_server!(bind, port) once to start a listening web server that accepts incoming data.
2. In the Child Process (Post-fork): Call become_remote_client!(host, port) to configure the child to report its data to the parent's server.

# In the parent process (e.g., before forking workers)
agent_context.start_remote_server!('127.0.0.1', 1234)

# In the child process (e.g., after a fork)
agent_context.become_remote_client!('127.0.0.1', 1234)

After signing up for a Scout account, create a configuration file at RAILS_ROOT/config/scout_apm.yml. This file uses YAML anchors to manage settings across different environments. Ensure monitor: true is set for environments where you want to report data to Scout.

common: &defaults
  name: YOUR_APPLICATION_NAME
  key: YOUR_APPLICATION_KEY
  monitor: true

test:
  monitor: false

production:
  <<: *defaults

When an error occurs in a Sidekiq job, Scout APM intercepts it to capture context before re-raising the exception.

• Exception Filtering: If the exception is listed in your ignored_exceptions configuration, Scout APM will bail out early and re-raise the error without reporting it to the Scout dashboard.
• Context Capture: For non-ignored errors, Scout APM captures the exception along with job metadata.
• Job Identification: The agent attempts to identify the job class. It supports standard Sidekiq jobs and ActiveJob jobs running via the SidekiqAdapter (by inspecting the ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper class).
• Error Propagation: After capturing the error for shipping, the agent always re-raises the exception to ensure Sidekiq's native error handling and retry mechanisms remain intact.

The Faktory integration uses a middleware (FaktoryMiddleware) to wrap job execution. It provides the following observability data:

• Queue Latency: Calculated using the enqueued_at or created_at timestamps from the job payload.
• Layers: It creates two distinct layers in the Scout APM trace:
  • A Queue layer representing the specific queue name.
  • A Job layer representing the job class name.
• Error Reporting: If a job raises an exception, Scout APM captures the error and attaches metadata including the custom_controller (the job class) and custom_action (the queue name).
• ActiveJob Support: The integration specifically handles ActiveJob when used with the FaktoryAdapter, extracting the wrapped job class from the custom['wrapped'] payload to ensure accurate job naming in traces.

To monitor Shoryuken background jobs with Scout APM, the agent automatically installs a middleware into the Shoryuken stack. This middleware captures each job, tracks its execution time, and calculates queue latency.

When integrated, Scout APM creates two layers for each job execution:

1. A Queue layer (named after the Shoryuken queue).
2. A Job layer (named after the job class).

If you are using ActiveJob with the Shoryuken adapter, the agent correctly identifies the underlying job class from the message body.

Scout APM automatically integrates with the Que background job library to provide visibility into job execution, including queue latency and job class details.

To enable this integration, ensure that the scout_apm gem is installed and that your application is running via the que executable (e.g., que start). The integration automatically hooks into Que::Worker to start the Scout agent and patches Que::Job to trace job execution layers.

When using Que with ActiveJob (v0.14.3+), Scout APM extracts the underlying job class from the ActiveJob::QueueAdapters::QueAdapter::JobWrapper arguments to ensure correct reporting.