rails_error_dashboard 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 532921b0ba2ccb40a532a66e5e3c7b1fcf17fc56e53cb5b0ed3772648644f0c0
-  data.tar.gz: 282169f161d90326aaebce5933521cd54c8bb373611e9002b447f114b6654204
+  metadata.gz: c51d8221b7ca00ce0f9242f98f3594fd86028a2c98c464fcac28aac34f6d2a3b
+  data.tar.gz: 597373253abc68befcf70edab809093c320740fca1a575bcc8cae7fd6ae7e3e5
 SHA512:
-  metadata.gz: 63c2ba5ef4319eaff8450837fec526135e37865ea0d2c72c30b7010ff6e86c03e49f728172d032bec6ad626f8dba39d00841300839fee9b8a493caa912669559
-  data.tar.gz: c84238b00e2f6959fd1e4ac5a1c9ff2d696a0d28379a102e99d761585caf4c24a4f6446f4d303d69c933e5135b31e7c3ef1d0a6b7464376e88ad25b14068c75a
+  metadata.gz: 2bcae54eb97ce19345f5ca8a92e515c7b44d9957afc985885bda168afddadc24b3640b7fc3dcdfbe5e80637564975be851d7aeb2d2be14fbdfb8b38bf769300c
+  data.tar.gz: f269598ef3e5c0b4a7761be4bb4ddeeef32f662dd18f6e75dca292f108804b8d73f4d95e0f30e86a550e51478ec66d43431bb722740caf7d0149f98addb9c042

data/README.md

@@ -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>
 

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
@@ -729,6 +736,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/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/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

@@ -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/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

data/lib/generators/rails_error_dashboard/install/templates/initializer.rb

@@ -518,6 +518,42 @@ RailsErrorDashboard.configure do |config|
   # No PII or request bodies in span attributes — just metadata + timing.
   # Safe to enable on production OTel pipelines.
 
+  # ============================================================================
+  # STORM PROTECTION (circuit breaker + adaptive sampling) — ON by default
+  # ============================================================================
+  #
+  # When the error rate spikes (bad deploy, 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 (context payloads, occurrence rows) is sampled under load.
+  #
+  # How it degrades, in order:
+  #   1. Per-fingerprint cap: past N/min, context is shed, then rows sampled
+  #   2. Global breaker: shedding (context off) → open (count-only mode)
+  #   3. Per-error notifications replaced by ONE "storm in progress" message
+  #   4. Counts reconciled onto error records every flush interval
+  #
+  # All thresholds are PER PROCESS (each Puma worker runs its own breaker).
+  #
+  # config.enable_storm_protection = true
+  # config.storm_fingerprint_full_per_minute = 30   # full-fidelity captures per fingerprint/min
+  # config.storm_occurrence_sample_keep_every = 10  # past the cap, keep every Nth occurrence
+  # config.storm_shedding_threshold_per_second = 10 # global rate entering shedding state
+  # config.storm_open_threshold_per_second = 50     # global rate opening the breaker (count-only)
+  # config.storm_cooldown_seconds = 60              # open → half-open probe delay
+  # config.storm_notification = true                # one notification per storm episode
+  #
+  # Always-on issue cap (a storm of NEW critical errors must not open
+  # hundreds of GitHub/Linear issues):
+  # config.auto_issue_rate_limit_count = 5
+  # config.auto_issue_rate_limit_window_minutes = 10
+  #
+  # Calm-weather context economy: an error seen 1000x/day doesn't need 1000
+  # breadcrumb trails. After N full-context captures per fingerprint per day,
+  # context is kept every Mth time (occurrence rows are unaffected):
+  # config.context_sampling_threshold_per_day = 25
+  # config.context_sampling_keep_every = 10
+
   # ============================================================================
   # ISSUE TRACKING (GitHub / GitLab / Codeberg / Linear)
   # ============================================================================

