error_radar 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 106881790c16306716c7588f317da722c0e589db0a0a2bbb6e7ad838c9a8d118
-  data.tar.gz: d4c9ccf1363b88637dc625418daf8553e15aad0796f42f79aadc6eafb3a4f554
+  metadata.gz: 57b3fa6a7576ae08baeb699b180048363846c84ecbb489fc93e16ea537939898
+  data.tar.gz: 67008613bd52755dad89b7ed1abbc9a86eb92c138f95cae8005f5272e8336594
 SHA512:
-  metadata.gz: c880963d54ef38274dbc226b970f848f7a9ced038c6d88ababffe1b3eb71ef2d8490695a0a256775a500e707a72b9af2a017a066e8af1f66b17ab842a18ac726
-  data.tar.gz: ba612e7cc8a547cd1bf7ffb8704347636bccc7f763fba3a73fbfe1919b86573421873b61c88f6c8b44da0ed661cf8cf73d4da62a54998828dfe1a767642580ad
+  metadata.gz: 2882f7be2a07a38bdafd4b44c8251774a470f37d44fcd3dc4403046cd2998eb1077ac576c97cd8aed6a43ab4a86153440598bafa5a6a47576f06bbc137a2528d
+  data.tar.gz: 8717757580e628dc988422df68c3a806bd7d9727f297439b5e7303cc049a48371f37035442dbfd12f7789cb8b480221b093720dda965f6ebeffc2c75ef3bcb57

data/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.7.0] - 2026-07-03
+
+### Added
+- **Occurrence history**: every individual error hit can now be stored in a
+  separate `error_radar_occurrences` table. Enable with
+  `config.track_occurrences = true` after running the upgrade migration:
+  `bin/rails generate error_radar:upgrade_v060 && bin/rails db:migrate`.
+- **`ErrorRadar::ErrorOccurrence` model**: columns `occurred_at`, `context`,
+  `backtrace`, `http_status`, `request_url`. Belongs to `ErrorLog` via
+  `error_log_id`. Indexed on `(error_log_id, occurred_at)` for fast retrieval.
+- **`config.max_occurrences_per_error`** (default: 200): automatically prunes
+  the oldest occurrences for a given error on each new hit so the table stays
+  bounded without manual cleanup.
+- **Occurrences panel on error detail page**: shows the 20 most recent
+  occurrences with timestamp, HTTP status badge, request URL, and expandable
+  "Context" / "Stack" toggles. Paginated at 20 per page.
+- **`GET /api/errors/:id`** now includes `recent_occurrences` (last 10 hits
+  with `occurred_at`, `http_status`, `request_url`, `context`) when
+  `track_occurrences` is enabled.
+- **`error_radar:upgrade_v060` generator**: generates the migration that creates
+  `error_radar_occurrences`.
+- **`ErrorLog#occurrences`** association: `has_many :occurrences, dependent: :delete_all`
+  so destroying an error log also removes its occurrence history.
+
+### Notes
+- `track_occurrences` defaults to `false` to avoid unexpected writes before the
+  migration is run. Set it to `true` after the migration has been applied.
+- Occurrences are recorded via `ErrorLog.record`, which is called by both the
+  synchronous capture path and `CaptureJob` (async path) — no extra
+  configuration needed once enabled.
+
+## [0.6.0] - 2026-07-03
+
+### Added
+- **Async capture** via ActiveJob: set `config.async_capture = true` to enqueue
+  error writes through `CaptureJob` so exceptions don't block the request/job
+  thread. Falls back to synchronous capture if ActiveJob is unavailable.
+  Configure the queue with `config.capture_job_queue` (default `:default`).
+- **Age-based retention**: set `config.retention_days` to automatically prune
+  resolved/ignored records older than N days.
+- **Count-based retention**: set `config.max_records` to cap the table size;
+  oldest resolved/ignored records are deleted first when the limit is exceeded.
+- **`ErrorRadar::Cleanup.run`**: underlying cleanup logic, callable from Ruby or
+  Rake. Supports `older_than_days:` override and `dry_run: true` for previewing
+  without deleting.
+- **Rake tasks**:
+  - `rake error_radar:cleanup` — apply `retention_days` + `max_records`
+  - `rake error_radar:cleanup:dry_run` — preview without deleting
+  - `rake error_radar:cleanup:older_than` — one-off: `DAYS=30 rake …`
+  - `rake error_radar:stats` — print table summary (total, by status, oldest)
+- **Dashboard maintenance panel**: data summary (total / purgeable / open),
+  oldest record date, and an inline "Purge / Dry run" form with adjustable days.
+- **`POST /maintenance/purge`** endpoint: called by the dashboard's Purge button;
+  accepts `days` and `dry_run` params, returns JSON `{ deleted:, dry_run: }`.
+- **Dashboard stat query optimization**: 5 separate COUNT queries replaced by one
+  `group(:status).count` query.
+
+### Notes
+- `async_capture` is `false` by default to avoid surprising behaviour for apps
+  that do not have a queue adapter configured.
+- Cleanup only touches `resolved` and `ignored` records — open/in-progress
+  records are never auto-deleted.
+
 ## [0.5.0] - 2026-07-03
 
 ### Added

