Configuration Guide

This guide covers all configuration options for Rails Error Dashboard, including advanced features for customization and extensibility.

Table of Contents

• Configuration Defaults Reference
• Opt-in Feature System
• Basic Configuration
• Notification Features
• Performance Features
• Advanced Analytics Features
• Source Code Integration
• Local Variable Capture
• Instance Variable Capture
• Swallowed Exception Detection
• Diagnostic Dump
• Rack Attack Event Tracking
• Process Crash Capture
• Custom Severity Classification
• Custom Grouping
• Ignored Exceptions
• Error Sampling
• Storm Protection
• Scheduled Digests
• Notification Callbacks
• ActiveSupport Notifications
• Backtrace Configuration
• Complete Configuration Example

Configuration Defaults Reference

Reference for the configuration options, with their defaults. Not listed here yet: AI help (llm_*) and OpenTelemetry export (enable_otel_export, otel_service_name, otel_spans), which the generated initializer documents; LLM observability; coverage tracking; and the sensitive-data filter (filter_sensitive_data, sensitive_data_patterns), which is described in the Sensitive Data Filtering section of the features guide, including what its best-effort redaction of free text such as the error message catches, and that it fails closed.

Authentication & Access

Multi-App Support

Dashboard UI

The dashboard sets its own locale for the duration of each request and restores the previous value afterwards, so it neither inherits the host app’s locale nor leaks its own back into the host. This matters because Pagy stores its locale in a thread-local it never resets — without this, a dashboard request landing on a recycled Puma thread would render in whatever language the host app last used.

Notifications - Slack

Notifications - Email

Notifications - Discord

Notifications - Telegram

Notifications - PagerDuty

Notifications - Webhooks

Notifications - Environment Filter (v0.11.0)

Notifications - Throttling

The burst cap exists for the bad deploy that produces hundreds of distinct new errors: each is a first occurrence, so the per-error cooldown never applies to it. The cap is per process, so the worst case is notification_burst_limit × the number of processes per window. The summary goes to Slack, Discord, Telegram and custom webhooks (event new_error_notifications_suppressed). A deployment with only email or PagerDuty enabled has no channel for it: the cap still applies and the summary is written to the Rails log at warn. With no notification channel enabled at all, the cap does nothing.

Notifications - Scheduled Digests

Storm Protection Options

On by default. See Storm Protection below.

Core Features

Error Classification

Performance Optimization

Rate Limiting

Enhanced Metrics

Advanced Analytics - Error Analysis

Advanced Analytics - Baseline Monitoring

Source Code Integration (NEW!)

Breadcrumbs — Request Activity Trail (NEW!)

System Health Snapshot

Local Variable Capture (v0.4.0)

Instance Variable Capture (v0.4.0)

Swallowed Exception Detection (v0.4.0)

Diagnostic Dump (v0.4.0)

Rack Attack Event Tracking (v0.4.0)

Missing Translation Tracking

ActionCable Connection Monitoring (v0.5.0)

ActiveStorage Service Health (v0.5+)

Live reachability needs no option: when config.active_storage.service is set, the ActiveStorage Health page and GET /health run one existence check for a never-stored key against that service (see the API reference).

Issue Tracking — GitHub/GitLab/Codeberg (v0.5.8+)

One switch enables all platform integration: issue creation, auto-create, lifecycle sync, platform state mirroring, and comment display. When enabled, workflow controls (Resolve, Assign, Priority) are replaced by platform state.

Minimal setup:

config.enable_issue_tracking = true
config.issue_tracker_token = ENV["RED_BOT_TOKEN"]

Process Crash Capture (v0.4.0)

Internal Logging & Debugging

Read-Only Attributes

Environment Variables Quick Reference

All environment variables that can be used instead of or alongside configuration:

# Authentication. Not needed in development and test. Everywhere else,
# set both (see Dashboard Credentials). Generate the password with:
#   openssl rand -base64 32
# ERROR_DASHBOARD_USER=admin
# ERROR_DASHBOARD_PASSWORD=

# Multi-App
APPLICATION_NAME=my-api
ERROR_DASHBOARD_ENVIRONMENT=staging                 # Defaults to Rails.env
ERROR_DASHBOARD_NOTIFICATION_ENVIRONMENTS=production  # Comma-separated; unset = notify everywhere

# Database: only when the initializer doesn't set use_separate_database
# (the generated one does), and config.database must be set too
USE_SEPARATE_ERROR_DB=true

# Notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
ERROR_NOTIFICATION_EMAILS=team@example.com,ops@example.com
ERROR_NOTIFICATION_FROM=errors@myapp.com
DASHBOARD_BASE_URL=https://dashboard.example.com
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
TELEGRAM_BOT_TOKEN=123456789:AAF...
TELEGRAM_CHAT_ID=-1001234567890
PAGERDUTY_INTEGRATION_KEY=abc123...
WEBHOOK_URLS=https://hook1.example.com,https://hook2.example.com
WEBHOOK_SIGNING_SECRET=...     # Optional: HMAC-SHA256 signature headers on every custom webhook

# Enhanced Metrics
APP_VERSION=1.2.3
GIT_SHA=abc123def456
GIT_REPOSITORY_URL=https://github.com/user/repo

# Baseline Alerts
BASELINE_ALERT_THRESHOLD=2.0  # Standard deviations
BASELINE_ALERT_COOLDOWN=120   # Minutes

# Issue tracking
RED_BOT_TOKEN=...             # or ISSUE_TRACKER_TOKEN
ISSUE_WEBHOOK_SECRET=...

# AI help
RED_LLM_PROVIDER=openai       # openai or anthropic; any other value fails boot
RED_LLM_API_KEY=...
RED_LLM_MODEL=gpt-5
RED_LLM_OPENAI_ENDPOINT=auto  # auto, responses or chat_completions

# Never set this at runtime: it turns off error capture. Docker images set it
# on the assets:precompile command only (see Running in Production).
# SECRET_KEY_BASE_DUMMY=1

Practical Defaults Guidance

For Development:

config.async_logging = false          # Sync for easier debugging
config.sampling_rate = 1.0             # Log all errors
config.enable_internal_logging = true  # See what's happening
config.log_level = :debug             # Verbose logging

For Production (Low Traffic):

config.async_logging = true           # Background jobs (run a worker)
config.sampling_rate = 1.0            # Log all errors
config.retention_days = 90            # 3 months (schedule RetentionCleanupJob)
config.max_backtrace_lines = 100      # The default

For Production (High Traffic >1000 errors/day):

config.async_logging = true           # REQUIRED (run a worker)
config.sampling_rate = 0.1            # 10% (critical always logged)
config.retention_days = 30            # 1 month (schedule RetentionCleanupJob)
config.max_backtrace_lines = 20       # Reduce storage
config.use_separate_database = true   # Isolate errors
config.database = :error_dashboard    # Its config/database.yml entry

Opt-in Feature System

Rails Error Dashboard uses an opt-in architecture. Core features are always enabled, while everything else is disabled by default.

Tier 1 Features (Always ON):

• ✅ Error capture (controllers, jobs, middleware)
• ✅ Dashboard UI with search and filtering
• ✅ Analytics and trend charts

Optional Features:

• 📧 6 Notification Channels (Slack, Email, Discord, Telegram, PagerDuty, Webhooks)
• ⚡ 3 Performance Features (Async Logging, Error Sampling, Separate Database)
• 📊 7 Advanced Analytics (Baseline Alerts, Fuzzy Matching, Co-occurring Errors, Error Cascades, Correlation, Platform Comparison, Occurrence Patterns)
• 🔍 2 Developer Tools (Source Code Integration, Git Blame)
• 📡 Live updates (enable_live_updates: new errors appear on an open error list; needs turbo-rails and Action Cable, see Real-Time Updates)

Most can be enabled during installation via the interactive installer, and all of them can be turned on or off at any time in the initializer.

Basic Configuration

Create an initializer at config/initializers/rails_error_dashboard.rb:

