rails_error_dashboard 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 002c2e5d338c585425599802271a90c5bac425dc86867da1aa10a0c7a478d1e8
-  data.tar.gz: 077d7d7a7f957bee799cf39c96632532e3c74259e83310605c6068d57436aec3
+  metadata.gz: c51d8221b7ca00ce0f9242f98f3594fd86028a2c98c464fcac28aac34f6d2a3b
+  data.tar.gz: 597373253abc68befcf70edab809093c320740fca1a575bcc8cae7fd6ae7e3e5
 SHA512:
-  metadata.gz: 8e6ef9f87aae8c200e997bf761184eb37c86d0637dfdd383fd6cc003f3c3b9fa30b7906fbaf6377670d932a60da5a9046202d4a48ab63264ce916c861ac20b91
-  data.tar.gz: 67858acc12ad29cb412b0c049b776b7193c9ce8d45febfa4bc23e079a1afd7ff64a2a85bd81516c999cc57861631ed3f89ea62bc36544370811e8cff858c8678
+  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>
 
@@ -233,7 +255,7 @@ Payload contract matches the `LlmCallEvent` value object — see [`docs/LLM_OBSE
 </details>
 
 <details>
-<summary><strong>Issue Tracking — GitHub, GitLab, Codeberg</strong></summary>
+<summary><strong>Issue Tracking — GitHub, GitLab, Codeberg, Linear</strong></summary>
 
 One switch connects errors to your issue tracker. Platform becomes the source of truth — status, assignees, labels, and comments are mirrored live in the dashboard.
 
@@ -250,6 +272,17 @@ config.issue_tracker_token = ENV["RED_BOT_TOKEN"]
 # That's it — provider and repo auto-detected from git_repository_url
 ```
 
+Linear works too — it's not a git forge, so set the provider and team key explicitly:
+
+```ruby
+config.enable_issue_tracking = true
+config.issue_tracker_provider = :linear
+config.issue_tracker_repo = "ENG"  # Linear team key (issues land as ENG-123)
+config.issue_tracker_token = ENV["RED_BOT_TOKEN"]  # lin_api_... personal API key
+```
+
+Closing maps to the team's first `completed` workflow state, reopening to `unstarted`/`backlog`. Two-way sync uses Linear webhooks (`Linear-Signature` HMAC verification).
+
 [Complete documentation →](docs/guides/CONFIGURATION.md)
 </details>
 

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/controllers/rails_error_dashboard/webhooks_controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module RailsErrorDashboard
-  # Receives webhooks from GitHub/GitLab/Codeberg for two-way issue sync.
+  # Receives webhooks from GitHub/GitLab/Codeberg/Linear for two-way issue sync.
   #
   # When an issue is closed/reopened on the platform, the corresponding
   # error in the dashboard is resolved/reopened to match.
@@ -10,6 +10,7 @@ module RailsErrorDashboard
   # - GitHub:   X-Hub-Signature-256 (HMAC-SHA256)
   # - GitLab:   X-Gitlab-Token (shared secret)
   # - Codeberg: X-Gitea-Signature (HMAC-SHA256)
+  # - Linear:   Linear-Signature (HMAC-SHA256)
   class WebhooksController < ActionController::Base
     skip_before_action :verify_authenticity_token
 
@@ -29,6 +30,8 @@ module RailsErrorDashboard
         handle_gitlab(payload)
       when "codeberg"
         handle_codeberg(payload)
+      when "linear"
+        handle_linear(payload)
       else
         head :not_found
         return
@@ -69,6 +72,8 @@ module RailsErrorDashboard
         verify_gitlab_token(secret)
       when "codeberg"
         verify_codeberg_signature(body, secret)
+      when "linear"
+        verify_linear_signature(body, secret)
       else
         false
       end
@@ -99,6 +104,14 @@ module RailsErrorDashboard
       ActiveSupport::SecurityUtils.secure_compare(expected, signature)
     end
 
+    def verify_linear_signature(body, secret)
+      signature = request.headers["Linear-Signature"]
+      return false unless signature
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
+      ActiveSupport::SecurityUtils.secure_compare(expected, signature)
+    end
+
     def parse_payload
       JSON.parse(request.body.read)
     rescue JSON::ParserError
@@ -162,6 +175,27 @@ module RailsErrorDashboard
       end
     end
 
+    # Linear: Issue webhook fires with action create/update/remove. State changes
+    # arrive as updates with the old stateId in updatedFrom. Linear has no
+    # open/closed binary — completed/canceled state types map to resolved.
+    def handle_linear(payload)
+      return unless payload["type"] == "Issue" && payload["action"] == "update"
+      return unless payload["updatedFrom"]&.key?("stateId")
+
+      issue_number = payload.dig("data", "number")
+      return unless issue_number
+
+      error = find_error_by_issue(issue_number, "linear")
+      return unless error
+
+      state_type = payload.dig("data", "state", "type")
+      if state_type.in?(%w[completed canceled])
+        resolve_error(error, "Completed on Linear by #{payload.dig("actor", "name")}")
+      elsif state_type.in?(%w[triage backlog unstarted started])
+        reopen_error(error)
+      end
+    end
+
     def find_error_by_issue(issue_number, provider)
       ErrorLog.find_by(
         external_issue_number: issue_number,

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/_issue_section.html.erb

@@ -18,6 +18,7 @@
                    when "github" then "bi-github"
                    when "gitlab" then "bi-gitlab"
                    when "codeberg" then "bi-git"
+                   when "linear" then "bi-kanban"
                    else "bi-link-45deg"
                    end %>
         <% issue = @platform_issue %>

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

@@ -519,7 +519,43 @@ RailsErrorDashboard.configure do |config|
   # Safe to enable on production OTel pipelines.
 
   # ============================================================================
-  # ISSUE TRACKING (GitHub / GitLab / Codeberg)
+  # 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)
   # ============================================================================
   #
   # One switch enables everything: issue creation, auto-create on first
@@ -534,7 +570,7 @@ RailsErrorDashboard.configure do |config|
   #   - Priority → labels from platform (with colors)
   #   - Snooze and Mute remain (no platform equivalent)
   #
-  # Setup:
+  # Setup (GitHub/GitLab/Codeberg):
   #   1. Create a RED bot account on GitHub/GitLab/Codeberg
   #   2. Generate a token and set RED_BOT_TOKEN env var
   #   3. Set git_repository_url above (already used for source code linking)
@@ -543,6 +579,17 @@ RailsErrorDashboard.configure do |config|
   # config.enable_issue_tracking = true
   # config.issue_tracker_token = ENV["RED_BOT_TOKEN"]
   #
+  # Setup (Linear):
+  #   Linear is not a git forge, so it cannot be auto-detected from
+  #   git_repository_url — set provider and team key explicitly. Issues are
+  #   created in the team matching the key (e.g. "ENG" for ENG-123 issues).
+  #   Generate a personal API key under Settings > Security & access.
+  #
+  # config.enable_issue_tracking = true
+  # config.issue_tracker_provider = :linear
+  # config.issue_tracker_repo = "ENG"                              # Linear team key
+  # config.issue_tracker_token = ENV["RED_BOT_TOKEN"]              # lin_api_... key
+  #
   # Optional overrides:
   # config.issue_tracker_labels = ["bug"]                          # Labels added to new issues
   # config.issue_tracker_auto_create_severities = [:critical, :high]  # Auto-create threshold

data/lib/rails_error_dashboard/commands/create_issue.rb

@@ -2,7 +2,7 @@
 
 module RailsErrorDashboard
   module Commands
-    # Command: Create an issue on the configured issue tracker (GitHub/GitLab/Codeberg)
+    # Command: Create an issue on the configured issue tracker (GitHub/GitLab/Codeberg/Linear)
     #
     # Creates the issue via the provider API, then stores the issue URL, number,
     # and provider on the error record for linking.