data/lib/rails_error_dashboard/commands/flush_storm_counts.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Commands
+    # Command: Reconcile counted-not-stored storm events onto ErrorLog rows
+    # and maintain the storm_events episode record.
+    #
+    # Runs in a background job (DB allowed). For each counted fingerprint:
+    #   1. Recompute the canonical error_hash from the stored identity parts
+    #      (the gate's key deliberately omits application_id — resolved here)
+    #   2. Unresolved match  → single UPDATE: occurrence_count += N
+    #   3. Resolved match    → reopen (mirrors FindOrIncrementError semantics)
+    #   4. No match          → create a minimal ErrorLog from the exemplar
+    #
+    # Counts are exact. Notifications are NOT dispatched from here — during a
+    # storm they're suppressed by design; the storm notification covers it.
+    class FlushStormCounts
+      def self.call(entries:, overflow: 0, episode: nil)
+        new(entries: entries, overflow: overflow, episode: episode).call
+      end
+
+      def initialize(entries:, overflow: 0, episode: nil)
+        @entries = Array(entries)
+        @overflow = overflow.to_i
+        @episode = episode
+      end
+
+      def call
+        application = resolve_application
+        counted = 0
+
+        @entries.each do |entry|
+          entry = entry.with_indifferent_access if entry.respond_to?(:with_indifferent_access)
+          counted += reconcile_entry(entry, application)
+        rescue => e
+          # A corrupt (non-Hash) entry must not abort the whole batch — and the
+          # log line itself must not assume `entry` is subscriptable (an Integer
+          # from a broken serializer would raise again here, escaping this rescue).
+          error_class = entry.is_a?(Hash) ? entry["error_class"] : entry.class
+          RailsErrorDashboard::Logger.error(
+            "[RailsErrorDashboard] Storm count reconcile failed for #{error_class}: #{e.class} - #{e.message}"
+          )
+        end
+
+        upsert_storm_event(counted)
+        { success: true, reconciled: counted, overflow: @overflow }
+      rescue => e
+        RailsErrorDashboard::Logger.error(
+          "[RailsErrorDashboard] FlushStormCounts failed: #{e.class} - #{e.message}"
+        )
+        { success: false, error: "#{e.class}: #{e.message}" }
+      end
+
+      private
+
+      def reconcile_entry(entry, application)
+        count = entry["count"].to_i
+        return 0 if count <= 0
+
+        error_hash = canonical_hash(entry, application)
+        last_seen = parse_time(entry["last_seen_at"]) || Time.current
+
+        # Priority 1: unresolved match — one UPDATE, no row instantiation
+        updated = ErrorLog.unresolved
+          .where(error_hash: error_hash, application_id: application.id)
+          .update_all([ "occurrence_count = occurrence_count + ?, last_seen_at = ?", count, last_seen ])
+        return count if updated.positive?
+
+        # Priority 2: resolved/wont_fix match — reopen, mirroring
+        # FindOrIncrementError so storm recurrences don't stay buried
+        resolved = ErrorLog
+          .where(error_hash: error_hash, application_id: application.id)
+          .where(status: %w[resolved wont_fix])
+          .order(last_seen_at: :desc)
+          .first
+        if resolved
+          attrs = {
+            resolved: false,
+            status: "new",
+            resolved_at: nil,
+            occurrence_count: resolved.occurrence_count + count,
+            last_seen_at: last_seen
+          }
+          attrs[:reopened_at] = Time.current if ErrorLog.column_names.include?("reopened_at")
+          resolved.update!(attrs)
+          return count
+        end
+
+        # Priority 3: first seen during count-only mode — minimal ErrorLog
+        # from the exemplar (no backtrace/context was captured; the next
+        # occurrence after the storm fills in detail via the normal path)
+        ErrorLog.create!(
+          application_id: application.id,
+          error_type: entry["error_class"],
+          message: entry["message"],
+          backtrace: entry["first_app_frame"],
+          controller_name: entry["controller_name"],
+          action_name: entry["action_name"],
+          occurred_at: parse_time(entry["first_seen_at"]) || Time.current,
+          last_seen_at: last_seen,
+          occurrence_count: count,
+          error_hash: error_hash,
+          resolved: false
+        )
+        count
+      end
+
+      # Mirrors ErrorHashGenerator.call exactly: same fields, same order,
+      # same normalization — so counts land on the same ErrorLog the full
+      # capture path would have used.
+      def canonical_hash(entry, application)
+        return entry["custom_hash"] if entry["custom_hash"].present?
+
+        digest_input = [
+          entry["error_class"],
+          Services::ErrorHashGenerator.normalize_message(entry["message"]),
+          entry["first_app_frame"],
+          entry["controller_name"],
+          entry["action_name"],
+          application.id.to_s
+        ].compact.join("|")
+
+        Digest::SHA256.hexdigest(digest_input)[0..15]
+      end
+
+      def resolve_application
+        # Same chain LogError uses — app name is process-global
+        app_name = RailsErrorDashboard.configuration.application_name ||
+                   ENV["APPLICATION_NAME"] ||
+                   (defined?(Rails) && Rails.application.class.module_parent_name) ||
+                   "Rails Application"
+        Application.find_or_create_by_name(app_name)
+      end
+
+      def upsert_storm_event(counted)
+        return unless @episode.is_a?(Hash)
+        return unless StormEvent.table_exists?
+
+        started_at = parse_time(@episode["started_at"])
+        return unless started_at
+
+        event = StormEvent.active.recent_first.first || StormEvent.create!(started_at: started_at)
+
+        event.events_counted_only = event.events_counted_only.to_i + counted
+        event.events_overflow = event.events_overflow.to_i + @overflow
+        # events_total is the count-only total: in-map reconciled + overflow.
+        # It deliberately excludes :lite/:full admissions (those became real
+        # ErrorLog rows on the hot path and are never counted here), so it is
+        # always events_counted_only + events_overflow. Derive it rather than
+        # accumulate so it can't drift from its two components.
+        event.events_total = event.events_counted_only.to_i + event.events_overflow.to_i
+        event.fingerprints_affected = [ event.fingerprints_affected.to_i, @entries.size ].max
+        event.peak_rate_per_minute = [ event.peak_rate_per_minute.to_i, @episode["peak_rate_per_minute"].to_i ].max
+        event.reached_open ||= @episode["reached_open"] == true
+        event.top_fingerprints = top_fingerprints_json(event)
+        event.ended_at = parse_time(@episode["ended_at"]) if @episode["ended_at"]
+        event.save!
+      rescue => e
+        RailsErrorDashboard::Logger.error(
+          "[RailsErrorDashboard] Storm event upsert failed: #{e.class} - #{e.message}"
+        )
+      end
+
+      def top_fingerprints_json(event)
+        existing = event.top_fingerprints_list
+        fresh = @entries.map { |e|
+          e = e.with_indifferent_access if e.respond_to?(:with_indifferent_access)
+          { "class" => e["error_class"], "message" => e["message"].to_s[0, 120], "count" => e["count"].to_i }
+        }
+
+        merged = (existing + fresh)
+          .group_by { |f| [ f["class"], f["message"] ] }
+          .map { |_k, group| group.first.merge("count" => group.sum { |f| f["count"].to_i }) }
+
+        merged.sort_by { |f| -f["count"].to_i }.first(5).to_json
+      end
+
+      def parse_time(value)
+        return value if value.is_a?(Time) || value.is_a?(ActiveSupport::TimeWithZone)
+        return nil if value.blank?
+
+        Time.zone.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end