RailsErrorDashboard.configure do |config|
  # Dashboard credentials come from the ERROR_DASHBOARD_USER and
  # ERROR_DASHBOARD_PASSWORD environment variables. Don't set them here.

  # Data retention (days)
  config.retention_days = 90

  # User model for error association
  config.user_model = "User"

  # Enable/disable middleware and error subscriber
  config.enable_middleware = true
  config.enable_error_subscriber = true
end

Dashboard Credentials

Unless you configure authenticate_with (see Custom Authentication), the dashboard is protected by HTTP Basic Auth. The gem reads the credentials from two environment variables itself, so you don’t need to set them in the initializer:

In development and test, the defaults work. There is nothing to set.

In every other environment (production, staging, uat, or any other name), the defaults are refused, because they are published. Set both variables before you deploy:

# Generate a strong password
openssl rand -base64 32

Put the values wherever your platform keeps secrets or environment variables: Kamal secrets, Heroku config vars, Fly.io secrets, Render environment variables, or the environment: section of a Compose file. Don’t commit them.

If you set only ERROR_DASHBOARD_PASSWORD, the username stays gandalf. That works, but set both. If you set only ERROR_DASHBOARD_USER, the password stays the published default and the app refuses to boot.

What is checked at boot

Outside development and test, the app refuses to boot and raises RailsErrorDashboard::ConfigurationError when either of these is true:

• the username or password is blank, including whitespace only;
• the password is the published default (youshallnotpass) and did not come from ERROR_DASHBOARD_PASSWORD.

The message says which one it was. The login applies the same rule on every request, so these credentials are refused even when the boot check is skipped.

The check runs every time the app boots in that environment, which includes bin/rails db:migrate, bin/rails console and bin/rails assets:precompile. So the two variables must also be present wherever those commands run: a release phase, a migration job, a one-off console.

Two exceptions:

• Docker asset builds. A build step has no secrets. When SECRET_KEY_BASE_DUMMY=1 is set, the check is skipped. The Dockerfile that Rails 7.1+ generates already runs SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile. If yours precompiles without it, add it. Set it on that command only, never in the runtime environment: while it is set, RED skips its error subscriber and captures no errors at all. (It wouldn’t reopen the default credentials, because the login still refuses them.)
• A deliberately public dashboard. Setting ERROR_DASHBOARD_PASSWORD=youshallnotpass explicitly counts as a choice, and is allowed. That is how the public demo runs. Never do it for an app with real data.

Patterns to avoid

config.authenticate_with = false does not turn authentication off. Any falsy value, including Rails.env.production? && -> { ... } outside production, falls back to HTTP Basic Auth.

Using Rails credentials instead

RailsErrorDashboard.configure do |config|
  # Development and test keep the built-in defaults.
  unless Rails.env.development? || Rails.env.test?
    config.dashboard_username = Rails.application.credentials.dig(:error_dashboard, :username)
    config.dashboard_password = Rails.application.credentials.dig(:error_dashboard, :password)
  end
end

If an entry is missing, its value is nil and the app refuses to boot, saying the credentials are blank.

Checking your setup

bin/rails error_dashboard:verify reports whether the app is using custom, default or blank credentials, using the same rule as the boot check.

Upgrading to 0.14.2

0.14.2 closed several ways around the boot check (GHSA-qh4g-qc9x-9f83). An app that relied on one of them now refuses to boot outside development and test. The common causes are:

• only ERROR_DASHBOARD_USER was set;
• the initializer hardcoded the default password;
• a variable was passed through empty, for example by a Compose file;
• authenticate_with evaluated to false.

To fix it, set both variables to real values and make sure the initializer doesn’t overwrite them, or configure an authenticate_with lambda.

Custom Authentication

If you use Devise, Warden, or any other auth system, you can replace HTTP Basic Auth with a lambda that runs in controller context via instance_exec:

RailsErrorDashboard.configure do |config|
  # Devise/Warden — use warden directly (recommended)
  config.authenticate_with = -> {
    if warden.authenticated?
      true
    else
      redirect_to main_app.new_user_session_path, allow_other_host: true
    end
  }

  # Warden with admin scope
  config.authenticate_with = -> { warden.authenticated?(:admin) }

  # Devise helpers work too
  config.authenticate_with = -> { current_user&.admin? }

  # Session-based
  config.authenticate_with = -> { session[:dashboard_admin] == true }
end

Engine controller context. The lambda runs inside the engine’s controller (via instance_exec), which inherits from ActionController::Base, not your app’s ApplicationController. Devise adds its helpers to ActionController::Base, so current_user, user_signed_in? and authenticate_user! work here, and so does warden. A method defined only in your own ApplicationController, or one of its concerns, doesn’t: the lambda raises, RED denies access (403) and logs [RailsErrorDashboard] authenticate_with lambda raised NoMethodError: ….

Works	Doesn’t work
current_user, user_signed_in?, authenticate_user! (Devise)	Methods defined in your ApplicationController
warden.authenticated?, warden.user	Helpers from your app’s own concerns
session, cookies, request, params

How it works:

• The lambda has access to warden, session, request, params, cookies, redirect_to, etc.
• Truthy return → access granted
• Falsy return (including nil) → 403 Forbidden
• Lambda raises → rescued, logged, 403 (fail closed)
• Lambda calls redirect_to → redirect honored (e.g. to your login page)
• authenticate_with is nil (the default) or false → HTTP Basic Auth is used (see Dashboard Credentials)

User IDs That Are Not Integers

At install, user_id takes the type of your app’s primary keys, as Active Storage does for its keys:

# config/application.rb
config.generators do |g|
  g.orm :active_record, primary_key_type: :uuid
end

On an existing install, change the type of user_id on rails_error_dashboard_error_logs and rails_error_dashboard_error_occurrences with a migration of your own. Until then, a user ID that is not an integer is stored as nil rather than as a wrong number.

Notification Features

Rails Error Dashboard supports 6 notification channels, all disabled by default.

Slack Notifications

Send real-time error notifications to Slack channels.

RailsErrorDashboard.configure do |config|
  config.enable_slack_notifications = true
  config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
end

Email Notifications

Send error alerts via email to your team.

RailsErrorDashboard.configure do |config|
  config.enable_email_notifications = true
  config.notification_email_recipients = ["dev@yourapp.com", "team@yourapp.com"]
  config.notification_email_from = "errors@yourapp.com"
end

Discord Notifications

Push errors to Discord channels via webhooks.

RailsErrorDashboard.configure do |config|
  config.enable_discord_notifications = true
  config.discord_webhook_url = ENV['DISCORD_WEBHOOK_URL']
end

Telegram Notifications

Push errors to a Telegram chat, group or channel through the Bot API. Create the bot with @BotFather and find the chat id as described in the Notifications guide.

RailsErrorDashboard.configure do |config|
  config.enable_telegram_notifications = true
  config.telegram_bot_token = ENV['TELEGRAM_BOT_TOKEN']
  config.telegram_chat_id = ENV['TELEGRAM_CHAT_ID']
end

PagerDuty Integration

Escalate critical errors to PagerDuty for on-call teams. Only triggers for critical errors to avoid alert fatigue.

RailsErrorDashboard.configure do |config|
  config.enable_pagerduty_notifications = true
  config.pagerduty_integration_key = ENV['PAGERDUTY_INTEGRATION_KEY']
end

Custom Webhooks

Send errors to custom endpoints (Zapier, IFTTT, custom services).

RailsErrorDashboard.configure do |config|
  config.enable_webhook_notifications = true
  config.webhook_urls = [
    'https://yourapp.com/hooks/errors',
    'https://zapier.com/hooks/catch/123456/abcdef'
  ]
  # Optional: sign every POST (HMAC-SHA256 over timestamp + body) so the
  # receiver can reject forged or replayed requests.
  config.webhook_signing_secret = ENV['WEBHOOK_SIGNING_SECRET']
end

Dashboard Base URL (for notification links):

config.dashboard_base_url = ENV['DASHBOARD_BASE_URL']  # e.g., "https://yourapp.com"

See Notifications Guide for detailed setup instructions.

Performance Features

Optimize performance and reduce database load with these features.

Async Error Logging

Save errors in a background job, so the request that raised them doesn’t wait for the database write. The generated initializer turns this on.

