Rails Error Dashboard

Rails Error Dashboard - Glossary

A comprehensive guide to terms, concepts, and terminology used throughout the Rails Error Dashboard documentation.

Core Concepts

Error Log

An individual occurrence of an error captured by the dashboard. Each error log contains the exception class, message, backtrace, context, and metadata.

Error Group

Errors with identical stack traces are automatically grouped together. The system tracks total occurrences, first seen, last seen, and provides a single view for related errors.

Deduplication

The process of identifying and grouping identical errors using SHA-256 hashing of the normalized stack trace. Prevents duplicate error entries in the database.

Hash Signature

A unique SHA-256 hash generated from an error’s normalized backtrace. Used for error deduplication and grouping.

Occurrence Count

The number of times a specific error (identified by hash signature) has been logged. Incremented atomically using pessimistic locking.

Context

Additional information captured with an error, including:

  • Request details (URL, HTTP method, parameters, headers)
  • User information (ID, email, IP address)
  • Application state (session data, environment variables)
  • Platform and version information

Severity Levels

Critical

Highest severity. Errors that require immediate attention:

  • Payment processing failures
  • Security breaches
  • Data corruption
  • Service outages

Default critical error types: SecurityError, NoMemoryError, SystemStackError, SignalException, ActiveRecord::StatementInvalid, LoadError, SyntaxError, ActiveRecord::ConnectionNotEstablished, Redis::ConnectionError, OpenSSL::SSL::SSLError

Custom severity rules can override defaults.

High

Serious errors that should be addressed soon:

  • Database connection failures
  • Third-party API failures
  • Authentication errors
  • Missing critical data

Default high severity error types: ActiveRecord::RecordNotFound, ArgumentError, TypeError, NoMethodError, NameError, ZeroDivisionError, FloatDomainError, IndexError, KeyError, RangeError

Custom severity rules can override defaults.

Medium

Moderate errors that affect functionality:

  • 404 Not Found (when unexpected)
  • Invalid user input
  • Missing optional resources
  • Deprecated method calls

Default medium severity error types: ActiveRecord::RecordInvalid, Timeout::Error, Net::ReadTimeout, Net::OpenTimeout, ActiveRecord::RecordNotUnique, JSON::ParserError, CSV::MalformedCSVError, Errno::ECONNREFUSED

Low

Minor errors or expected failures:

  • User-initiated cancellations
  • Preview mode errors
  • Development-only warnings

Default: All other error types default to low severity unless matched by critical/high/medium rules or custom severity rules.

Workflow States

New

Default state. Error has not been addressed. Appears in the main error list.

Status: new (database column default)

Valid transitions: Can move to in_progress, investigating, or wont_fix.

In Progress

Someone is actively working on fixing the error. Can be assigned to a team member.

Status: in_progress

Valid transitions: Can move to investigating, resolved, or back to new.

Investigating

Team is analyzing the error to understand root cause.

Status: investigating

Valid transitions: Can move to resolved, in_progress, or wont_fix.

Resolved

Error has been fixed. Removed from main list but still searchable. If the error occurs again, it automatically reopens to new status.

Status: resolved

Valid transitions: Can reopen to new if error recurs.

Won’t Fix

Error is intentionally not being fixed. Removed from main list. Can be reopened if needed.

Status: wont_fix

Valid transitions: Can reopen to new.

Snoozed (Not a Status)

Snoozed is not a status field but a separate snoozed_until datetime column. Errors can be snoozed while in any status. Automatically becomes visible again when snoozed_until time expires.

Features

Async Logging

Error logging happens in a background job instead of blocking the request. Reduces performance impact from ~10-50ms to ~1-2ms per error.

Adapters: Sidekiq, Solid Queue, or Rails’ built-in :async adapter.

Sampling

Only log a percentage of non-critical errors. Useful for high-traffic applications to reduce database load. Critical errors always bypass sampling.

Example: sampling_rate = 0.1 logs 10% of errors.

Backtrace Limiting

Truncate error backtraces to reduce storage size. Default is 50 lines, configurable down to 10-20 for high-volume apps.

Baseline Monitoring

Statistical anomaly detection that compares current error rates against historical baselines. Alerts when error rates exceed 2 standard deviations from the mean.

Metrics: Mean, standard deviation, 95th percentile.

Platform Comparison

Compare error rates and stability across different platforms (iOS, Android, Web, API). Calculates stability scores and health status.

Error Correlation

Analyze relationships between errors and:

  • Release correlation: Errors introduced in specific app versions
  • User correlation: Users experiencing multiple error types
  • Co-occurring errors: Errors that happen together

Cascade Detection

Identify parent-child error relationships where one error triggers subsequent errors. Helps find root causes.

