rails_error_dashboard 0.8.1 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 532921b0ba2ccb40a532a66e5e3c7b1fcf17fc56e53cb5b0ed3772648644f0c0
-  data.tar.gz: 282169f161d90326aaebce5933521cd54c8bb373611e9002b447f114b6654204
+  metadata.gz: 270ac48ebee51c2f68cab29abdbf1169b7db7d7b860bf1fc5a43883960cdc0c6
+  data.tar.gz: 6def5b5a2bbcabffd1116f13607771f6923823dc65eec803e028ba911af85ec9
 SHA512:
-  metadata.gz: 63c2ba5ef4319eaff8450837fec526135e37865ea0d2c72c30b7010ff6e86c03e49f728172d032bec6ad626f8dba39d00841300839fee9b8a493caa912669559
-  data.tar.gz: c84238b00e2f6959fd1e4ac5a1c9ff2d696a0d28379a102e99d761585caf4c24a4f6446f4d303d69c933e5135b31e7c3ef1d0a6b7464376e88ad25b14068c75a
+  metadata.gz: fd6984fc8ccb2a68f9543786ffd6157d1a975ed5d446a13e38b3a38b42cc93047117918186b7f3936c2ddc3a53c3609db63073abad5f25d02edba4961e7b1f30
+  data.tar.gz: 55ba8d78b0d06176ac80e63919cd29a6ca94423d8880712c8fb82979a17741b5881878ef2351efd89c468fbb3d03c6411c82c5c4668a687f4f441b512c169814

data/README.md