RailsErrorDashboard.configure do |config|
  config.async_logging = true
end

The job runs on your app’s Active Job adapter (config.active_job.queue_adapter): Solid Queue (the default since Rails 8.0), Sidekiq, GoodJob, or Rails’ in-process :async adapter. RED’s config.async_adapter is only checked for a valid value; it doesn’t choose the backend.

A worker has to process RED’s two queues, default and error_notifications. Without a worker, set config.async_logging = false; notifications still need one. See Run a worker for RED’s jobs.

Error Sampling

Reduce database writes by logging only a percentage of non-critical errors. Critical errors are ALWAYS logged regardless of sampling rate.

RailsErrorDashboard.configure do |config|
  config.sampling_rate = 0.1  # Log 10% of non-critical errors
end

See Error Sampling section below for details.

Separate Database

Isolate error data in a dedicated database for better performance and separation of concerns.

RailsErrorDashboard.configure do |config|
  config.use_separate_database = true
  config.database = :error_dashboard  # must match an entry in config/database.yml
end

Boot fails if config.database is missing. Every environment the app boots in also needs that entry in config/database.yml. See the Database Options Guide for setup instructions.

Advanced Analytics Features

Powerful analytics features for deep error insights, all disabled by default.

Baseline Anomaly Alerts

Automatically detect when error rates exceed normal patterns using statistical analysis.

RailsErrorDashboard.configure do |config|
  config.enable_baseline_alerts = true
  config.baseline_alert_threshold_std_devs = 2.0  # An anomaly starts 2 std devs above baseline
  config.baseline_alert_severities = [:critical, :high]  # Error severities that alert
  config.baseline_alert_cooldown_minutes = 120  # 2 hours between alerts for same error
end

Nothing alerts until RailsErrorDashboard::BaselineCalculationJob has calculated the baselines, and nothing in the gem schedules it. Run it daily: see Schedule the periodic jobs.

baseline_alert_severities lists error severities: an anomaly in a :critical or :high error alerts as soon as it passes the threshold. Before 0.14.4 the option was compared with the anomaly’s level (elevated, high, critical) instead, so with the defaults alerts started at 3 standard deviations, and :medium or :low never matched. PagerDuty still receives only anomalies 2 or more standard deviations past the threshold (the :critical level).

See Baseline Monitoring Guide for details.

Fuzzy Error Matching

Find similar errors even with different error_hashes using backtrace signatures and message similarity.

RailsErrorDashboard.configure do |config|
  config.enable_similar_errors = true
end

See Advanced Error Grouping Guide for details.

Co-occurring Errors

Detect errors that happen together in time (within 5-minute windows).

RailsErrorDashboard.configure do |config|
  config.enable_co_occurring_errors = true
end

See Advanced Error Grouping Guide for details.

Error Cascades

Identify parent→child error relationships (error A causes error B).

RailsErrorDashboard.configure do |config|
  config.enable_error_cascades = true
end

Detection runs in RailsErrorDashboard::CascadeDetectionJob, which you schedule hourly with the other periodic jobs; with the flag on and no schedule, the Cascades card stays empty.

See Advanced Error Grouping Guide for details.

Error Correlation

Correlate errors with app versions, users, and time patterns.

RailsErrorDashboard.configure do |config|
  config.enable_error_correlation = true
end

See Error Correlation Guide for details.

Platform Comparison

Compare iOS vs Android vs API health metrics and platform-specific error rates (a desktop browser request is classed as API; Web only appears when you report it manually).

RailsErrorDashboard.configure do |config|
  config.enable_platform_comparison = true
end

See Platform Comparison Guide for details.

Occurrence Patterns

Detect cyclical patterns (daily/weekly rhythms) and error bursts.

RailsErrorDashboard.configure do |config|
  config.enable_occurrence_patterns = true
end

See Occurrence Patterns Guide for details.

Source Code Integration (NEW!)

View source code directly in the error dashboard with git blame information and repository links.

Basic Configuration

RailsErrorDashboard.configure do |config|
  # Enable source code viewer
  config.enable_source_code_integration = true

  # Optional: Enable git blame integration
  config.enable_git_blame = true
end

Advanced Configuration

RailsErrorDashboard.configure do |config|
  # Enable source code viewer
  config.enable_source_code_integration = true

  # Enable git blame
  config.enable_git_blame = true

  # Context lines (±N lines around error)
  config.source_code_context_lines = 5  # Default: 5

  # Cache TTL in seconds
  config.source_code_cache_ttl = 3600  # Default: 1 hour

  # Security: only show app code (hide gems/vendor)
  config.only_show_app_code_source = true  # Default: true

  # Branch strategy for repository links
  config.git_branch_strategy = :commit_sha  # Options: :commit_sha, :current_branch, :main
end

Features

• Source Code Viewer: View actual source code lines around the error
• Git Blame Integration: See who last modified the code and when
• Repository Links: Direct links to GitHub, GitLab, or Bitbucket
• Repository URL: set config.git_repository_url (or GIT_REPOSITORY_URL); it isn’t read from your git remote
• Security: Only reads files within application root directory

Requirements

• Application must be a git repository
• Git must be installed (for git blame functionality)
• Dashboard must have read access to application source files

Use Cases

# Development: Full visibility
config.enable_source_code_integration = true
config.enable_git_blame = true

# Production: Source code only (no git blame for performance)
config.enable_source_code_integration = true
config.enable_git_blame = false

# Staging: Enable both for debugging
if Rails.env.staging?
  config.enable_source_code_integration = true
  config.enable_git_blame = true
end

Privacy & Security

• Self-hosted: Source code never leaves your infrastructure
• Read-only: Dashboard only reads files, never modifies
• Path validation: Only files within app root can be accessed
• No external calls: All processing happens locally

Breadcrumbs — Request Activity Trail (NEW!)

Breadcrumbs capture a timeline of events (SQL queries, controller actions, cache operations, etc.) during a request, then store them with the error for instant debugging context.

Basic Configuration

RailsErrorDashboard.configure do |config|
  # Enable breadcrumbs
  config.enable_breadcrumbs = true
end

Advanced Configuration

RailsErrorDashboard.configure do |config|
  config.enable_breadcrumbs = true

  # Max events per request (default: 40, ring buffer drops oldest when full)
  config.breadcrumb_buffer_size = 40

  # Limit which categories are captured (default: nil = all)
  # Options: :sql, :controller, :cache, :job, :mailer, :deprecation, :custom,
  # :action_cable, :active_storage, :rack_attack, :llm, :llm_tool (Symbols, not Strings)
  config.breadcrumb_categories = [ :sql, :controller ]  # Only SQL and controller events

  # N+1 query detection (analyzes SQL breadcrumbs at display time)
  config.enable_n_plus_one_detection = true  # Default: true
  config.n_plus_one_threshold = 3            # Min repetitions to flag (default: 3, min: 2)
end

Manual Breadcrumbs

Add custom breadcrumbs from anywhere in your application code:

RailsErrorDashboard.add_breadcrumb("checkout started", { cart_id: 123 })
RailsErrorDashboard.add_breadcrumb("payment processed", { provider: "stripe", amount: 99.99 })

Captured Events

N+1 Query Detection

When breadcrumbs and N+1 detection are both enabled, the error detail page automatically analyzes SQL breadcrumbs for repeated query patterns. A yellow warning card appears when the same normalized query shape is repeated above the threshold:

config.enable_n_plus_one_detection = true  # ON by default
config.n_plus_one_threshold = 3            # Flag when same pattern appears 3+ times

The detector normalizes SQL by replacing literal values (WHERE id = 42 → WHERE id = ?) and IN lists (IN (1, 2, 3) → IN (?)) while preserving PostgreSQL double-quoted identifiers. Analysis runs at display time only — zero overhead on requests.

Use Cases

# Development: Full breadcrumb visibility
config.enable_breadcrumbs = true

# Production: Enable with conservative buffer
config.enable_breadcrumbs = true
config.breadcrumb_buffer_size = 25

# High-traffic: Only capture SQL and controller events
config.enable_breadcrumbs = true
config.breadcrumb_categories = [ :sql, :controller ]

Safety