Example: Database connection timeout → Multiple record not found errors

Occurrence Patterns

Detect cyclical patterns in error occurrences:

  • Hourly patterns: Errors during peak hours
  • Daily patterns: Weekend vs weekday differences
  • Burst detection: Sudden spikes in error rates

Fuzzy Error Matching

Find similar errors even if they’re not exact duplicates using:

  • Jaccard similarity: Compare error message and backtrace tokens
  • Levenshtein distance: Measure string similarity

Priority Scoring

Automatic calculation of error priority based on:

  • Severity level (weight: 40%)
  • Occurrence count (weight: 30%)
  • Recency (weight: 20%)
  • User impact (weight: 10%)

Database

Abstract Base Class

Rails pattern for routing specific models to different databases. Used for multi-database support.

class ErrorsRecord < ActiveRecord::Base
  self.abstract_class = true
  connects_to database: { writing: :errors, reading: :errors }
end

Composite Index

Database index on multiple columns. Improves query performance for common filter combinations.

Example: (application_id, occurred_at) for time-range queries per app.

Pessimistic Locking

Database row-level locking using SELECT FOR UPDATE. Prevents race conditions during error deduplication.

Connection Pooling

Reusable database connections. Rails manages a pool of connections shared across requests. Critical for multi-database setups.

Multi-App Support

Application

A registered application instance in the dashboard. Created automatically from APP_NAME environment variable or manual configuration.

Application Name

Unique identifier for each application. Used to filter and separate errors across multiple apps sharing one dashboard.

Sources:

  1. APP_NAME environment variable (recommended)
  2. config.application_name (manual)
  3. Rails.application.class.module_parent_name (fallback)

Shared Database

Single database storing errors from multiple applications. Each error is tagged with application_id.

Separate Database

Dedicated error database, separate from the main application database. Improves performance and isolates error data.

Notifications

Webhook

HTTP POST callback sent when specific events occur. Used for Slack, Discord, and custom integrations.

Notification Channel

Delivery method for error alerts:

  • Slack: Team chat notifications
  • Discord: Server/channel notifications
  • Email: Direct email alerts
  • PagerDuty: Incident management for critical errors
  • Custom: Your own webhook endpoints

Notification Throttling

Rate limiting to prevent alert fatigue. Example: Baseline alerts limited to once per hour per error type.

Severity Threshold

Minimum severity level required to trigger a notification. Example: PagerDuty only receives critical errors.

Real-Time Updates

Turbo Streams

Hotwire/Turbo feature for real-time page updates without JavaScript. Broadcasts DOM changes over WebSockets or SSE.

Broadcast

Server-initiated update sent to connected clients. Used to update error lists and statistics in real-time.

ActionCable

Rails’ WebSocket framework. Powers real-time broadcasts in the dashboard.

Plugin System

Plugin

Custom extension that hooks into error dashboard lifecycle events. Used for custom integrations, metrics, or audit logging.

Plugin Registry

Central registry managing all registered plugins. Ensures plugins execute safely without breaking error logging.

Lifecycle Hooks

Events that trigger plugin callbacks:

  • on_error_logged: When an error is first captured
  • on_error_resolved: When an error is marked as resolved
  • on_error_ignored: When an error is marked as ignored
  • on_error_assigned: When an error is assigned to someone
  • on_error_reopened: When a resolved error occurs again

Safe Execution

Plugin methods wrapped in error handling to prevent plugin failures from breaking core functionality.

Configuration

Initializer

Ruby file in config/initializers/ that runs at Rails startup. Used for gem configuration.

Location: config/initializers/rails_error_dashboard.rb

Configuration Block

DSL for setting gem options:

RailsErrorDashboard.configure do |config|
  config.option_name = value
end

Environment Variables

System-level variables accessed via ENV['NAME']. Used for secrets and environment-specific settings.

Best practice: Use .env files with dotenv-rails gem in development.

Feature Flags

Boolean configuration options that enable/disable specific features:

  • enable_slack_notifications, enable_email_notifications, enable_discord_notifications, enable_pagerduty_notifications, enable_webhook_notifications
  • enable_baseline_alerts, enable_similar_errors, enable_platform_comparison, enable_error_correlation, enable_occurrence_patterns
  • enable_breadcrumbs, enable_system_health, enable_source_code_integration, enable_git_blame
  • enable_local_variables, enable_instance_variables, detect_swallowed_exceptions, enable_diagnostic_dump, enable_rack_attack_tracking, enable_crash_capture

Performance

N+1 Query

Performance anti-pattern where a query is executed once for each item in a collection. Rails Error Dashboard uses eager loading to prevent this.

Solution: .includes(:application) on error queries.