@@ -13,7 +13,7 @@
 gem 'rails_error_dashboard'
 ```
 
-**5-minute setup** · **Works out-of-the-box** · **Postgres, MySQL/Trilogy, SQLite** · **No vendor lock-in**
+**5-minute setup** · **Works out-of-the-box** · **PostgreSQL, MySQL/Trilogy, SQLite — shared or separate database** · **No vendor lock-in**
 
 [Full Documentation](https://anjanj.github.io/rails_error_dashboard/) · [Live Demo](https://rails-error-dashboard.anjan.dev) · [RubyGems](https://rubygems.org/gems/rails_error_dashboard)
 
@@ -79,6 +79,28 @@ Error capture from controllers, jobs, and middleware. Custom-designed dashboard
 
 ### Optional Features
 
+<details>
+<summary><strong>Storm Protection — Circuit Breaker + Adaptive Sampling</strong></summary>
+
+When the error rate spikes (a bad deploy throwing thousands of errors a minute), the nightmare scenario for any in-process tracker is amplifying the outage with its own database writes. Storm protection makes the gem **provably degrade itself first** — ON by default.
+
+- **Per-fingerprint caps:** past N occurrences/minute per error, context is shed, then rows are sampled deterministically (a fresh exemplar is always kept each minute)
+- **Global circuit breaker:** sustained floods flip the gem to count-only mode — zero per-event I/O, exact in-memory counts reconciled onto error records every 30s. Async mode is gated too (a SolidQueue enqueue is itself a DB write)
+- **One storm notification** replaces hundreds of per-error pings; auto-issue creation is capped (default 5 per 10 min) so a storm of new errors can't open 500 GitHub/Linear issues
+- **Honest accounting:** a dashboard banner during/after the storm, a Storm History page with exact counts of everything shed, and `reached_open`/peak-rate per episode. Counts are never extrapolated
+- **Calm-weather economy:** after 25 full-context captures of the same error per day, context is sampled (occurrence counting unaffected)
+- **Fails open:** any internal storm-protection error means full capture. Protection can never be the thing that loses an error
+
+```ruby
+config.enable_storm_protection = true  # default
+config.storm_open_threshold_per_second = 50  # per process
+```
+
+All thresholds are per process and individually configurable. Disable with one flag.
+
+**Measured overhead** (Apple Silicon, Ruby 4.0): 2.4µs/error with protection active and calm, 2.95µs in count-only mode, 0.2µs when disabled — against a 5µs budget. The check is a digest plus an atomic increment; there is no I/O on the hot path.
+</details>
+
 <details>
 <summary><strong>Breadcrumbs — Request Activity Trail</strong></summary>
 
@@ -580,6 +602,37 @@ end
 
 ---
 
+## FAQ
+
+**Does Rails Error Dashboard support a separate database for errors?**
+Yes. You can store errors in your app's existing database (shared) **or** in a dedicated, isolated database (separate). Set `config.use_separate_database = true` (or `USE_SEPARATE_ERROR_DB=true`) and point it at a separate connection — the engine routes all of its tables through `connects_to`, keeping error data fully isolated from your app data. Both modes are first-class and covered by the [Database Options guide](docs/guides/DATABASE_OPTIONS.md).
+
+**Which databases does it work with?**
+SQLite, PostgreSQL, and MySQL/Trilogy — in either shared or separate-database mode.
+
+**Is this a self-hosted alternative to Sentry?**
+Yes. It runs entirely inside your own Rails process — no external services, no SDK calling out, no per-event pricing. Error data never leaves your infrastructure.
+
+**Does it capture local variables like Sentry?**
+Yes — local **and** instance variables at the moment the exception is raised, via `TracePoint(:raise)`, with sensitive-data filtering and configurable limits. This is opt-in and a capability Sentry charges extra for.
+
+**Will a flood of errors take down my app?**
+No. Storm protection (a circuit breaker with adaptive sampling, **ON by default**) makes the gem degrade itself first during error floods — occurrence counts stay exact while it sheds the expensive work. Measured hot-path overhead is ~2.4µs/error.
+
+**Does it work with my background jobs?**
+Yes — it auto-detects and supports Sidekiq, SolidQueue, and GoodJob, and can log errors asynchronously through any of them.
+
+**Does it work with my authentication?**
+Yes — HTTP Basic Auth out of the box, or a custom `authenticate_with` lambda that integrates with Devise, Warden, or session-based auth.
+
+**Can it track more than one app?**
+Yes — multi-app support tracks errors from multiple Rails apps in one dashboard with per-app filtering.
+
+**What Rails and Ruby versions are supported?**
+Rails 7.0–8.1 and Ruby 3.2–4.0.
+
+---
+
 ## Documentation
 
 ### Getting Started

data/app/controllers/rails_error_dashboard/application_controller.rb

@@ -77,6 +77,11 @@ module RailsErrorDashboard
     def set_common_view_variables
       @applications = Application.ordered_by_name.pluck(:name, :id) rescue []
       @default_credentials_warning = RailsErrorDashboard.configuration.default_credentials? rescue false
+      # Only query when a before_action (e.g. ErrorsController#load_storm_banner)
+      # hasn't already loaded it this request — the error renderer runs after
+      # those callbacks, so reuse their result instead of querying a second time.
+      # Tracked by a flag rather than the value, since the common case is nil.
+      @storm_banner_event = Queries::StormHistory.banner_event unless @storm_banner_loaded
     end
   end
 end

data/app/controllers/rails_error_dashboard/errors_controller.rb

@@ -5,6 +5,7 @@ module RailsErrorDashboard
     before_action :authenticate_dashboard_user!
     before_action :set_application_context
     before_action :check_default_credentials
+    before_action :load_storm_banner
 
     FILTERABLE_PARAMS = %i[
       error_type
@@ -329,6 +330,12 @@ module RailsErrorDashboard
       @pagy, @releases = pagy(:offset, all_releases, limit: params[:per_page] || 25)
     end
 
+    def storms
+      result = Queries::StormHistory.call
+      @active_storm = result[:active]
+      @storm_events = result[:events]
+    end
+
     def user_impact
       days = days_param(default: 30)
       @days = days
@@ -477,9 +484,8 @@ module RailsErrorDashboard
     end
 
     def rack_attack_summary
-      unless RailsErrorDashboard.configuration.enable_rack_attack_tracking &&
-             RailsErrorDashboard.configuration.enable_breadcrumbs
-        flash[:alert] = "Rack Attack tracking is not enabled. Enable enable_rack_attack_tracking and enable_breadcrumbs in config/initializers/rails_error_dashboard.rb"
+      unless RailsErrorDashboard.configuration.enable_rack_attack_tracking
+        flash[:alert] = "Rack Attack tracking is not enabled. Set enable_rack_attack_tracking = true in config/initializers/rails_error_dashboard.rb"
         redirect_to errors_path(**app_context_params)
         return
       end
@@ -729,6 +735,11 @@ module RailsErrorDashboard
       @default_credentials_warning = RailsErrorDashboard.configuration.default_credentials?
     end
 
+    def load_storm_banner
+      @storm_banner_loaded = true
+      @storm_banner_event = Queries::StormHistory.banner_event
+    end
+
     def authenticate_dashboard_user!
       auth_lambda = RailsErrorDashboard.configuration.authenticate_with
 

data/app/jobs/rails_error_dashboard/rack_attack_flush_job.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  # Job: Persist buffered Rack::Attack event counts to the database.
+  #
+  # Two usage modes:
+  # 1. With a counts hash — dispatched by RackAttackTracker's periodic flush.
+  #    Zero I/O in the request path; all DB writes happen here.
+  # 2. Without arguments — scheduled periodic sweep that flushes the current
+  #    thread's buffer (useful as a cron safety net for low-traffic apps where
+  #    the flush interval may not be reached during a request).
+  #
+  # Example cron (via solid_queue or whenever):
+  #   every 5.minutes { RailsErrorDashboard::RackAttackFlushJob.perform_later }
+  class RackAttackFlushJob < ApplicationJob
+    queue_as :default
+
+    def perform(counts = nil)
+      return unless RailsErrorDashboard.configuration.enable_rack_attack_tracking
+
+      if counts
+        # Mode 1: Persist provided snapshot (dispatched from tracker flush)
+        Commands::FlushRackAttackEvents.call(counts: counts)
+      else
+        # Mode 2: Flush current thread's buffer (scheduled cron safety net).
+        # sync: true because we are already off the request path.
+        Services::RackAttackTracker.flush!(sync: true)
+      end
+    end
+  end
+end

data/app/jobs/rails_error_dashboard/retention_cleanup_job.rb

@@ -20,6 +20,12 @@ module RailsErrorDashboard
       return 0 if retention_days.blank?
 
       cutoff = retention_days.days.ago
+
+      # Rack Attack events live in their own table and expire independently of
+      # errors — clean them up BEFORE the early return below, which fires
+      # whenever no error logs happen to be expired.
+      cleanup_rack_attack_events(cutoff)
+
       expired_scope = ErrorLog.where("occurred_at < ?", cutoff)
       return 0 if expired_scope.none?
 
@@ -52,5 +58,29 @@ module RailsErrorDashboard
       RailsErrorDashboard::Logger.error("[RailsErrorDashboard] Retention cleanup failed: #{e.class} - #{e.message}")
       0
     end
+
+    private
+
+    # Expire aggregated Rack Attack event rows. Isolated in its own rescue so a
+    # failure here (e.g. table not yet migrated) never blocks error cleanup.
+    def cleanup_rack_attack_events(cutoff)
+      return unless RailsErrorDashboard.configuration.enable_rack_attack_tracking
+      return unless RackAttackEvent.table_exists?
+
+      deleted = 0
+      RackAttackEvent.where("period_hour < ?", cutoff).in_batches(of: 1000) do |batch|
+        deleted += batch.delete_all
+      end
+
+      if deleted > 0
+        RailsErrorDashboard::Logger.info(
+          "[RailsErrorDashboard] Retention cleanup: deleted #{deleted} rack attack events"
+        )
+      end
+    rescue => e
+      RailsErrorDashboard::Logger.debug(
+        "[RailsErrorDashboard] Rack attack retention cleanup failed: #{e.class} - #{e.message}"
+      )
+    end
   end
 end

data/app/jobs/rails_error_dashboard/storm_flush_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  # Persists storm-protection count snapshots (mirrors SwallowedExceptionFlushJob):
+  # the gate accumulates counts in memory with zero I/O, snapshots are handed
+  # to this job at most once per flush interval, and ALL DB writes happen here.
+  class StormFlushJob < ApplicationJob
+    queue_as :default
+
+    def perform(entries: [], overflow: 0, episode: nil)
+      entries = entries.map { |e| e.respond_to?(:stringify_keys) ? e.stringify_keys : e }
+      episode = episode.stringify_keys if episode.respond_to?(:stringify_keys)
+
+      Commands::FlushStormCounts.call(entries: entries, overflow: overflow, episode: episode)
+    rescue => e
+      Rails.logger.error("[RailsErrorDashboard] StormFlushJob failed: #{e.class} - #{e.message}")
+    end
+  end
+end

data/app/jobs/rails_error_dashboard/storm_notification_job.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  # Sends the SINGLE "error storm in progress" notification per storm episode.
+  #
+  # During a storm, per-error notifications are suppressed (500 Slack pings
+  # help nobody) — this one message replaces them. The gate guarantees at
+  # most one enqueue per episode; this job just delivers.
+  class StormNotificationJob < ApplicationJob
+    queue_as :default
+
+    # @param started_at [String] ISO8601 episode start
+    # @param state [String] breaker state at notification time ("shedding"/"open")
+    def perform(started_at:, state: "shedding")
+      config = RailsErrorDashboard.configuration
+      message = build_message(started_at, state, config)
+
+      if config.enable_slack_notifications && config.slack_webhook_url.present?
+        post_json(config.slack_webhook_url, { text: message })
+      end
+
+      if config.enable_discord_notifications && config.discord_webhook_url.present?
+        post_json(config.discord_webhook_url, { content: message })
+      end
+
+      if config.enable_webhook_notifications && config.webhook_urls.any?
+        payload = {
+          event: "error_storm_detected",
+          started_at: started_at,
+          state: state,
+          application: app_name(config)
+        }
+        config.webhook_urls.each { |url| post_json(url, payload) }
+      end
+    rescue => e
+      Rails.logger.error("[RailsErrorDashboard] StormNotificationJob failed: #{e.class} - #{e.message}")
+    end
+
+    private
+
+    def build_message(started_at, state, config)
+      mode = state == "open" ? "count-only mode (occurrences tallied, detail paused)" : "shedding mode (context sampling active)"
+      dashboard = (config.dashboard_base_url || "").chomp("/")
+      link = dashboard.present? ? " Dashboard: #{dashboard}/errors/storms" : ""
+
+      ":warning: Error storm detected in #{app_name(config)} at #{started_at}. " \
+        "Storm protection engaged — #{mode}. Per-error notifications are " \
+        "suppressed until the storm subsides; exact counts are preserved.#{link}"
+    end
+
+    def app_name(config)
+      config.application_name || ENV["APPLICATION_NAME"] ||
+        (defined?(Rails) && Rails.application.class.module_parent_name) || "Rails Application"
+    end
+
+    def post_json(url, payload)
+      if defined?(HTTParty)
+        HTTParty.post(url, body: payload.to_json,
+          headers: { "Content-Type" => "application/json" }, timeout: 10)
+      else
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+        request = Net::HTTP::Post.new(uri.path, { "Content-Type" => "application/json" })
+        request.body = payload.to_json
+        http.request(request)
+      end
+    rescue => e
+      Rails.logger.error("[RailsErrorDashboard] Storm notification post failed: #{e.message}")
+    end
+  end
+end

data/app/models/rails_error_dashboard/rack_attack_event.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  # Stores aggregated Rack::Attack throttle/blocklist/track events per hourly bucket.
+  #
+  # Rack::Attack events are NOT errors — a throttled request returns HTTP 429 without
+  # raising. They are therefore persisted independently of error_logs rather than as
+  # a side-effect of error capture (see issue #143).
+  #
+  # Rows are aggregated hourly by (rule, match_type, discriminator, path) so that a
+  # rate-limit flood collapses to a handful of rows instead of one INSERT per request.
+  class RackAttackEvent < ErrorLogsRecord
+    self.table_name = "rails_error_dashboard_rack_attack_events"
+
+    # Event types emitted by Rack::Attack (v5.0+)
+    MATCH_TYPES = %w[throttle blocklist track safelist].freeze
+
+    belongs_to :application, optional: true
+
+    validates :rule, presence: true
+    validates :match_type, presence: true
+    validates :period_hour, presence: true
+    validates :event_count, presence: true, numericality: { greater_than_or_equal_to: 0 }
+
+    scope :for_application, ->(app_id) { where(application_id: app_id) }
+    scope :since, ->(time) { where("period_hour >= ?", time) }
+    scope :recent, -> { order(period_hour: :desc) }
+    scope :throttles, -> { where(match_type: "throttle") }
+    scope :blocklists, -> { where(match_type: "blocklist") }
+
+    # Whether this event represents a hard block rather than a rate limit
+    def blocked?
+      match_type == "blocklist"
+    end
+  end
+end

data/app/models/rails_error_dashboard/storm_event.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  # One row per storm-protection episode (per process). Powers the dashboard
+  # banner and the storm history page. Counts are exact, not extrapolated.
+  # Inherits ErrorLogsRecord so separate-database routing applies.
+  class StormEvent < ErrorLogsRecord
+    self.table_name = "rails_error_dashboard_storm_events"
+
+    scope :active, -> { where(ended_at: nil) }
+    scope :recent_first, -> { order(started_at: :desc) }
+    scope :ended_within, ->(duration) { where.not(ended_at: nil).where(ended_at: duration.ago..) }
+
+    def active?
+      ended_at.nil?
+    end
+
+    def duration_seconds
+      return nil unless ended_at
+
+      (ended_at - started_at).round
+    end
+
+    # @return [Array<Hash>] top fingerprints by count, [] when absent/corrupt
+    def top_fingerprints_list
+      return [] if top_fingerprints.blank?
+
+      parsed = JSON.parse(top_fingerprints)
+      parsed.is_a?(Array) ? parsed : []
+    rescue JSON::ParserError
+      []
+    end
+  end
+end

data/app/views/layouts/rails_error_dashboard.html.erb

@@ -993,7 +993,7 @@ tr[data-red-row-href]:hover .sev-bar { opacity: 1 !important; }
             <% health_items << { path: job_health_summary_errors_path(nav_params), icon: 'bi-gear-wide-connected', label: 'Jobs' } %>
             <% health_items << { path: database_health_summary_errors_path(nav_params), icon: 'bi-database', label: 'Database' } %>
           <% end %>
-          <% if RailsErrorDashboard.configuration.enable_rack_attack_tracking && RailsErrorDashboard.configuration.enable_breadcrumbs %>
+          <% if RailsErrorDashboard.configuration.enable_rack_attack_tracking %>
             <% health_items << { path: rack_attack_summary_errors_path(nav_params), icon: 'bi-shield-exclamation', label: 'Rate Limits' } %>
           <% end %>
           <% if RailsErrorDashboard.configuration.enable_actioncable_tracking && RailsErrorDashboard.configuration.enable_breadcrumbs %>
@@ -1036,6 +1036,9 @@ tr[data-red-row-href]:hover .sev-bar { opacity: 1 !important; }
           <% if RailsErrorDashboard.configuration.enable_diagnostic_dump %>
             <% diag_items << { path: diagnostic_dumps_errors_path(nav_params), icon: 'bi-clipboard-pulse', label: 'Diagnostics' } %>
           <% end %>
+          <% if RailsErrorDashboard.configuration.enable_storm_protection %>
+            <% diag_items << { path: storms_errors_path(nav_params), icon: 'bi-cloud-lightning-rain', label: 'Storms' } %>
+          <% end %>
 
           <% if diag_items.any? %>
             <div style="margin-bottom: var(--space-2);" id="navDiagSection">
@@ -1175,6 +1178,24 @@ tr[data-red-row-href]:hover .sev-bar { opacity: 1 !important; }
             </div>
             <script<%= " nonce=\"#{red_csp_nonce}\"".html_safe if red_csp_nonce %>>try { if (sessionStorage.getItem('red_dismiss_creds_warning') === '1') { document.getElementById('security-warning').style.display = 'none'; } } catch(e) {}</script>
           <% end %>
+          <% if defined?(@storm_banner_event) && @storm_banner_event %>
+            <% storm_active = @storm_banner_event.active? %>
+            <div id="storm-banner" class="alert <%= storm_active ? 'alert-danger' : 'alert-info' %>" style="display: flex; align-items: center; gap: 10px; margin-top: var(--space-2); margin-bottom: var(--space-4); border-left: 4px solid <%= storm_active ? 'var(--status-critical)' : 'var(--status-info)' %>;">
+              <i class="bi <%= storm_active ? 'bi-cloud-lightning-rain-fill' : 'bi-cloud-check' %>" style="font-size: 18px; flex-shrink: 0;"></i>
+              <div style="flex: 1;">
+                <% if storm_active %>
+                  <strong>Error storm in progress</strong> (since <%= @storm_banner_event.started_at.strftime("%H:%M %Z") %>) —
+                  storm protection engaged. Occurrences are being counted exactly;
+                  <%= @storm_banner_event.reached_open ? "detail capture is paused (count-only mode)" : "context capture is sampled" %>.
+                <% else %>
+                  <strong>Storm protection engaged recently</strong> (ended <%= @storm_banner_event.ended_at.strftime("%H:%M %Z") %>) —
+                  <%= number_with_delimiter(@storm_banner_event.events_counted_only.to_i + @storm_banner_event.events_overflow.to_i) %> occurrences
+                  were recorded as exact counts with sampled detail.
+                <% end %>
+                <a href="<%= storms_errors_path %>" style="margin-left: 4px;">View storm history</a>
+              </div>
+            </div>
+          <% end %>
           <%= yield %>
         </main>
 

data/app/views/rails_error_dashboard/errors/rack_attack_summary.html.erb

@@ -25,16 +25,16 @@
       <i class="bi bi-shield-check display-1 text-success mb-3"></i>
       <div class="red-empty-state-title">No Rate Limit Events Found</div>
       <p class="text-muted">
-        No Rack Attack throttle, blocklist, or track events were detected in error breadcrumbs over the last <%= @days %> days.
+        No Rack Attack throttle, blocklist, or track events were recorded over the last <%= @days %> days.
       </p>
       <div class="card mx-auto" style="max-width: 500px;">
         <div class="card-body text-start">
           <h6>How Rack Attack tracking works:</h6>
           <ul class="mb-0">
-            <li>Breadcrumbs must be enabled (<code>enable_breadcrumbs = true</code>)</li>
             <li>Rack Attack tracking must be enabled (<code>enable_rack_attack_tracking = true</code>)</li>
             <li>Rack Attack must be installed and configured in your app</li>
-            <li>Throttle, blocklist, and track events are captured as breadcrumbs during requests that produce errors</li>
+            <li>Throttle, blocklist, and track events are recorded whenever a rule matches — no error required</li>
+            <li>Events are buffered and written every <%= RailsErrorDashboard.configuration.rack_attack_flush_interval %>s, so allow a short delay before they appear</li>
           </ul>
         </div>
       </div>
@@ -86,7 +86,6 @@
                 <th width="80">Count</th>
                 <th width="80">IPs</th>
                 <th>Top Path</th>
-                <th width="80">Errors</th>
                 <th width="140">Last Seen</th>
               </tr>
             </thead>
@@ -105,7 +104,6 @@
                   <td><strong><%= event[:count] %></strong></td>
                   <td><%= event[:unique_ips] %></td>
                   <td><code><%= event[:top_path] %></code></td>
-                  <td><%= event[:error_count] %></td>
                   <td><%= local_time_ago(event[:last_seen]) %></td>
                 </tr>
               <% end %>
@@ -116,7 +114,7 @@
       <div class="card-footer border-top d-flex justify-content-between align-items-center">
         <div>
           <small class="text-muted">
-            <i class="bi bi-lightbulb text-warning"></i> Rate limit events are captured when they coincide with errors. High counts may indicate abuse or misconfigured rules.
+            <i class="bi bi-lightbulb text-warning"></i> High counts may indicate abuse or misconfigured rules.
           </small>
           <small class="ms-3">
             <a href="https://github.com/rack/rack-attack" target="_blank" rel="noopener" class="text-decoration-none">

data/app/views/rails_error_dashboard/errors/storms.html.erb

@@ -0,0 +1,91 @@
+<% content_for :page_title, "Storm History" %>
+
+<div>
+  <div class="d-flex justify-content-between align-items-center mb-4">
+    <h1 style="font-size: 20px; font-weight: 700; margin: 0;">
+      <i class="bi bi-cloud-lightning-rain me-2"></i>
+      Storm History
+    </h1>
+  </div>
+
+  <p class="text-muted" style="font-size: 13px; margin-bottom: var(--space-4);">
+    When the error rate spikes (a bad deploy, a dependency outage), storm protection
+    limits the gem's own database writes so it never amplifies the incident.
+    Occurrences are always counted exactly — only per-event detail is sampled.
+    Thresholds are configurable per process via <code>storm_*</code> options.
+  </p>
+
+  <% if @active_storm %>
+    <div class="alert alert-danger" style="border-left: 4px solid var(--status-critical);">
+      <i class="bi bi-cloud-lightning-rain-fill me-1"></i>
+      <strong>Storm in progress</strong> since <%= @active_storm.started_at.strftime("%Y-%m-%d %H:%M %Z") %> —
+      peak rate <%= number_with_delimiter(@active_storm.peak_rate_per_minute) %>/min.
+    </div>
+  <% end %>
+
+  <% if @storm_events.empty? %>
+    <div class="red-empty-state">
+      <i class="bi bi-cloud-sun display-1 text-muted mb-3"></i>
+      <div class="red-empty-state-title">No Storms Recorded</div>
+      <p class="text-muted">
+        Storm protection is standing by. If an error flood ever hits this app,
+        episodes will appear here with exact counts of what was shed.
+      </p>
+    </div>
+  <% else %>
+    <div class="card">
+      <div class="card-body" style="padding: 0;">
+        <table class="table" style="margin: 0;">
+          <thead>
+            <tr>
+              <th>Started</th>
+              <th>Duration</th>
+              <th>Peak Rate</th>
+              <th>Mode</th>
+              <th class="text-end">Counted (exact)</th>
+              <th class="text-end">Overflow</th>
+              <th>Top Errors</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @storm_events.each do |event| %>
+              <tr>
+                <td style="white-space: nowrap;">
+                  <%= event.started_at.strftime("%Y-%m-%d %H:%M") %>
+                  <% if event.active? %>
+                    <span class="badge bg-danger ms-1">active</span>
+                  <% end %>
+                </td>
+                <td>
+                  <% if event.duration_seconds %>
+                    <%= ActiveSupport::Duration.build(event.duration_seconds).inspect %>
+                  <% else %>
+                    &mdash;
+                  <% end %>
+                </td>
+                <td><%= number_with_delimiter(event.peak_rate_per_minute) %>/min</td>
+                <td>
+                  <% if event.reached_open %>
+                    <span class="badge bg-danger">count-only</span>
+                  <% else %>
+                    <span class="badge bg-warning text-dark">shedding</span>
+                  <% end %>
+                </td>
+                <td class="text-end"><%= number_with_delimiter(event.events_counted_only) %></td>
+                <td class="text-end"><%= number_with_delimiter(event.events_overflow) %></td>
+                <td style="max-width: 320px;">
+                  <% event.top_fingerprints_list.first(3).each do |fp| %>
+                    <div style="font-size: 12px; font-family: var(--font-mono); overflow: hidden; text-overflow: ellipsis; white-space: nowrap;" title="<%= fp["message"] %>">
+                      <strong><%= fp["class"] %></strong>
+                      <span class="text-muted">&times;<%= number_with_delimiter(fp["count"]) %></span>
+                    </div>
+                  <% end %>
+                </td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    </div>
+  <% end %>
+</div>

data/config/routes.rb

@@ -40,6 +40,7 @@ RailsErrorDashboard::Engine.routes.draw do
       get :activestorage_health_summary
       get :llm_health_summary
       get :releases
+      get :storms
       get :user_impact
       get :diagnostic_dumps
       post :create_diagnostic_dump

data/db/migrate/20260306000002_add_instance_variables_to_error_logs.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 class AddInstanceVariablesToErrorLogs < ActiveRecord::Migration[7.0]
-  def change
+  def up
+    return if column_exists?(:rails_error_dashboard_error_logs, :instance_variables)
+
     add_column :rails_error_dashboard_error_logs, :instance_variables, :text
   end
+
+  def down
+    remove_column :rails_error_dashboard_error_logs, :instance_variables if column_exists?(:rails_error_dashboard_error_logs, :instance_variables)
+  end
 end

data/db/migrate/20260306000003_create_rails_error_dashboard_swallowed_exceptions.rb

@@ -2,6 +2,10 @@
 
 class CreateRailsErrorDashboardSwallowedExceptions < ActiveRecord::Migration[7.0]
   def change
+    # Guard against the squashed schema migration having already created this
+    # table — without it, every later migration is silently cancelled.
+    return if table_exists?(:rails_error_dashboard_swallowed_exceptions)
+
     create_table :rails_error_dashboard_swallowed_exceptions do |t|
       t.string   :exception_class,  null: false, limit: 250
       t.string   :raise_location,   null: false, limit: 250

data/db/migrate/20260307000001_create_rails_error_dashboard_diagnostic_dumps.rb

@@ -2,6 +2,10 @@
 
 class CreateRailsErrorDashboardDiagnosticDumps < ActiveRecord::Migration[7.0]
   def change
+    # Guard against the squashed schema migration having already created this
+    # table — without it, every later migration is silently cancelled.
+    return if table_exists?(:rails_error_dashboard_diagnostic_dumps)
+
     create_table :rails_error_dashboard_diagnostic_dumps do |t|
       t.references :application, null: false,
         foreign_key: { to_table: :rails_error_dashboard_applications }

data/db/migrate/20260613000001_create_storm_events.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Storm protection honesty layer: one row per storm episode, powering the
+# dashboard banner ("storm detected, counts recorded, detail sampled") and
+# the storm history page. Small table — a few rows per incident.
+class CreateStormEvents < ActiveRecord::Migration[7.0]
+  def change
+    return if table_exists?(:rails_error_dashboard_storm_events)
+
+    create_table :rails_error_dashboard_storm_events do |t|
+      t.datetime :started_at, null: false
+      t.datetime :ended_at                    # NULL while the storm is active
+      t.integer :peak_rate_per_minute, default: 0
+      t.boolean :reached_open, default: false # true if count-only mode engaged
+      t.bigint :events_total, default: 0      # count-only total = counted_only + overflow (excludes :lite/:full rows)
+      t.bigint :events_counted_only, default: 0 # counted in memory, no rows
+      t.bigint :events_overflow, default: 0   # beyond the bounded map — exact total, anonymous identity
+      t.integer :fingerprints_affected, default: 0
+      t.text :top_fingerprints                # JSON: top 5 by count [{class, message, count}]
+      t.timestamps
+    end
+
+    add_index :rails_error_dashboard_storm_events, :ended_at,
+              name: "index_red_storm_events_on_ended_at"
+    add_index :rails_error_dashboard_storm_events, :started_at,
+              name: "index_red_storm_events_on_started_at"
+  end
+end