• Default OFF — opt-in only
• Fixed-size ring buffer — no unbounded memory growth
• Thread-local — no mutex/lock, each request isolated
• Cleanup in ensure — buffer cleared even on exceptions (Puma thread reuse safe)
• Every subscriber wrapped in rescue — never raises, never blocks
• Sensitive data filtered — values under sensitive names are replaced with [FILTERED] before storage; free text gets best-effort redaction
• < 0.1ms/request overhead — events already fired by Rails

System Health Snapshot (NEW!)

Capture runtime health metrics (GC stats, memory, threads, connection pool, Puma) at the moment of every error. Displayed in the error detail sidebar.

Quick Start

RailsErrorDashboard.configure do |config|
  config.enable_system_health = true
end

What Gets Captured

Safety

• Default OFF — opt-in only
• Sub-millisecond, except the job-queue counts, which are database or Redis queries (cached per process)
• Every metric individually wrapped in rescue => nil
• Top-level rescue — returns { captured_at: ... } if everything fails (never raises)
• No ObjectSpace scanning — never calls each_object or count_objects
• No Thread backtraces — only .count, never .map(&:backtrace)
• No subprocess — memory via procfs only, no ps, no fork, no backtick
• No Thread.current — the only shared state is the per-process cache of queue counts, refreshed by one thread at a time

Local Variable Capture (v0.4.0)

Capture local variables when an exception is raised via TracePoint(:raise). The most valuable debugging context possible. The snapshot is one level deep: strings, arrays and hashes are copied at raise time, while nested containers and other objects are retained by reference and show their state at serialization time.

RailsErrorDashboard.configure do |config|
  config.enable_local_variables = true

  # Serialization limits (all have sensible defaults)
  config.local_variable_max_count = 15          # Max variables per exception
  config.local_variable_max_depth = 3           # Max object nesting depth
  config.local_variable_max_string_length = 200 # Truncate strings beyond this
  config.local_variable_max_array_items = 10    # Max array items
  config.local_variable_max_hash_items = 20     # Max hash entries

  # Additional sensitive patterns (beyond Rails filter_parameters)
  config.local_variable_filter_patterns = [ /secret/, /token/ ]
end

Safety

• Never stores Binding objects — values extracted immediately, Binding is GC’d
• Sensitive data auto-filtered — Rails filter_parameters applied automatically; free-text values get best-effort redaction
• Configurable limits — all size limits enforced during serialization
• Opt-in only — disabled by default

Instance Variable Capture (v0.4.0)

Capture instance variables from the object that raised the exception (tp.self on the TracePoint).

RailsErrorDashboard.configure do |config|
  config.enable_instance_variables = true
  config.instance_variable_max_count = 20          # Max variables (default: 20)
  config.instance_variable_filter_patterns = []    # Additional sensitive patterns
end

Shares the same TracePoint handler as local variable capture — minimal overhead when both are enabled. Includes _self_class metadata showing the receiver’s class name.

Swallowed Exception Detection (v0.4.0)