data/app/controllers/error_radar/api/errors_controller.rb

@@ -99,6 +99,22 @@ module ErrorRadar
             context:         log.context,
             backtrace:       log.backtrace
           )
+
+          if ErrorRadar.config.track_occurrences
+            begin
+              data[:recent_occurrences] = log.occurrences.recent.limit(10).map do |occ|
+                {
+                  id:           occ.id,
+                  occurred_at:  occ.occurred_at&.iso8601,
+                  http_status:  occ.http_status,
+                  request_url:  occ.request_url,
+                  context:      occ.context
+                }
+              end
+            rescue ActiveRecord::StatementInvalid
+              data[:recent_occurrences] = []
+            end
+          end
         end
 
         if log.class.column_names.include?('github_issue_url')

data/app/controllers/error_radar/dashboard_controller.rb

@@ -10,13 +10,18 @@ module ErrorRadar
     SEVERITY_ORDER = { 'critical' => 0, 'error' => 1, 'warning' => 2, 'info' => 3 }.freeze
 
     def index
-      @total          = ErrorLog.count
-      @open_count     = ErrorLog.status_open.count
-      @in_progress    = ErrorLog.status_in_progress.count
-      @resolved_count = ErrorLog.status_resolved.count
-      @ignored_count  = ErrorLog.status_ignored.count
+      counts_by_status = ErrorLog.group(:status).count
+      # statuses returns {"open"=>0, "in_progress"=>1, "resolved"=>2, "ignored"=>3}
+      inv = ErrorLog.statuses.invert
+      @open_count     = counts_by_status[ErrorLog.statuses['open']] || 0
+      @in_progress    = counts_by_status[ErrorLog.statuses['in_progress']] || 0
+      @resolved_count = counts_by_status[ErrorLog.statuses['resolved']] || 0
+      @ignored_count  = counts_by_status[ErrorLog.statuses['ignored']] || 0
+      @total          = counts_by_status.values.sum
       @unresolved     = @open_count + @in_progress
 
+      @oldest_record  = ErrorLog.minimum(:first_seen_at)
+
       @by_category = ErrorLog.unresolved.group(:category).count
       @by_severity = ErrorLog.unresolved.group(:severity).count
 
@@ -46,6 +51,28 @@ module ErrorRadar
       @external_links = build_external_links
     end
 
+    def purge
+      days    = params[:days].presence&.to_i
+      dry_run = params[:dry_run] == '1'
+
+      result = ErrorRadar::Cleanup.run(
+        older_than_days: (days if days&.positive?),
+        dry_run: dry_run
+      )
+
+      respond_to do |format|
+        format.json { render json: result }
+        format.html do
+          msg = if dry_run
+                  "Dry run: would delete #{result[:deleted]} record(s)."
+                else
+                  "Purged #{result[:deleted]} record(s)."
+                end
+          redirect_to root_path, notice: msg
+        end
+      end
+    end
+
     private
 
     def build_external_links

data/app/controllers/error_radar/errors_controller.rb

@@ -22,7 +22,23 @@ module ErrorRadar
       @pages        = pagination_pages(@page, @total_pages)
     end
 
-    def show; end
+    def show
+      @occurrences = []
+      return unless ErrorRadar.config.track_occurrences
+
+      begin
+        @occ_page       = [params[:occ_page].to_i, 1].max
+        occ_per_page    = 20
+        @occ_total      = @error.occurrences.count
+        @occ_total_pages = [(@occ_total.to_f / occ_per_page).ceil, 1].max
+        @occ_page       = [@occ_page, @occ_total_pages].min
+        @occurrences    = @error.occurrences.recent
+                                .limit(occ_per_page)
+                                .offset((@occ_page - 1) * occ_per_page)
+      rescue ActiveRecord::StatementInvalid
+        @occurrences = []
+      end
+    end
 
     def update_status
       new_status = params[:status].to_s