Eager Loading

Preload associated records in a single query instead of multiple queries. Uses Rails’ includes, preload, or eager_load.

Caching

Temporary storage of computed results. Dashboard uses:

  • Stats caching: 1-minute TTL for dashboard statistics
  • Application lookup caching: 1-hour TTL for app names

Background Job

Asynchronous task executed outside the request-response cycle. Used for error logging, notifications, and data cleanup.

Security

HTTP Basic Auth

Simple authentication requiring username and password. Used to protect dashboard access.

Implementation: authenticate_or_request_with_http_basic

XSS (Cross-Site Scripting)

Security vulnerability where user input is rendered as HTML/JavaScript. Dashboard sanitizes all user-provided content.

Protection: json_escape, sanitize, HTML escaping in ERB.

SQL Injection

Security vulnerability where user input is executed as SQL. Rails protects against this with parameterized queries.

Protection: ActiveRecord’s query interface, never raw SQL with string interpolation.

Mass Assignment

Security vulnerability where unwanted attributes are updated. Rails protects with strong parameters.

Protection: Permitted parameters in controllers.

Testing

RSpec

Ruby testing framework. Rails Error Dashboard has 2,600+ tests covering models, controllers, services, and integration.

Factory Bot

Test data generation. Creates realistic test records for errors, applications, and users.

Test Coverage

Percentage of code executed during tests. Measured with SimpleCov.

Current: 90%+ coverage target.

Integration Test

Test that verifies multiple components working together. Example: Error capture → Database save → Notification sent.

API

REST API

HTTP-based API following REST principles. Dashboard provides endpoints for:

  • Creating errors
  • Querying errors
  • Updating error status
  • Retrieving statistics

API Authentication

HTTP Basic Auth required for all API endpoints. Same credentials as dashboard UI.

JSON Response

Structured data format for API responses. Includes status codes, data payload, and error messages.

Deployment

Migration

Database schema change. Rails Error Dashboard includes migrations for creating tables and indexes.

Run: rails db:migrate

Zero-Downtime Deploy

Deployment strategy where new code is deployed without stopping the application. Requires backward-compatible migrations.

Rollback

Reverting to a previous version after a failed deployment. Rails Error Dashboard supports database rollbacks via migration down methods.

Common Abbreviations

  • TTL: Time To Live (cache expiration)
  • MTTR: Mean Time To Resolution (average time to fix errors)
  • SHA: Secure Hash Algorithm (for hash signatures)
  • HTTP: HyperText Transfer Protocol
  • SSL: Secure Sockets Layer (for HTTPS)
  • API: Application Programming Interface
  • UI: User Interface
  • CRUD: Create, Read, Update, Delete
  • DSL: Domain-Specific Language
  • ENV: Environment (variables)
  • DB: Database
  • DDL: Data Definition Language (migrations)
  • ORM: Object-Relational Mapping (ActiveRecord)

Deep Debugging (v0.4.0)

TracePoint

Ruby’s built-in mechanism for hooking into runtime events. Rails Error Dashboard uses TracePoint(:raise) to capture local/instance variables at exception time, and TracePoint(:rescue) (Ruby 3.3+) for swallowed exception detection. Production-safe — Sentry ships the same :raise event.

Local Variable Capture

Capturing the values of local variables at the exact moment an exception is raised, via TracePoint(:raise). Shows what the code was working with when it failed.

Instance Variable Capture

Capturing instance variables from tp.self (the receiver object) when an exception is raised. Shows the internal state of the object that failed.

Swallowed Exception

An exception that is raised but then silently rescued — never logged, re-raised, or handled meaningfully. Detected by comparing raise counts vs rescue counts per code location.

Diagnostic Dump

An on-demand snapshot of the application’s runtime state: environment, GC stats, threads, connection pool, memory, job queue health. Triggered via dashboard button or rake task.

Process Crash Capture

Capturing unhandled exceptions that terminate the Ruby process via an at_exit hook. Writes crash data to disk (JSON) since the database may be unavailable during shutdown. Imported on next boot.

at_exit Hook

Ruby’s Kernel.at_exit — registers a block that runs when the process exits. Used by crash capture to write exception data to disk before the process terminates.

RubyVM.stat

Ruby’s built-in method returning VM internal statistics: constant cache invalidations, class serial number, global method state. Included in system health snapshots when available.

YJIT

Yet Another JIT compiler — Ruby’s built-in JIT (Ruby 3.1+). RubyVM::YJIT.runtime_stats provides compiled ISEQs, code region size, inline/outlined bytes. Included in system health snapshots when YJIT is enabled.

Additional Resources

Need clarification on a term? Open an issue or start a discussion.