Detect exceptions that are raised but silently rescued — the hardest bugs to find. Requires Ruby 3.3+ (TracePoint :rescue event, Feature #19572).

RailsErrorDashboard.configure do |config|
  config.detect_swallowed_exceptions = true

  config.swallowed_exception_max_cache_size = 1000  # Thread-local cache size
  config.swallowed_exception_flush_interval = 60    # Seconds between DB flushes
  config.swallowed_exception_threshold = 0.95       # 95% rescue ratio = "swallowed"
  config.swallowed_exception_ignore_classes = []    # Exception classes to skip
end

Dashboard page at /errors/swallowed_exceptions. Auto-disabled on Ruby < 3.3 with a warning (no crash).

Diagnostic Dump (v0.4.0)

On-demand system state snapshots — environment, GC stats, threads, connection pool, memory, job queue health.

RailsErrorDashboard.configure do |config|
  config.enable_diagnostic_dump = true
end

Trigger via dashboard button or rails error_dashboard:diagnostic_dump NOTE="deploy check". Dashboard page at /errors/diagnostic_dumps.

Rack Attack Event Tracking (v0.4.0)

Record Rack::Attack throttle, blocklist, and track events to their own table, aggregated hourly. Requires the rack-attack gem to be installed and configured in your app. Breadcrumbs are not required.

RailsErrorDashboard.configure do |config|
  config.enable_rack_attack_tracking = true
  config.rack_attack_max_cache_size = 1000      # Buffered keys per thread (LRU)
  config.rack_attack_flush_interval = 5         # Max age of buffered events before a write
end

Buffered events are written out at the end of the request or job that fills the buffer once rack_attack_flush_interval has elapsed, and again when the process exits. The interval is therefore an upper bound on how stale the Rate Limits page can be, not a delay you have to wait out — a rule that matches once still appears. Raising it reduces write volume under sustained rate-limiting; lowering it makes the page more immediate.

If rack-attack is not loaded, a startup warning is logged and no events are recorded. Enabling breadcrumbs as well adds the event to the activity trail on error detail pages. Dashboard page at /errors/rack_attack_summary.

Measuring AI crawler traffic (v0.10.0)

Events record the client’s user agent, and known AI agents are named on the dashboard — GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, Claude-User, Claude Code, PerplexityBot, GitHub Copilot, Bytespider, CCBot and others, alongside ordinary crawlers such as Googlebot so the two can be told apart. The page shows an AI Agent Requests total and a Top Agent column per rule.

Rack::Attack.track rules are the way to feed it. They count matching requests without blocking or throttling anything:

# Who is reading the site, regardless of the format they ask for
Rack::Attack.track("ai agents") do |req|
  ua = req.user_agent.to_s
  req.ip if ua.match?(/GPTBot|ChatGPT-User|OAI-SearchBot|ClaudeBot|Claude-User|Claude-Code|PerplexityBot|GitHubCopilot/i)
end

# Who specifically wants Markdown
Rack::Attack.track("requests accepting markdown") do |req|
  req.ip if req.get? && req.env["HTTP_ACCEPT"].to_s.include?("text/markdown")
end

Run together, the two answer different questions — how many agents read the site, versus how many prefer Markdown. A rule keyed only on Accept: text/markdown will undercount badly: agents differ enormously in whether they use content negotiation at all, so a low Markdown figure means “this agent doesn’t ask for it”, not “no agent wants it”.

path is recorded per event, so .md routes and /llms.txt hits appear in the per-rule breakdown without extra configuration.

Don’t add limit:/period: to a track rule. Rack::Attack routes a counted track through Throttle, which only emits a notification once count > limit — so the rule stays silent below its limit, the opposite of what adding a limit suggests. Leave track rules uncounted.

Buffer overflow

Events are buffered per thread, keyed on rule, match type, discriminator, path, method and user agent, and capped by rack_attack_max_cache_size. Past the cap the oldest entry is evicted, and its count is added to an overflow total rather than discarded — the dashboard reports it instead of silently showing a smaller number.

Tracking many clients (a crawler fleet on rotating IPs generates a distinct key per address) makes eviction more likely. Raise the cap if the page reports overflow:

config.rack_attack_max_cache_size = 5000

Buffered counts are flushed on the interval above, and also at process exit, so a deploy does not discard whatever a thread was still holding.

Process Crash Capture (v0.4.0)

Capture unhandled exceptions that crash the Ruby process via an at_exit hook.

RailsErrorDashboard.configure do |config|
  config.enable_crash_capture = true
  config.crash_capture_path = nil    # nil = Dir.tmpdir; a custom path is created if missing
end

Writes crash data to JSON on disk (database may be unavailable during shutdown). Imported automatically on next boot. Honeybadger, Bugsnag and AppSignal have at_exit reporters too; RED’s difference is that the crash lands in your own database rather than a SaaS.

Custom Severity Classification

Override default severity levels for specific error types. This is useful when you want to treat certain errors differently than the defaults.

Default Severity Levels

• Critical: SecurityError, NoMemoryError, SystemStackError, SignalException, ActiveRecord::StatementInvalid, LoadError, SyntaxError, ActiveRecord::ConnectionNotEstablished, Redis::ConnectionError, OpenSSL::SSL::SSLError
• High: ActiveRecord::RecordNotFound, ArgumentError, TypeError, NoMethodError, NameError, ZeroDivisionError, FloatDomainError, IndexError, KeyError, RangeError
• Medium: ActiveRecord::RecordInvalid, Timeout::Error, Net::ReadTimeout, Net::OpenTimeout, ActiveRecord::RecordNotUnique, JSON::ParserError, CSV::MalformedCSVError, Errno::ECONNREFUSED
• Low: All other errors

Each list matches the exact class name only, not subclasses.

Configuration

RailsErrorDashboard.configure do |config|
  config.custom_severity_rules = {
    # Treat payment errors as critical
    "Stripe::CardError" => :critical,
    "PaymentProcessingError" => :critical,

    # Downgrade validation errors to low
    "ActiveRecord::RecordInvalid" => :low,

    # Custom application errors
    "MyApp::BusinessLogicError" => :medium
  }
end

Each key is the exact class name, as a String. A Regexp or Symbol key never matches, a rule doesn’t cover subclasses, and the order of the rules doesn’t matter. A rule mapping to :critical also exempts that error from sampling.

To check how an error type is classified:

RailsErrorDashboard::Services::SeverityClassifier.classify("Stripe::CardError")  # => :critical

Use Cases

• Payment Errors: Treat as critical to ensure immediate attention
• Validation Errors: Downgrade to low if they’re expected user input errors
• Third-party API Errors: Classify based on business impact
• Custom Application Errors: Set appropriate severity for domain-specific errors

Custom Grouping

RED groups errors by their class, their message with numbers and IDs normalized, the first frame in your code, and the controller and action, within each application. To group some errors differently, return your own key:

RailsErrorDashboard.configure do |config|
  config.custom_fingerprint = ->(exception, context) {
    case exception
    when ActiveRecord::RecordNotFound
      # One group per path, IDs collapsed: /players/1 and /players/2 count together.
      # Outside a request there is no request_url, and nil keeps the default.
      path = context[:request_url]&.split("?")&.first
      "404:#{path.gsub(/\d+/, ':id')}" if path
    when MyApp::ExternalServiceError
      # One group per service, whatever the message says
      "external-#{exception.service_name}"
    end
    # Anything else returns nil: RED's default grouping
  }
end

What the lambda returns

• A non-empty String: errors with the same string share a group, within one application. RED stores a digest of the string, not the string itself.
• nil, or anything that isn’t a non-empty String: RED’s default grouping.
• If the lambda raises, RED logs the failure and uses the default grouping. The error is still recorded.

What context holds

A Hash with Symbol keys. Any value can be nil, and there is no request or controller object: read the fields below.

• Errors RED captures itself, and Rails.error.report: request_url (path and query string), http_method, controller_name, action_name, request_params, user_id, ip_address, user_agent, platform, hostname, content_type, request_id, session_id, request_duration_ms, environment, app_version, occurred_at and source.
• ManualErrorReporter.report: the arguments you passed (request_url, platform, user_id, user_agent, ip_address, app_version, metadata, occurred_at) and source.

Notes

• Storm protection counts errors by the same key, so errors you group together also count together toward its thresholds.
• A new or changed lambda applies to errors captured from then on. Groups already recorded keep their key, so an error that recurs after the change opens a new group once.
• The lambda runs on the request thread for every error. Keep it to a few string operations.

Ignored Exceptions

Prevent certain exceptions from being logged. Useful for reducing noise from expected errors or third-party gems.

Configuration

RailsErrorDashboard.configure do |config|
  config.ignored_exceptions = [
    # Exact class names
    "ActionController::RoutingError",
    "ActiveRecord::RecordNotFound",

    # Regex patterns for flexible matching
    /Rack::Timeout/,
    /ActionController::InvalidAuthenticityToken/,

    # All errors from a specific namespace
    /ThirdPartyGem::.*/
  ]
end

Features

• Class names or classes: "ActiveRecord::RecordNotFound" or ActiveRecord::RecordNotFound, either way including its subclasses. (Before 0.14.4 a class object was not matched; quote the name if your app still runs an older version.)
• Regex Patterns: matched against the exception’s class name only, so they don’t cover subclasses
• Early Exit: Ignored exceptions skip all processing, saving resources

Use Cases

# Production: Ignore bot-related errors
config.ignored_exceptions = [
  "ActionController::RoutingError",  # Bots scanning for vulnerabilities
  /ActionController::InvalidAuthenticityToken/  # CSRF from legitimate crawlers
]

# Development: Ignore known third-party issues
config.ignored_exceptions = [
  /Geocoder::.*/,  # Geocoding API rate limits
  "Redis::CannotConnectError"  # Redis disconnects during development
]

Error Sampling

Reduce database load by logging only a percentage of non-critical errors. Critical errors are ALWAYS logged regardless of sampling rate.

Configuration

RailsErrorDashboard.configure do |config|
  # Log 100% of errors (default)
  config.sampling_rate = 1.0

  # Log only 10% of non-critical errors (critical errors always logged)
  config.sampling_rate = 0.1

  # Disable logging of non-critical errors entirely
  config.sampling_rate = 0.0
end

Behavior

• 1.0 (100%): Log all errors - default behavior
• 0.1 (10%): Log about 10% of non-critical errors, and every critical error
• 0.0 (0%): Skip all non-critical errors, log only critical errors
• Above 1.0 or below 0.0: rejected; the app fails to boot with RailsErrorDashboard::ConfigurationError

Between 0.0 and 1.0, the first occurrence of each error in each process is always logged, so sampling can’t hide that an error exists. (“Each error” here means the exception class plus the first line of your app’s code in the backtrace.)

Critical Errors (Always Logged)

Critical errors bypass sampling: the ten types listed under Default Severity Levels, and any type you map to :critical in custom_severity_rules.

Use Cases

# High-traffic production: Reduce database writes
config.sampling_rate = 0.1  # 10% sampling

# Load testing: Only log critical issues
config.sampling_rate = 0.0  # Skip non-critical

# Monitoring phase: Full visibility
config.sampling_rate = 1.0  # Log everything

Storm Protection

When the error rate spikes, after a bad deploy or during a dependency outage, storm protection limits RED’s own database writes so that error tracking doesn’t add to the incident. It is on by default. Occurrence counts stay exact; what is sampled is per-event detail:

1. Past storm_fingerprint_full_per_minute captures of one error in a minute, RED stops storing context for it, then keeps only every storm_occurrence_sample_keep_everyth occurrence row.
2. Past storm_shedding_threshold_per_second errors per second, RED stops storing per-event context for every error. Past storm_open_threshold_per_second, it only counts. After storm_cooldown_seconds, once the rate is back below the shedding threshold, it captures a sample of events without context, and returns to full capture when the rate stays low.
3. Per-error notifications pause; with storm_notification on, one “storm in progress” notification goes out instead.
4. The buffered counts are written to the error records every storm_flush_interval_seconds.

An error first seen while RED only counts gets a minimal record, with no callbacks, events or notifications. Past storm_max_tracked_fingerprints distinct errors in one process, further events are added to one overflow total that isn’t attached to any error.

Every threshold is per process: each Puma worker and job process keeps its own counts. While storm protection is on, every option in the table must be a positive integer, and storm_open_threshold_per_second must be at least storm_shedding_threshold_per_second; otherwise the app fails to boot. With enable_storm_protection = false, none of this applies, including the cap on automatically created issues.

Scheduled Digests

A daily or weekly summary email of error activity. It is off by default, and nothing sends it until you schedule RailsErrorDashboard::ScheduledDigestJob.

RailsErrorDashboard.configure do |config|
  config.enable_scheduled_digests = true
  config.digest_recipients = ["team@example.com"]  # default: notification_email_recipients
end

The job takes the period as an argument: period: "daily" (the default) or period: "weekly". digest_frequency doesn’t change what it sends. See Schedule the periodic jobs for a Solid Queue schedule and a cron line. The email goes through your app’s Action Mailer setup, from notification_email_from. To send one now, bin/rails error_dashboard:send_digest PERIOD=daily queues the job for your worker.

Notification Callbacks

Register custom Ruby blocks that execute when errors are logged or resolved. Perfect for integrating with external services.

Available Callbacks

1. on_error_logged - Any Error Logged

RailsErrorDashboard.on_error_logged do |error_log|
  # Called when an error is first logged, and when a resolved error reopens.
  # Not called for the other recurrences.

  # Send to custom logging service
  CustomLogger.log(
    level: error_log.severity,
    message: error_log.message,
    metadata: {
      error_type: error_log.error_type,
      platform: error_log.platform,
      environment: error_log.environment
    }
  )
end

2. on_critical_error - Critical Errors Only

RailsErrorDashboard.on_critical_error do |error_log|
  # Called ONLY for critical errors (in addition to on_error_logged), at the same moments

  # Trigger PagerDuty incident
  PagerDuty.trigger(
    summary: "Critical: #{error_log.error_type}",
    severity: "critical",
    source: error_log.platform,
    custom_details: {
      message: error_log.message,
      backtrace: error_log.backtrace&.lines&.first(5)
    }
  )
end

3. on_error_resolved - Error Resolved

RailsErrorDashboard.on_error_resolved do |error_log|
  # Called when one error is resolved (the Resolve button, or ResolveError).
  # Not called for a batch resolve, or for a status change to "resolved".

  # Notify team
  Slack.post_message(
    channel: "#engineering",
    text: "✅ Error resolved: #{error_log.error_type}",
    attachments: [{
      fields: [
        { title: "Resolved By", value: error_log.resolved_by_name },
        { title: "Occurrences", value: error_log.occurrence_count },
        { title: "Resolution", value: error_log.resolution_comment }
      ]
    }]
  )
end

Multiple Callbacks

You can register multiple callbacks for the same event:

# Callback 1: Log to external service
RailsErrorDashboard.on_error_logged do |error_log|
  Datadog.increment("errors.logged", tags: ["type:#{error_log.error_type}"])
end

# Callback 2: Send to analytics
RailsErrorDashboard.on_error_logged do |error_log|
  Analytics.track_error(error_log)
end

# Both callbacks will execute

Error Handling

Callbacks are fail-safe - if one callback raises an error, it won’t break error logging or prevent other callbacks from running. The failure is logged at error level, which you only see when config.log_level isn’t :silent (the default):

RailsErrorDashboard.on_error_logged do |error_log|
  raise "Callback error"  # Logged at error level, other callbacks still run
end

RailsErrorDashboard.on_error_logged do |error_log|
  puts "This still executes"  # ✓ Runs even if previous callback failed
end

Integration Examples

Datadog

RailsErrorDashboard.on_error_logged do |error_log|
  Datadog::Statsd.increment("errors.logged",
    tags: [
      "severity:#{error_log.severity}",
      "platform:#{error_log.platform}",
      "environment:#{error_log.environment}"
    ]
  )
end

Sentry (alongside Error Dashboard)

RailsErrorDashboard.on_critical_error do |error_log|
  Sentry.capture_message(
    "Critical Error: #{error_log.error_type}",
    level: :fatal,
    extra: {
      error_id: error_log.id,
      message: error_log.message,
      platform: error_log.platform
    }
  )
end

Custom Metrics

RailsErrorDashboard.on_error_logged do |error_log|
  Prometheus.error_counter.increment(
    labels: {
      type: error_log.error_type,
      severity: error_log.severity,
      platform: error_log.platform
    }
  )
end

ActiveSupport Notifications

Rails Error Dashboard emits standard Rails instrumentation events that can be subscribed to using ActiveSupport::Notifications.

Available Events

1. error_logged.rails_error_dashboard

Emitted when an error is first logged, and when a resolved error reopens. Not emitted for the other recurrences.

ActiveSupport::Notifications.subscribe("error_logged.rails_error_dashboard") do |name, start, finish, id, payload|
  # Payload contains:
  # - error_log: Full ErrorLog record (payload[:error_log].environment has the environment)
  # - error_id: Error ID
  # - error_type: Exception class name
  # - message: Error message
  # - severity: Error severity (:critical, :high, :medium, :low)
  # - platform: Platform (iOS, Android, API)
  # - occurred_at: Timestamp

  StatsD.increment("errors.logged", tags: ["type:#{payload[:error_type]}"])
end

The events are sent after the error is saved, not around the save, so their duration is always about zero: they can’t be used to time error logging.

2. critical_error.rails_error_dashboard

Emitted when a critical error is logged (in addition to error_logged).

ActiveSupport::Notifications.subscribe("critical_error.rails_error_dashboard") do |name, start, finish, id, payload|
  # Same payload as error_logged

  # Trigger immediate alert
  PagerDuty.trigger_incident(
    title: "Critical Error: #{payload[:error_type]}",
    severity: "critical",
    details: payload[:message]
  )
end

3. error_resolved.rails_error_dashboard

Emitted when an error is marked as resolved.

ActiveSupport::Notifications.subscribe("error_resolved.rails_error_dashboard") do |name, start, finish, id, payload|
  # Payload contains:
  # - error_log: Full ErrorLog record
  # - error_id: Error ID
  # - error_type: Exception class name
  # - resolved_by: Name of person who resolved it
  # - resolved_at: Timestamp

  Analytics.track_resolution(
    error_id: payload[:error_id],
    resolved_by: payload[:resolved_by],
    resolution_time: payload[:resolved_at] - payload[:error_log].occurred_at
  )
end

Using Event Objects

ActiveSupport::Notifications.subscribe("error_logged.rails_error_dashboard") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)

  puts "Event: #{event.name}"
  puts "Error Type: #{event.payload[:error_type]}"
  puts "Severity: #{event.payload[:severity]}"