data/app/models/error_radar/error_log.rb

@@ -16,6 +16,10 @@ module ErrorRadar
 
     enum status: { open: 0, in_progress: 1, resolved: 2, ignored: 3 }, _prefix: :status
 
+    has_many :occurrences, class_name: 'ErrorRadar::ErrorOccurrence',
+                           foreign_key: :error_log_id,
+                           dependent: :delete_all
+
     validates :fingerprint, presence: true, uniqueness: true
     validates :first_seen_at, :last_seen_at, presence: true
 
@@ -60,6 +64,17 @@ module ErrorRadar
       log.last_seen_at = now
       log.save!
       log.instance_variable_set(:@new_fingerprint, new_fingerprint)
+
+      if ErrorRadar.config.track_occurrences
+        ErrorRadar::ErrorOccurrence.record_for(
+          log,
+          context:     context,
+          backtrace:   backtrace,
+          http_status: http_status,
+          request_url: request_url
+        )
+      end
+
       log
     rescue StandardError => e
       ErrorRadar::Tracking.warn_internal("ErrorLog.record failed: #{e.class}: #{e.message}")

data/app/models/error_radar/error_occurrence.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  # One row per individual error hit. Linked to an ErrorLog (the deduplicated
+  # aggregate). Only recorded when config.track_occurrences is true and the
+  # upgrade_v060 migration has been run.
+  class ErrorOccurrence < ApplicationRecord
+    belongs_to :error_log
+
+    scope :recent, -> { order(occurred_at: :desc) }
+
+    def self.record_for(log, context: {}, backtrace: nil, http_status: nil, request_url: nil)
+      max = ErrorRadar.config.max_occurrences_per_error
+
+      create!(
+        error_log:   log,
+        occurred_at: Time.current,
+        context:     context.presence,
+        backtrace:   Array(backtrace).join("\n").presence,
+        http_status: http_status,
+        request_url: request_url
+      )
+
+      if max&.positive?
+        keep_ids = where(error_log_id: log.id).order(occurred_at: :desc).limit(max).pluck(:id)
+        where(error_log_id: log.id).where.not(id: keep_ids).delete_all if keep_ids.any?
+      end
+    rescue ActiveRecord::StatementInvalid
+      # Table not yet created — run: bin/rails generate error_radar:upgrade_v060 && bin/rails db:migrate
+    rescue StandardError => e
+      ErrorRadar::Tracking.warn_internal("ErrorOccurrence.record_for failed: #{e.class}: #{e.message}")
+    end
+
+    def context_pretty
+      return '{}' if context.blank?
+      JSON.pretty_generate(context.is_a?(Hash) ? context : JSON.parse(context.to_s))
+    rescue JSON::ParserError
+      context.to_s
+    end
+  end
+end

data/app/views/error_radar/dashboard/index.html.erb

@@ -101,6 +101,52 @@
   </div>
 </div>
 
