Error Monitoring

Note: For general error monitoring feature documentation, see the Error Monitoring features page.

Scout’s Error Monitoring feature allows you to track, triage, and resolve Ruby application errors directly within the Scout UI. By integrating with our existing APM agent, we provide enhanced context and filtering capabilities for comprehensive error management.

Installation

AIf you haven't, add the scout_apm gem to your gemfile.

gem 'scout_apm'

BConfigure Scout in your scout_apm.yml configuration file:

common: &defaults

     # ... other Scout APM settings

     errors_enabled: true

CDeploy!

Once enabled, Scout will automatically begin capturing and organizing errors from your application.

Configuration Options

The following configuration settings are available for error monitoring. These can be set in the scout_apm.yml configuration file or as environment variables with the SCOUT_ prefix, e.g. SCOUT_ERRORS_ENABLED.

Only errors_enabled is required to enable error monitoring. The rest are optional.

Setting Name	Description	Default	Required
errors_enabled	True or false. If true, monitor errors and send them to Scout	`false`	Yes
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
errors_env_capture	Additional environment (request.env) key, values to capture.	`[]`	No

Custom Error Reporting

In addition to automatically capturing unhandled exceptions, Scout provides an API for manually reporting errors with custom context.

Error Capture API

The ScoutApm::Error.capture method accepts up to four arguments:

ScoutApm::Error.capture(error, context = {}, env: nil, name: nil)

error (required): A string message or Exception object
context (optional): Hash of custom context data
env (optional, named): Request environment (e.g., request.env)
name (optional, named): Custom error name (if not specified, will be named: ScoutApm::Error::Custom)

Basic Usage

# Simple string message
ScoutApm::Error.capture("Something went boom")

# With custom context, will be given default name of `ScoutApm::Error::Custom`
ScoutApm::Error.capture("Something went boom", {"user_id" => current_user.id, "action" => "checkout"})

# With full context and environment
ScoutApm::Error.capture(
  "Something went boom", 
  {"context_key" => "context_value"}, 
  env: request.env, 
  name: "BoomError"
)

Rescued Exception Example

class CheckoutController < ApplicationController
  def create
    begin
      process_payment(params[:payment_info])
    rescue PaymentGatewayError => e
      # Report the rescued error with additional context.
      # Can also capture context via the API in addition to passing it in as
      # an argument. See 'Ruby Features' for docs on context.
      ScoutApm::Context.add(company_id: @company.id)
      ScoutApm::Context.add_user(id: @user.id)
      ScoutApm::Error.capture(
        e,
        env: request.env,
        # name: "PaymentProcessingError" # Not needed, we will capture it automatically from the exception class.
      )
      
      # Handle the error gracefully for the user
      redirect_to checkout_path, alert: "Payment failed. Please try again."
    end
  end
end

Error Context and Attributes

Scout automatically enriches error data with contextual information:

Entrypoint: The top-level action (e.g. Controller class) where the error occurred
Custom Context: All key-value pairs from any Custom Context that you have set
Request Data: HTTP method, URI, parameters, and headers
User Context: User identification and session information (when configured)

This context makes it easy to understand the circumstances that led to each error occurrence.

Data Retention

Scout retains error data for 30 days, and aggregate parent groups (total counts, first seen at (& sha), last error message, etc) indefinitely, providing sufficient time for analysis and resolution tracking. This retention period allows teams to:

Identify recurring error patterns
Analyze error trends over time
Maintain historical context for resolved issues
Support post-incident analysis and learning

Integration with APM

Error monitoring seamlessly integrates with Scout’s APM features:

Performance Context: View error occurrences alongside performance traces
Endpoint Analysis: Identify which endpoints generate the most errors
Critical Endpoint Errors: Automatically prioritize errors from marked critical endpoints
Time Correlation: Correlate errors with performance degradation events

For more detailed information on error management features, triage workflows, and team collaboration tools, see the main Error Monitoring documentation.

How It Works

Error monitoring is built into the Scout APM Ruby agent. When an error occurs in your Rails application, Scout automatically captures:

Complete stack trace showing the execution path leading to the error
Request information including URI, method, and parameters
Application context including custom context data
Error grouping based on error type and location

For Rails applications, Scout integrates directly with the Rails error handling system to capture both handled and unhandled exceptions.

Not seeing errors?

Reach out to us at support@scoutapm.com for further support and troubleshooting assistance

Platform Docs

Agent Docs

Support Docs