end

Wildcard Subscriptions

# Subscribe to all Rails Error Dashboard events
ActiveSupport::Notifications.subscribe(/rails_error_dashboard/) do |event|
  Rails.logger.info "Error Dashboard Event: #{event.name}"
end

Integration Examples

NewRelic

ActiveSupport::Notifications.subscribe("critical_error.rails_error_dashboard") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  NewRelic::Agent.notice_error(
    StandardError.new(event.payload[:message]),
    custom_params: {
      error_id: event.payload[:error_id],
      platform: event.payload[:platform]
    }
  )
end

Prometheus

error_counter = Prometheus::Client::Counter.new(
  :rails_errors_total,
  docstring: "Total number of Rails errors",
  labels: [:type, :severity, :platform]
)

ActiveSupport::Notifications.subscribe("error_logged.rails_error_dashboard") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  error_counter.increment(
    labels: {
      type: event.payload[:error_type],
      severity: event.payload[:severity],
      platform: event.payload[:platform]
    }
  )
end

Elasticsearch

ActiveSupport::Notifications.subscribe("error_logged.rails_error_dashboard") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)

  Elasticsearch::Client.new.index(
    index: "rails-errors",
    body: {
      timestamp: event.payload[:occurred_at],
      error_type: event.payload[:error_type],
      message: event.payload[:message],
      severity: event.payload[:severity],
      platform: event.payload[:platform],
      environment: event.payload[:error_log].environment
    }
  )
end

Async Error Logging (Revisited)

See Async Error Logging above. For quick reference:

RailsErrorDashboard.configure do |config|
  # Save errors in a background job on your app's Active Job adapter.
  # A worker must process the default and error_notifications queues.
  config.async_logging = true
end

Backtrace Configuration

Control how many lines of backtrace are stored:

RailsErrorDashboard.configure do |config|
  # Limit backtrace to 100 lines (default)
  config.max_backtrace_lines = 100

  # Store less for high-volume apps
  config.max_backtrace_lines = 50

  # Minimal storage (just the first line)
  config.max_backtrace_lines = 1
end

Benefits:

• Reduced database storage
• Faster error logging
• Still captures the most relevant stack frames

Complete Configuration Example

Here’s a production-ready configuration combining multiple features:

# config/initializers/rails_error_dashboard.rb