+<div class="panel" style="margin-bottom:20px" id="maintenance-panel">
+  <h2>Maintenance &amp; Data Retention</h2>
+  <div style="display:grid;grid-template-columns:1fr 1fr 1fr 1fr;gap:12px;margin-bottom:16px">
+    <div style="background:#f9fafb;border-radius:8px;padding:12px;text-align:center">
+      <div style="font-size:22px;font-weight:700;color:#111827"><%= @total %></div>
+      <div style="font-size:11px;color:#6b7280">Total records</div>
+    </div>
+    <div style="background:#f9fafb;border-radius:8px;padding:12px;text-align:center">
+      <div style="font-size:22px;font-weight:700;color:#28a745"><%= @resolved_count + @ignored_count %></div>
+      <div style="font-size:11px;color:#6b7280">Resolved / Ignored (purgeable)</div>
+    </div>
+    <div style="background:#f9fafb;border-radius:8px;padding:12px;text-align:center">
+      <div style="font-size:22px;font-weight:700;color:#fd7e14"><%= @unresolved %></div>
+      <div style="font-size:11px;color:#6b7280">Open / In progress</div>
+    </div>
+    <div style="background:#f9fafb;border-radius:8px;padding:12px;text-align:center">
+      <div style="font-size:13px;font-weight:600;color:#111827">
+        <%= @oldest_record ? @oldest_record.strftime('%Y-%m-%d') : '—' %>
+      </div>
+      <div style="font-size:11px;color:#6b7280">Oldest record</div>
+    </div>
+  </div>
+  <div style="display:flex;align-items:center;gap:12px;flex-wrap:wrap">
+    <label style="font-size:13px;font-weight:500">Delete resolved/ignored older than</label>
+    <input id="purge-days" type="number" min="1" placeholder="days" value="90"
+           style="width:80px;padding:5px 8px;border:1px solid #d1d5db;border-radius:6px;font-size:13px">
+    <span style="font-size:13px;color:#6b7280">days</span>
+    <button onclick="doPurge(false)"
+            style="padding:6px 14px;background:#dc3545;color:#fff;border:none;border-radius:6px;font-size:13px;cursor:pointer">
+      Purge
+    </button>
+    <button onclick="doPurge(true)"
+            style="padding:6px 14px;background:#6c757d;color:#fff;border:none;border-radius:6px;font-size:13px;cursor:pointer">
+      Dry run
+    </button>
+    <span id="purge-result" style="font-size:13px;color:#16a34a"></span>
+  </div>
+  <% if ErrorRadar.config.retention_days || ErrorRadar.config.max_records %>
+    <div style="margin-top:10px;font-size:12px;color:#6b7280">
+      Config: retention_days=<strong><%= ErrorRadar.config.retention_days || '—' %></strong>,
+      max_records=<strong><%= ErrorRadar.config.max_records || '—' %></strong>
+      (applies automatically when you run <code>rake error_radar:cleanup</code>)
+    </div>
+  <% end %>
+</div>
+
 <div class="panel" style="margin-bottom:20px">
   <h2>Kanban — drag a card to change status</h2>
   <div class="kanban">
@@ -127,6 +173,28 @@
 </div>
 
 <script>
