Rails Error Dashboard

Self-hosted error tracking and exception monitoring for Ruby on Rails. Open source, free forever. A Sentry alternative with cause chains, analytics, workflow management, and multi-channel notifications.

Download as .zip Download as .tar.gz View on GitHub

Quickstart Guide

Get Rails Error Dashboard up and running in 5 minutes!

Prerequisites

Installation

1. Add to Gemfile

gem 'rails_error_dashboard'

2. Install with Interactive Setup

bundle install
rails generate rails_error_dashboard:install
rails db:migrate

Interactive Feature Selection

The installer will guide you through optional features organized in 4 categories:

Notifications (5 features)

Performance & Scalability (3 features)

Advanced Analytics (7 features)

Developer Tools (4 features)

Deep Debugging (6 features) — v0.4.0

All features are opt-in - you can say “no” to everything and just use the core dashboard, or enable specific features you need.

Example Installation Flow

$ rails generate rails_error_dashboard:install

╔════════════════════════════════════════════════════════════════════╗
║        Rails Error Dashboard - Interactive Installation            ║
╚════════════════════════════════════════════════════════════════════╝

This installer will help you configure optional features.
Core features (error capture, dashboard UI, analytics) are always enabled.

Choose the features you want to enable:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📧  NOTIFICATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[1/24] Slack Notifications
    Send real-time error notifications to Slack channels
    Enable? (y/N): y

[2/24] Email Notifications
    Send error alerts via email to your team
    Enable? (y/N): n

...

✓ Installation complete!

Enabled features:
  ✓ Slack Notifications
  ✓ Async Logging
  ✓ Baseline Anomaly Alerts

Next steps:
  1. Edit config/initializers/rails_error_dashboard.rb
  2. Set environment variables (if needed)
  3. Run: rails db:migrate
  4. Visit: http://localhost:3000/error_dashboard

That’s it! The dashboard is now available at /error_dashboard in your Rails app.

First Steps

Access the Dashboard

Visit http://localhost:3000/error_dashboard to see the error dashboard.

Initially, you won’t see any errors. Let’s create one to test:

# In rails console
raise "Test error from console"

Or create a controller error:

# app/controllers/home_controller.rb
class HomeController < ApplicationController
  def index
    raise "Test error from controller"
  end
end

Visit the route and check /error_dashboard - you should see your test error!

Configure Basic Settings

The installer creates config/initializers/rails_error_dashboard.rb with your selected features already configured:

RailsErrorDashboard.configure do |config|
  # ============================================================================
  # AUTHENTICATION (Always Required)
  # ============================================================================
  config.dashboard_username = ENV.fetch("ERROR_DASHBOARD_USER", "gandalf")
  config.dashboard_password = ENV.fetch("ERROR_DASHBOARD_PASSWORD", "youshallnotpass")

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

  # ============================================================================
  # OPTIONAL FEATURES (Based on your selections during install)
  # ============================================================================

  # Async Logging - ENABLED (if you selected it during install)
  config.async_logging = true
  config.async_adapter = :sidekiq  # Options: :sidekiq, :solid_queue, :async

  # Slack Notifications - ENABLED (if you selected it during install)
  config.enable_slack_notifications = true
  config.slack_webhook_url = ENV["SLACK_WEBHOOK_URL"]

  # Baseline Anomaly Alerts - ENABLED (if you selected it during install)
  config.enable_baseline_alerts = true
  config.baseline_alert_threshold_std_devs = 2.0

  # ... other features based on your selections
end

Important: Change the default username and password before deploying to production!

Using Devise or another auth system? Replace HTTP Basic Auth with a lambda:

config.authenticate_with = -> { warden.authenticated? }

Note: Devise helpers like current_user are not available in the engine controller context. Use warden directly instead. See the Configuration Guide for details and examples.

You can enable or disable any feature at any time by editing this file. Just change true to false (or vice versa) and restart your Rails server.

Enabling Features After Installation