RailsErrorDashboard.configure do |config|
  # ============================================================================
  # AUTHENTICATION (Always Required)
  # ============================================================================
  # Credentials come from ERROR_DASHBOARD_USER and ERROR_DASHBOARD_PASSWORD.
  # Don't set them here (see Dashboard Credentials).

  # ============================================================================
  # CORE FEATURES (Always Enabled)
  # ============================================================================
  config.enable_middleware = true
  config.enable_error_subscriber = true
  config.user_model = "User"
  config.retention_days = 90

  # ============================================================================
  # NOTIFICATION SETTINGS
  # ============================================================================

  # Each channel is switched on only when its setting is present. A channel
  # that is on without its URL, key or recipients stops the app booting.

  # Slack Notifications
  config.slack_webhook_url = ENV["SLACK_WEBHOOK_URL"]
  config.enable_slack_notifications = config.slack_webhook_url.present?

  # Email Notifications
  config.notification_email_recipients = ENV.fetch("ERROR_NOTIFICATION_EMAILS", "").split(",").map(&:strip).reject(&:empty?)
  config.notification_email_from = ENV.fetch("ERROR_NOTIFICATION_FROM", "errors@example.com")
  config.enable_email_notifications = config.notification_email_recipients.any?

  # Discord Notifications
  config.discord_webhook_url = ENV["DISCORD_WEBHOOK_URL"]
  config.enable_discord_notifications = config.discord_webhook_url.present?

  # Telegram Notifications
  config.telegram_bot_token = ENV["TELEGRAM_BOT_TOKEN"]
  config.telegram_chat_id = ENV["TELEGRAM_CHAT_ID"]
  config.enable_telegram_notifications = config.telegram_bot_token.present? && config.telegram_chat_id.present?

  # PagerDuty Integration (critical errors only)
  config.pagerduty_integration_key = ENV["PAGERDUTY_INTEGRATION_KEY"]
  config.enable_pagerduty_notifications = config.pagerduty_integration_key.present?

  # Generic Webhook Notifications
  config.webhook_urls = ENV.fetch("WEBHOOK_URLS", "").split(",").map(&:strip).reject(&:empty?)
  config.enable_webhook_notifications = config.webhook_urls.any?

  # Dashboard base URL (used in notification links)
  config.dashboard_base_url = ENV["DASHBOARD_BASE_URL"]

  # ============================================================================
  # PERFORMANCE & SCALABILITY
  # ============================================================================

  # Async Error Logging (on your app's Active Job adapter; run a worker
  # for the default and error_notifications queues)
  config.async_logging = true

  # Backtrace size limiting (default: 100)
  config.max_backtrace_lines = 50

  # Error Sampling (10% - critical errors ALWAYS logged)
  config.sampling_rate = 0.1

  # Ignored exceptions
  config.ignored_exceptions = [
    "ActionController::RoutingError",
    "ActionController::InvalidAuthenticityToken",
    /^ActiveRecord::RecordNotFound/
  ]

  # ============================================================================
  # DATABASE CONFIGURATION
  # ============================================================================
  config.use_separate_database = false
  # With true, also set config.database = :error_dashboard (its database.yml entry)

  # ============================================================================
  # ADVANCED ANALYTICS
  # ============================================================================

  # Baseline Anomaly Alerts (schedule RailsErrorDashboard::BaselineCalculationJob)
  config.enable_baseline_alerts = true
  config.baseline_alert_threshold_std_devs = 2.0
  config.baseline_alert_severities = [:critical, :high]
  config.baseline_alert_cooldown_minutes = 120

  # Fuzzy Error Matching
  config.enable_similar_errors = true

  # Co-occurring Errors
  config.enable_co_occurring_errors = true

  # Error Cascade Detection
  config.enable_error_cascades = true

  # Error Correlation Analysis
  config.enable_error_correlation = true

  # Platform Comparison
  config.enable_platform_comparison = true

  # Occurrence Pattern Detection
  config.enable_occurrence_patterns = true

  # ============================================================================
  # SOURCE CODE INTEGRATION (NEW!)
  # ============================================================================

  # Enable source code viewer
  config.enable_source_code_integration = true

  # Context lines around error (default: 5)
  config.source_code_context_lines = 5

  # Enable git blame integration
  config.enable_git_blame = true

  # Cache TTL in seconds (default: 3600 = 1 hour)
  config.source_code_cache_ttl = 3600

  # Security: only show app code (default: true)
  config.only_show_app_code_source = true

  # Branch strategy for repository links (default: :commit_sha)
  config.git_branch_strategy = :commit_sha

  # ============================================================================
  # BREADCRUMBS (NEW!)
  # ============================================================================

  # Enable breadcrumbs (request activity trail)
  config.enable_breadcrumbs = true

  # Max events per request (default: 40)
  config.breadcrumb_buffer_size = 40

  # Capture all categories (default: nil = all)
  # config.breadcrumb_categories = [:sql, :controller, :cache, :job, :mailer, :custom]

  # ============================================================================
  # SYSTEM HEALTH SNAPSHOT (NEW!)
  # ============================================================================

  # Capture GC, memory, threads, connection pool, RubyVM, YJIT at error time
  config.enable_system_health = true

  # ============================================================================
  # DEEP DEBUGGING (v0.4.0)
  # ============================================================================

  # Local variable capture via TracePoint(:raise)
  config.enable_local_variables = true
  config.local_variable_max_count = 15
  config.local_variable_max_depth = 3
  config.local_variable_max_string_length = 200

  # Instance variable capture from raising object
  config.enable_instance_variables = true
  config.instance_variable_max_count = 20

  # Swallowed exception detection (Ruby 3.3+ required)
  config.detect_swallowed_exceptions = true
  config.swallowed_exception_threshold = 0.95

  # On-demand diagnostic dump
  config.enable_diagnostic_dump = true

  # Rack Attack event tracking (needs the rack-attack gem)
  config.enable_rack_attack_tracking = true

  # ActionCable connection monitoring (requires breadcrumbs)
  config.enable_actioncable_tracking = true

  # ActiveStorage service health (requires breadcrumbs)
  config.enable_activestorage_tracking = true

  # Process crash capture via at_exit hook
  config.enable_crash_capture = true
  # config.crash_capture_path = "/var/log/myapp/crashes"  # default: Dir.tmpdir

  # ============================================================================
  # ADDITIONAL CONFIGURATION
  # ============================================================================

  # Custom severity rules
  config.custom_severity_rules = {
    "PaymentError" => :critical,
    "ValidationError" => :low
  }

  # Enhanced metrics
  config.app_version = ENV["APP_VERSION"]
  config.git_sha = ENV["GIT_SHA"]
  # config.total_users_for_impact = 10000  # For user impact % calculation
end

# ============================================================================
# NOTIFICATION CALLBACKS
# ============================================================================

# Alert on critical errors
RailsErrorDashboard.on_critical_error do |error_log|
  PagerDuty.trigger(
    summary: "Critical: #{error_log.error_type}",
    severity: "critical",
    source: error_log.platform
  )
end

# Track metrics
RailsErrorDashboard.on_error_logged do |error_log|
  StatsD.increment("errors.logged",
    tags: [
      "type:#{error_log.error_type}",
      "severity:#{error_log.severity}",
      "platform:#{error_log.platform}"
    ]
  )
end

# Notify on resolution
RailsErrorDashboard.on_error_resolved do |error_log|
  Slack.post_message(
    channel: "#engineering",
    text: "✅ #{error_log.error_type} resolved by #{error_log.resolved_by_name}"
  )
end

# ============================================================================
# ACTIVESUPPORT NOTIFICATIONS
# ============================================================================

# Send to external logging service
ActiveSupport::Notifications.subscribe("error_logged.rails_error_dashboard") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)

  Elasticsearch::Client.new.index(
    index: "rails-errors",
    body: {
      timestamp: event.payload[:occurred_at],
      error_type: event.payload[:error_type],
      message: event.payload[:message],
      severity: event.payload[:severity],
      platform: event.payload[:platform]
    }
  )
end

Environment-Specific Configuration

Configure differently per environment:

RailsErrorDashboard.configure do |config|
  # Common configuration
  config.user_model = "User"
  config.max_backtrace_lines = 50

  if Rails.env.production?
    # Production: Aggressive sampling, strict filtering
    config.sampling_rate = 0.1
    config.ignored_exceptions = [
      "ActionController::RoutingError",
      /ActionController::InvalidAuthenticityToken/
    ]

  elsif Rails.env.staging?
    # Staging: Moderate sampling
    config.sampling_rate = 0.5

  else
    # Development/Test: Log everything
    config.sampling_rate = 1.0
    config.ignored_exceptions = []
  end
end

Troubleshooting

Configuration Not Taking Effect

Problem: Changes to config/initializers/rails_error_dashboard.rb don’t seem to work.

Solutions:

1. Restart server - Configuration is loaded at startup

   rails server
   

2. Check file location - Must be in config/initializers/

   ls -la config/initializers/rails_error_dashboard.rb
   

3. Check for syntax errors

   ruby -c config/initializers/rails_error_dashboard.rb
   

4. Verify configuration is loaded

   # In rails console: read the options you changed, one by one
   RailsErrorDashboard.configuration.async_logging
   RailsErrorDashboard.configuration.sampling_rate
   

   Don’t print the whole RailsErrorDashboard.configuration object, or paste it into an issue: it includes the dashboard password, webhook URLs and API keys.

Environment Variables Not Working

Problem: ENV['VARIABLE'] returns nil in configuration.

Solutions:

1. Load environment variables before Rails
   • Use dotenv-rails gem for development
   • Use system environment variables in production
2. Check variable is set

   echo $SLACK_WEBHOOK_URL
   

3. Provide defaults

   config.slack_webhook_url = ENV.fetch('SLACK_WEBHOOK_URL', nil)
   

Notifications Not Sending

Problem: Slack/Discord/Telegram notifications aren’t working.

Solutions:

1. Check notifications are enabled

   # In rails console
   RailsErrorDashboard.configuration.enable_slack_notifications
   # Should return true
   

2. Verify webhook URL is set

   RailsErrorDashboard.configuration.slack_webhook_url
   # Should return your webhook URL
   

3. Test webhook manually

   curl -X POST YOUR_WEBHOOK_URL \
     -H 'Content-Type: application/json' \
     -d '{"text": "Test message"}'
   

4. Check background jobs are running, on both queues

   # With Sidekiq: Slack and email jobs use the error_notifications queue
   bundle exec sidekiq -q default -q error_notifications
   
   # With Solid Queue
   bin/jobs
   

5. Check what holds notifications back
   • notification_minimum_severity (default :low): new and reopened errors below it don’t notify. Milestone notifications ignore it.
   • A recurring error notifies only at the notification_threshold_alerts counts (10, 50, 100, 500, 1000), and a reopened one at most every notification_cooldown_minutes (5).
   • notification_burst_limit (10 per 60 seconds, per process) replaces the rest of a burst of new errors with one summary.
   • notification_environments, when set, limits notifications to those environments.
   • Muted errors, errors marked “Won’t fix” and errors during an error storm don’t notify.
   • PagerDuty only receives critical errors, and baseline alerts at the :critical level.

Custom Severity Rules Not Working

Problem: Custom severity rules aren’t being applied.

Solutions:

1. Check rule format - Keys are exact class names, as Strings

   # Correct
   config.custom_severity_rules = {
     "ActiveRecord::RecordNotFound" => :low,
     "Net::ReadTimeout" => :high
   }
   
   # Incorrect: Regexp and Symbol keys never match
   config.custom_severity_rules = {
     /ActiveRecord::RecordNotFound/ => :low,
     :timeout_error => :high
   }
   

2. Check the class name - A rule covers that exact class only, not its subclasses, and the order of the rules doesn’t matter. To see how a type is classified:

   # In rails console
   RailsErrorDashboard::Services::SeverityClassifier.classify("ActiveRecord::RecordNotFound")
   # => :low with the rule above
   

3. Restart the app - The rules are read when each error is classified, but the initializer only runs at boot.

Background Jobs Not Processing

Problem: Async logging enabled but errors not appearing.

Solutions:

1. Check which backend runs the jobs - RED uses your app’s Active Job adapter

   # In rails console
   ActiveJob::Base.queue_adapter
   # (RailsErrorDashboard.configuration.async_adapter doesn't choose it)
   

2. Verify job processor is running, on both queues

   # Sidekiq (must process default and error_notifications)
   ps aux | grep sidekiq
   
   # Solid Queue (process titles start with solid-queue)
   ps aux | grep solid-queue
   

3. Check queued and failed jobs

   # Sidekiq
   require 'sidekiq/api'
   Sidekiq::Queue.new("default").size
   Sidekiq::RetrySet.new.size
   Sidekiq::DeadSet.new.size
   
   # Solid Queue
   SolidQueue::ReadyExecution.count
   SolidQueue::FailedExecution.count
   

   Most of RED’s jobs retry three times and are then dropped with a log line (“discarded after 3 attempts”), so they don’t stay in the failed set. The issue-tracker jobs are the exception.

4. Test with sync logging temporarily

   config.async_logging = false  # For debugging
   

Sampling Too Aggressive

Problem: Too many errors being filtered out.

Solutions:

1. Check sampling rate

   RailsErrorDashboard.configuration.sampling_rate
   # 0.1 = 10% of errors logged
   

2. Critical errors always logged - Check severity

   # Critical errors bypass sampling
   RailsErrorDashboard::Services::SeverityClassifier.critical?("MyError")
   

3. Adjust rate - Start higher, tune down

   config.sampling_rate = 0.5  # Start with 50%
   

4. Always keep specific errors - There is no per-exception sampling hook. Map the types you always want to :critical, which bypasses sampling:

   config.custom_severity_rules = { "Stripe::CardError" => :critical }
   

Database Performance Issues

Problem: Error logging is slow or causing database issues.

Solutions:

1. Enable async logging

   config.async_logging = true
   

2. Use separate database

   config.use_separate_database = true
   config.database = :error_dashboard  # must match an entry in config/database.yml
   

   See the Database Options Guide.

3. Add database indexes - Already included in migrations

4. Reduce backtrace limit

   config.max_backtrace_lines = 20  # Default is 100
   

5. Configure retention policy

   config.retention_days = 30  # Deletes errors unseen for 30 days...
   

   …when RailsErrorDashboard::RetentionCleanupJob runs. Nothing schedules it for you: see Schedule the periodic jobs.

See Database Optimization Guide for more.

Authentication Not Working

Problem: Can’t access dashboard even with correct credentials.

Solutions:

1. Check username and password are set

   # In rails console
   RailsErrorDashboard.configuration.dashboard_username
   RailsErrorDashboard.configuration.dashboard_password
   

2. Check neither value is blank A blank or nil username or password denies every login, in development too. The usual cause is config.dashboard_username = ENV["ERROR_DASHBOARD_USER"] in the initializer with the variable unset. See Dashboard Credentials.

3. Test credentials

   curl -u admin:password http://localhost:3000/red
   

4. Check for proxy/load balancer issues
   • Some proxies strip Authorization headers
   • May need to configure pass-through
5. Clear browser cache - Old credentials may be cached

Multi-App Configuration Issues

Problem: Errors from multiple apps not showing correctly.

Solutions:

1. Set the APPLICATION_NAME environment variable

   APPLICATION_NAME=my-api rails server
   

2. Or configure manually

   config.application_name = "my-api"
   

3. Verify application is created

   # In rails console
   RailsErrorDashboard::Application.all.pluck(:name)
   

4. Check errors are tagged correctly

   RailsErrorDashboard::ErrorLog.last.application.name
   

See Multi-App Support Guide for more.

Resetting Configuration

For tests only. reset_configuration! also drops every registered callback and the issue-tracker hooks, and the new values are not validated. Middleware and subscribers are set up at boot, so resetting doesn’t change them in a running app.

# Reset to defaults
RailsErrorDashboard.reset_configuration!

# Reconfigure
RailsErrorDashboard.configure do |config|
  config.sampling_rate = 1.0
end

Next Steps

• Testing: Write tests for your custom callbacks and severity rules
• Monitoring: Set up ActiveSupport::Notifications subscribers for your metrics service
• Optimization: Review database optimization and performance tuning guides

For questions or issues, visit: https://github.com/AnjanJ/rails_error_dashboard