+  function doPurge(dryRun) {
+    var days = document.getElementById('purge-days').value;
+    var result = document.getElementById('purge-result');
+    var token = document.querySelector('meta[name="csrf-token"]').content;
+    result.textContent = 'Running…';
+    result.style.color = '#6b7280';
+    fetch('<%= maintenance_purge_path %>', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': token, 'Accept': 'application/json' },
+      body: JSON.stringify({ days: days, dry_run: dryRun ? '1' : '0' })
+    }).then(function(r) { return r.json(); })
+      .then(function(d) {
+        var label = dryRun ? 'Would delete' : 'Deleted';
+        result.textContent = label + ' ' + d.deleted + ' record(s).';
+        result.style.color = dryRun ? '#fd7e14' : '#16a34a';
+      })
+      .catch(function() {
+        result.textContent = 'Request failed.';
+        result.style.color = '#dc3545';
+      });
+  }
+
   (function () {
     var token = document.querySelector('meta[name="csrf-token"]').content;
 

data/app/views/error_radar/errors/show.html.erb

@@ -104,6 +104,97 @@
   </div>
 </div>
 
+<%# ── Occurrences History ── %>
+<% if ErrorRadar.config.track_occurrences %>
+  <div class="panel" style="margin-top:16px" id="occurrences-panel">
+    <div style="display:flex;justify-content:space-between;align-items:baseline;margin-bottom:12px">
+      <h2 style="margin:0">Occurrence History
+        <% if @occ_total.to_i > 0 %>
+          <span style="font-size:13px;font-weight:400;color:#6b7280">(<%= @occ_total %> total)</span>
+        <% end %>
+      </h2>
+    </div>
+
+    <% if @occurrences.empty? %>
+      <p style="font-size:13px;color:#9ca3af;margin:0">
+        <% if @occ_total.to_i == 0 %>
+          No occurrences recorded yet. New hits will appear here.
+        <% else %>
+          No occurrences on this page.
+        <% end %>
+      </p>
+    <% else %>
+      <table style="width:100%;border-collapse:collapse;font-size:13px">
+        <thead>
+          <tr style="border-bottom:2px solid #e5e7eb">
+            <th style="text-align:left;padding:6px 8px;color:#6b7280;width:170px">Time</th>
+            <th style="text-align:left;padding:6px 8px;color:#6b7280;width:70px">HTTP</th>
+            <th style="text-align:left;padding:6px 8px;color:#6b7280">Context / Request</th>
+            <th style="text-align:left;padding:6px 8px;color:#6b7280;width:80px">Backtrace</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @occurrences.each_with_index do |occ, i| %>
+            <tr style="border-bottom:1px solid #f3f4f6" class="occ-row">
+              <td style="padding:7px 8px;font-family:monospace;font-size:11px;white-space:nowrap">
+                <%= occ.occurred_at&.strftime('%Y-%m-%d %H:%M:%S') %>
+              </td>
+              <td style="padding:7px 8px">
+                <% if occ.http_status.present? %>
+                  <span class="badge" style="background:<%= occ.http_status.to_i >= 500 ? '#dc3545' : '#fd7e14' %>">
+                    <%= occ.http_status %>
+                  </span>
+                <% end %>
+              </td>
+              <td style="padding:7px 8px;max-width:400px">
+                <% if occ.request_url.present? %>
+                  <div style="font-size:11px;color:#6b7280;word-break:break-all;margin-bottom:4px"><%= occ.request_url.truncate(120) %></div>
+                <% end %>
+                <% unless (occ.context || {}).empty? %>
+                  <button onclick="toggleOcc('ctx-<%= i %>')"
+                          style="padding:2px 8px;font-size:11px;border:1px solid #d1d5db;border-radius:4px;background:#f9fafb;cursor:pointer">
+                    Context ▾
+                  </button>
+                  <div id="ctx-<%= i %>" style="display:none;margin-top:6px">
+                    <pre class="er-pre" style="max-height:200px;font-size:10px"><%= occ.context_pretty %></pre>
+                  </div>
+                <% end %>
+              </td>
+              <td style="padding:7px 8px">
+                <% if occ.backtrace.present? %>
+                  <button onclick="toggleOcc('bt-<%= i %>')"
+                          style="padding:2px 8px;font-size:11px;border:1px solid #d1d5db;border-radius:4px;background:#f9fafb;cursor:pointer">
+                    Stack ▾
+                  </button>
+                  <div id="bt-<%= i %>" style="display:none;position:absolute;z-index:10;background:#fff;border:1px solid #e5e7eb;border-radius:8px;padding:12px;width:600px;max-width:90vw;box-shadow:0 4px 16px rgba(0,0,0,.12)">
+                    <pre class="er-pre" style="max-height:300px"><%= occ.backtrace %></pre>
+                    <button onclick="toggleOcc('bt-<%= i %>')" style="margin-top:6px;font-size:11px;border:0;background:none;cursor:pointer;color:#6b7280">Close</button>
+                  </div>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+
+      <%# Pagination %>
+      <% if @occ_total_pages.to_i > 1 %>
+        <div style="margin-top:12px;display:flex;gap:6px;font-size:12px;align-items:center">
+          <% (1..@occ_total_pages).each do |p| %>
+            <% if p == @occ_page %>
+              <span style="padding:4px 10px;background:#2563eb;color:#fff;border-radius:6px"><%= p %></span>
+            <% else %>
+              <%= link_to p, error_path(@error, occ_page: p, anchor: 'occurrences-panel'),
+                    style: 'padding:4px 10px;border:1px solid #d1d5db;border-radius:6px;text-decoration:none;color:#374151' %>
+            <% end %>
+          <% end %>
+          <span style="color:#9ca3af">of <%= @occ_total_pages %> pages</span>
+        </div>
+      <% end %>
+    <% end %>
+  </div>
+<% end %>
+
 <%# ── GitHub Issue ── %>
 <% if ErrorRadar.config.github_token.present? && ErrorRadar.config.github_repo.present? %>
   <div class="panel" style="margin-top:16px">
@@ -130,6 +221,11 @@
 <% end %>
 
 <script>
+  window.toggleOcc = function (id) {
+    var el = document.getElementById(id);
+    if (el) el.style.display = el.style.display === 'none' ? 'block' : 'none';
+  };
+
 (function () {
   var CSRF       = document.querySelector('meta[name="csrf-token"]').content;
   var STATUS_URL = '<%= error_status_path(@error) %>';

data/config/routes.rb

@@ -16,4 +16,6 @@ ErrorRadar::Engine.routes.draw do
   get    'errors/:id',              to: 'errors#show',                as: :error
   patch  'errors/:id/status',       to: 'errors#update_status',       as: :error_status
   delete 'errors/:id',              to: 'errors#destroy'
+
+  post 'maintenance/purge', to: 'dashboard#purge', as: :maintenance_purge
 end

data/lib/error_radar/capture_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  # Background job for async exception capture. Used when config.async_capture
+  # is true. Failures are logged to Rails.logger and swallowed — a broken
+  # capture job must not cause retry storms or affect the application.
+  class CaptureJob < ActiveJob::Base
+    queue_as { ErrorRadar.config.capture_job_queue }
+
+    def perform(attrs_json)
+      attrs = JSON.parse(attrs_json, symbolize_names: true)
+      log   = ErrorLog.record(**attrs)
+      Notifier.dispatch(log) if log
+    rescue StandardError => e
+      ErrorRadar::Tracking.warn_internal("CaptureJob failed: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/error_radar/cleanup.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  # Prunes stale ErrorLog records. Two independent strategies run in sequence:
+  #
+  #   1. Age-based: deletes resolved/ignored records whose last_seen_at is
+  #      older than `older_than_days` (or config.retention_days).
+  #   2. Count-based: when the total exceeds config.max_records, deletes the
+  #      oldest resolved/ignored records until the limit is satisfied.
+  #
+  # Open and in_progress records are never deleted automatically.
+  module Cleanup
+    def self.run(older_than_days: nil, dry_run: false)
+      deleted = 0
+
+      # ── Age-based pruning ───────────────────────────────────────────────
+      days = (older_than_days || ErrorRadar.config.retention_days)&.to_i
+      if days && days > 0
+        cutoff = days.days.ago
+        scope  = stale_scope.where('last_seen_at < ?', cutoff)
+        deleted += dry_run ? scope.count : scope.delete_all
+      end
+
+      # ── Count-based pruning ────────────────────────────────────────────
+      max = ErrorRadar.config.max_records&.to_i
+      if max && max > 0
+        total = ErrorLog.count
+        if total > max
+          excess = total - max
+          ids    = stale_scope.order(last_seen_at: :asc).limit(excess).pluck(:id)
+          deleted += dry_run ? ids.size : ErrorLog.where(id: ids).delete_all
+        end
+      end
+
+      { deleted: deleted, dry_run: dry_run }
+    end
+
+    def self.stale_scope
+      ErrorLog.where(status: [ErrorLog.statuses[:resolved], ErrorLog.statuses[:ignored]])
+    end
+    private_class_method :stale_scope
+  end
+end

data/lib/error_radar/configuration.rb

@@ -69,6 +69,27 @@ module ErrorRadar
       @error_callbacks << block
     end
 
+    # Occurrences ─────────────────────────────────────────────────────────────
+    # When true, each individual error hit is stored in error_radar_occurrences.
+    # Requires running: bin/rails generate error_radar:upgrade_v060 && bin/rails db:migrate
+    attr_accessor :track_occurrences
+    # Maximum occurrences to keep per ErrorLog. Oldest are pruned on each new hit.
+    # nil = keep all (not recommended for high-volume apps).
+    attr_accessor :max_occurrences_per_error
+
+    # Performance ─────────────────────────────────────────────────────────────
+    # When true, ErrorLog.record is enqueued via ActiveJob (non-blocking).
+    # Requires ActiveJob to be configured. Falls back to sync if ActiveJob is absent.
+    attr_accessor :async_capture
+    # Queue name for CaptureJob when async_capture is enabled.
+    attr_accessor :capture_job_queue
+
+    # Retention ───────────────────────────────────────────────────────────────
+    # Auto-delete resolved/ignored records older than this many days (nil = keep forever).
+    attr_accessor :retention_days
+    # Keep at most this many total records; deletes oldest resolved/ignored first (nil = unlimited).
+    attr_accessor :max_records
+
     # REST API ────────────────────────────────────────────────────────────────
     # Bearer token for /api/* endpoints. nil = unauthenticated (not for prod).
     attr_accessor :api_token
@@ -135,6 +156,14 @@ module ErrorRadar
       @app_host             = nil
       @error_callbacks      = []
 
+      @track_occurrences        = false
+      @max_occurrences_per_error = 200
+
+      @async_capture     = false
+      @capture_job_queue = :default
+      @retention_days    = nil
+      @max_records       = nil
+
       @api_token    = nil
       @github_token = nil
       @github_repo  = nil

data/lib/error_radar/engine.rb

@@ -52,5 +52,9 @@ module ErrorRadar
         ErrorRadar::Integrations::RailsAdmin.install!
       end
     end
+
+    rake_tasks do
+      load File.expand_path('../tasks/error_radar.rake', __dir__)
+    end
   end
 end

data/lib/error_radar/tracking.rb

@@ -27,6 +27,17 @@ module ErrorRadar
         attrs.merge!(extra.compact) if extra.is_a?(Hash)
       end
 
+      if ErrorRadar.config.async_capture && defined?(::ActiveJob::Base)
+        require 'error_radar/capture_job'
+        job_attrs = attrs.merge(
+          category: attrs[:category].to_s,
+          severity: attrs[:severity].to_s,
+          context:  safe_json(attrs[:context])
+        )
+        ErrorRadar::CaptureJob.perform_later(job_attrs.to_json)
+        return nil
+      end
+
       log = ErrorRadar::ErrorLog.record(**attrs)
       ErrorRadar::Notifier.dispatch(log) if log
       log
@@ -112,6 +123,12 @@ module ErrorRadar
       nil
     end
 
+    def safe_json(value)
+      JSON.parse(value.to_json)
+    rescue StandardError
+      {}
+    end
+
     def warn_internal(message)
       logger = defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
       logger ? logger.error("[ErrorRadar] #{message}") : warn("[ErrorRadar] #{message}")

data/lib/error_radar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ErrorRadar
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end

data/lib/error_radar.rb

@@ -4,6 +4,7 @@ require 'error_radar/version'
 require 'error_radar/configuration'
 require 'error_radar/tracking'
 require 'error_radar/notifier'
+require 'error_radar/cleanup'
 require 'error_radar/middleware'
 require 'error_radar/server_monitor'
 require 'error_radar/engine'

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

@@ -83,6 +83,31 @@ ErrorRadar.configure do |config|
   # Requires running: bin/rails generate error_radar:upgrade_v050 && bin/rails db:migrate
   # config.github_token = ENV['GITHUB_TOKEN']   # PAT with repo scope
   # config.github_repo  = 'myorg/myapp'         # "owner/repo" format
+
+  # --- Occurrence History ---
+  # Store each individual error hit so you can see context/backtrace per occurrence.
+  # Requires running: bin/rails generate error_radar:upgrade_v060 && bin/rails db:migrate
+  # config.track_occurrences         = true
+  # config.max_occurrences_per_error = 200  # keep last N per error (oldest pruned on each new hit)
+
+  # --- Performance & Async Capture ---
+  # Write ErrorLog records via ActiveJob so exceptions don't block the request.
+  # Requires ActiveJob + a queue adapter (Sidekiq, Solid Queue, etc.).
+  # Falls back to synchronous capture if ActiveJob is unavailable.
+  # config.async_capture     = true
+  # config.capture_job_queue = :default   # queue name for CaptureJob
+
+  # --- Retention / Cleanup ---
+  # Auto-prune old resolved/ignored records to keep the table lean.
+  # Run `rake error_radar:cleanup` from a cron job or Heroku Scheduler.
+  # config.retention_days = 90    # delete resolved/ignored records older than 90 days
+  # config.max_records    = 50000 # hard cap; oldest resolved/ignored purged first
+  #
+  # Rake tasks available:
+  #   rake error_radar:cleanup              # apply retention_days + max_records
+  #   rake error_radar:cleanup:dry_run      # preview without deleting
+  #   rake error_radar:cleanup:older_than   # DAYS=30 rake error_radar:cleanup:older_than
+  #   rake error_radar:stats                # print table summary
 end
 
 # ActiveJob is now captured automatically via install_active_job = true above.

data/lib/generators/error_radar/upgrade_v060/templates/create_error_radar_occurrences.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateErrorRadarOccurrences < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :error_radar_occurrences do |t|
+      t.references :error_log, null: false,
+                               foreign_key: { to_table: :error_radar_error_logs },
+                               index: false  # covered by composite index below
+
+      t.datetime :occurred_at, null: false
+
+      t.json    :context      # structured payload snapshot for this hit
+      t.text    :backtrace    # backtrace at the moment of this occurrence
+      t.integer :http_status
+      t.string  :request_url, limit: 2000
+
+      t.timestamps
+    end
+
+    # Fast per-error chronological listing
+    add_index :error_radar_occurrences, %i[error_log_id occurred_at],
+              name: 'idx_er_occurrences_log_time'
+  end
+end

data/lib/generators/error_radar/upgrade_v060/upgrade_v060_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_record'
+
+module ErrorRadar
+  module Generators
+    class UpgradeV060Generator < ActiveRecord::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      argument :name, type: :string, default: 'upgrade_v060'
+
+      desc 'Creates the error_radar_occurrences table for per-hit occurrence history (v0.7.0).'
+
+      def create_migration
+        migration_template 'create_error_radar_occurrences.rb.tt',
+                           'db/migrate/create_error_radar_occurrences.rb'
+      end
+    end
+  end
+end

data/lib/tasks/error_radar.rake

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+namespace :error_radar do
+  desc 'Delete old resolved/ignored ErrorLogs per config.retention_days and config.max_records'
+  task cleanup: :environment do
+    result = ErrorRadar::Cleanup.run
+    puts "[ErrorRadar] Cleanup complete — #{result[:deleted]} record(s) deleted."
+  end
+
+  namespace :cleanup do
+    desc 'Preview what error_radar:cleanup would delete without actually deleting'
+    task dry_run: :environment do
+      result = ErrorRadar::Cleanup.run(dry_run: true)
+      puts "[ErrorRadar] Dry run — would delete #{result[:deleted]} record(s)."
+    end
+
+    desc 'Delete resolved/ignored ErrorLogs older than DAYS (e.g. DAYS=30 rake error_radar:cleanup:older_than)'
+    task older_than: :environment do
+      days = ENV.fetch('DAYS', nil)&.to_i
+      abort '[ErrorRadar] Set DAYS env var (e.g. DAYS=30)' unless days&.positive?
+
+      result = ErrorRadar::Cleanup.run(older_than_days: days)
+      puts "[ErrorRadar] Deleted #{result[:deleted]} record(s) older than #{days} days."
+    end
+  end
+
+  desc 'Print a summary of ErrorLog table stats'
+  task stats: :environment do
+    counts = ErrorRadar::ErrorLog.group(:status).count
+                                 .transform_keys { |k| ErrorRadar::ErrorLog.statuses.key(k) || k }
+    total  = counts.values.sum
+
+    puts "\n[ErrorRadar] Error log summary"
+    puts "  Total      : #{total}"
+    puts "  Open       : #{counts['open'] || 0}"
+    puts "  In progress: #{counts['in_progress'] || 0}"
+    puts "  Resolved   : #{counts['resolved'] || 0}"
+    puts "  Ignored    : #{counts['ignored'] || 0}"
+
+    oldest = ErrorRadar::ErrorLog.minimum(:first_seen_at)
+    puts "  Oldest     : #{oldest&.strftime('%Y-%m-%d') || '—'}"
+    puts ''
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: error_radar
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - chienbn9x
@@ -66,6 +66,7 @@ files:
 - app/mailers/error_radar/error_mailer.rb
 - app/models/error_radar/application_record.rb
 - app/models/error_radar/error_log.rb
+- app/models/error_radar/error_occurrence.rb
 - app/views/error_radar/dashboard/index.html.erb
 - app/views/error_radar/dashboard/show.html.erb
 - app/views/error_radar/error_mailer/new_error.html.erb
@@ -75,6 +76,8 @@ files:
 - app/views/layouts/error_radar/application.html.erb
 - config/routes.rb
 - lib/error_radar.rb
+- lib/error_radar/capture_job.rb
+- lib/error_radar/cleanup.rb
 - lib/error_radar/configuration.rb
 - lib/error_radar/engine.rb
 - lib/error_radar/integrations/active_job.rb
@@ -96,6 +99,9 @@ files:
 - lib/generators/error_radar/install/templates/initializer.rb
 - lib/generators/error_radar/upgrade_v050/templates/add_github_issue_to_error_radar_error_logs.rb.tt
 - lib/generators/error_radar/upgrade_v050/upgrade_v050_generator.rb
+- lib/generators/error_radar/upgrade_v060/templates/create_error_radar_occurrences.rb.tt
+- lib/generators/error_radar/upgrade_v060/upgrade_v060_generator.rb
+- lib/tasks/error_radar.rake
 homepage: https://github.com/chienbn9x/error_radar
 licenses:
 - MIT