All features can be toggled on/off at any time by editing config/initializers/rails_error_dashboard.rb:

Enable a Feature

To enable a feature that was disabled during installation:

RailsErrorDashboard.configure do |config|
  # Change from false to true
  config.enable_slack_notifications = true
  config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
end

Disable a Feature

To disable a feature that was enabled during installation:

RailsErrorDashboard.configure do |config|
  # Change from true to false
  config.enable_baseline_alerts = false
end

Feature Examples

Slack Notifications:

config.enable_slack_notifications = true
config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']

Async Logging (Better Performance):

config.async_logging = true
config.async_adapter = :sidekiq  # or :solid_queue, :async

Error Sampling (High-Traffic Apps):

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

Baseline Anomaly Alerts:

config.enable_baseline_alerts = true
config.baseline_alert_threshold_std_devs = 2.0

Fuzzy Error Matching:

config.enable_similar_errors = true

Platform Comparison:

config.enable_platform_comparison = true

See the Complete Configuration Guide for all configuration options.

Common Tasks

Resolve an Error

  1. Go to /error_dashboard
  2. Click on an error
  3. Click “Mark as Resolved”
  4. Add a resolution comment (optional)

Batch Delete Errors

  1. Go to /error_dashboard
  2. Select errors using checkboxes
  3. Click “Bulk Actions” → “Delete Selected”

Filter Errors

Use the sidebar filters:

Next Steps

Now that you have the basics working:

  1. Set up notifications: Notifications Guide
  2. Customize severity: Customization Guide
  3. Enable advanced features: Baseline Monitoring
  4. Build integrations: Plugin System

Troubleshooting

“No errors showing up”

Check:

  1. Errors are being logged: rails console → raise "test"
  2. Database migration ran: rails db:migrate:status | grep error_dashboard
  3. Middleware is active: Check config/application.rb

Fix:

# Re-run the installer to copy migrations, then migrate
rails generate rails_error_dashboard:install
rails db:migrate

“Dashboard returns 404”

Check routes:

rails routes | grep error

Should see:

Rails.application.routes.draw do
  mount RailsErrorDashboard::Engine => "/error_dashboard"
end

“Authentication not working”

Using HTTP Basic Auth? Verify credentials in config/initializers/rails_error_dashboard.rb:

config.dashboard_username = "admin"
config.dashboard_password = "your_password"

Using custom auth (Devise/Warden)? Verify your lambda works:

config.authenticate_with = -> { warden.authenticated? }

Common mistake: Using current_user — this will raise NameError because Devise helpers aren’t available in the engine controller. Use warden directly instead.

Check log/production.log for [RailsErrorDashboard] authenticate_with lambda raised messages — these indicate your lambda is raising an error (which results in 403 denied).

Restart server after changing configuration:

rails server

“Errors not capturing automatically”

The middleware and error subscriber are installed automatically by the engine. Check that they’re enabled in your initializer:

# config/initializers/rails_error_dashboard.rb
config.enable_middleware = true
config.enable_error_subscriber = true

Re-run the installer if needed:

rails generate rails_error_dashboard:install

Performance Tips

Use Async Logging

For production apps, enable async logging:

config.async_logging = true
config.async_adapter = :sidekiq

With Sidekiq:

# Gemfile
gem 'sidekiq'

# config/initializers/rails_error_dashboard.rb
config.async_adapter = :sidekiq

With SolidQueue:

# Gemfile
gem 'solid_queue'

# config/initializers/rails_error_dashboard.rb
config.async_adapter = :solid_queue

Limit Backtrace Size

Large backtraces slow down the database:

config.max_backtrace_lines = 100  # Default
config.max_backtrace_lines = 50   # Smaller for high-volume apps

Sample Errors

For apps with >1000 errors/day:

config.sampling_rate = 0.1  # Log 10% of errors

Production Checklist

Before deploying to production:

Getting Help

What’s Next?

Explore advanced features:

Congratulations! Your error dashboard is now running. Start catching and resolving errors! 🎉