rails_error_dashboard 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b2e35c8edb61946295bbd2bb05ae2707e6fa00dc185decf62cb3fa938cdf44d
-  data.tar.gz: 5b511e0c7a0c1c4fc545a8369ceb1f8cbd32a8cf678a3b55df3607b98c03d5dd
+  metadata.gz: d6b9a0833340184697ca86044a78e7a91ef89a3e328606c246df4dc8ced28eb7
+  data.tar.gz: b2f94352f6a035f842c36e277374b1b60bd2bc2cd3f48c5480e640073658395f
 SHA512:
-  metadata.gz: 64458bad098e19081d3000a2ecede576586713bf8fe523f5ca19b98752935eea1338447c69890ece067a818c012377c90bf1a8b97b20d7bbcabdd62564ab6fb0
-  data.tar.gz: 510f01f55a766042854c0105840a7de4b33c23a704bb036c95c9c663263143c725b7ff0ec5ab32c4347a3be608068f4d1eed3ac747b0d3bda5221a1b443984c4
+  metadata.gz: f296da936589382a6fd7d727d90cf82f115d91fbb30ff63c0fe56df1b6197f09ca46accc3d39d86718b5abaaee32aa9a11fd18089750e16d9f3bb13243fcf6ef
+  data.tar.gz: d2cbd1a52e7c85153b28fa7537650776b9aff1ae6588626c0ab5e76a3f2c45bbf7d30774a99530c3faa3c708edb1ae42d9dfc8dbc6709acff2d285bb7035ac47

data/README.md

@@ -1,8 +1,10 @@
 # Rails Error Dashboard
 
 [![Gem Version](https://badge.fury.io/rb/rails_error_dashboard.svg)](https://badge.fury.io/rb/rails_error_dashboard)
+[![Downloads](https://img.shields.io/gem/dt/rails_error_dashboard)](https://rubygems.org/gems/rails_error_dashboard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Tests](https://github.com/AnjanJ/rails_error_dashboard/workflows/Tests/badge.svg)](https://github.com/AnjanJ/rails_error_dashboard/actions)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/anjanj)
 
 ## Self-hosted Rails error monitoring — free, forever.
 
@@ -26,10 +28,36 @@ Username: `gandalf` · Password: `youshallnotpass`
 
 Experience the full dashboard with 480+ realistic Rails errors, LOTR-themed demo data, cause chains, enriched context, auto-reopened errors, and all features enabled.
 
+### Screenshots
+
+**Dashboard Overview** — Real-time error stats, severity breakdown, and trend charts at a glance.
+
+![Dashboard Overview](docs/images/dashboard-overview.png)
+
+**Error Detail** — Full stack trace, cause chain, enriched context, and workflow management.
+
+![Error Detail](docs/images/error-detail.png)
+
+**Analytics** — Error trends, platform health, correlation insights, and pattern detection.
+
+![Analytics](docs/images/analytics.png)
+
+**Deprecation Warnings** — Aggregate deprecation warnings across all errors with occurrence counts and affected error links.
+
+![Deprecation Warnings](docs/images/deprecations.png)
+
+**N+1 Query Patterns** — Cross-error N+1 detection grouped by SQL fingerprint.
+
+![N+1 Query Patterns](docs/images/n-plus-one-queries.png)
+
+**Cache Health** — Per-error cache performance sorted worst-first.
+
+![Cache Health](docs/images/cache-health.png)
+
 ---
 
 ### ⚠️ BETA SOFTWARE
-This Rails Engine is in beta and under active development. While functional and tested (1,895+ tests passing, including browser-based system tests), the API may change before v1.0.0. Use in production at your own discretion.
+This Rails Engine is in beta and under active development. While functional and tested (2,100+ tests passing, including browser-based system tests), the API may change before v1.0.0. Use in production at your own discretion.
 
 **Supports**: Rails 7.0 - 8.1 | Ruby 3.2 - 4.0
 
@@ -97,7 +125,7 @@ Modern Bootstrap 5 UI with dark/light mode, responsive design, real-time statist
 Error assignment and status tracking, priority levels (critical/high/medium/low), snooze functionality, comment threads, batch operations (bulk resolve/delete), resolution tracking with references.
 
 #### 🔒 Security & Privacy
-HTTP Basic Auth, environment-based settings, optional separate database for isolation. Your data stays on your server - no third-party access.
+HTTP Basic Auth or custom authentication via `config.authenticate_with` lambda (Devise, Warden, session-based — runs in controller context with access to `warden`, `session`, `request`). Environment-based settings, optional separate database for isolation. Your data stays on your server - no third-party access.
 
 ### Optional Features (Choose During Install)
 
@@ -143,7 +171,7 @@ Detect cyclical patterns (business hours, nighttime, weekend rhythms) and error
 **Plus: Developer Insights Dashboard** 💡
 Built-in analytics dashboard with severity detection, platform stability scoring, actionable recommendations, and recent error activity summaries (always available, no configuration needed).
 
-#### 🔍 Source Code Integration (NEW!)
+#### 🔍 Source Code Integration
 
 **View actual source code directly in error backtraces** - no need to switch to your editor or GitHub.
 
@@ -153,22 +181,53 @@ Built-in analytics dashboard with severity detection, platform stability scoring
 - **Smart Caching** - Fast performance with 1-hour cache (configurable)
 - **Security Controls** - Only shows your app code by default (not gems/frameworks)
 
-**Perfect for debugging:**
-- Understand the code context without leaving the dashboard
-- Identify code ownership with git blame
-- Quick navigation to your repository
-- See recent changes that might have caused the error
-
 ```ruby
-# Enable in config/initializers/rails_error_dashboard.rb
 config.enable_source_code_integration = true
-config.source_code_context_lines = 7
 config.enable_git_blame = true
-config.git_repository_url = "https://github.com/user/repo"
 ```
 
 **📖 [Complete documentation →](docs/SOURCE_CODE_INTEGRATION.md)**
 
+#### 🥖 Breadcrumbs — Request Activity Trail (NEW!)
+
+**See exactly what happened before the crash** — SQL queries, controller actions, cache operations, job executions, and mailer deliveries captured automatically via `ActiveSupport::Notifications`.
+
+- **Automatic capture** — Zero config beyond the enable flag (Rails already emits the events)
+- **Timeline display** — Color-coded event list on each error's detail page
+- **Deprecation warnings** — `deprecation.rails` events captured with caller location
+- **N+1 detection** — Repeated SQL patterns flagged automatically at display time
+- **Custom breadcrumbs** — `RailsErrorDashboard.add_breadcrumb("checkout started", { cart_id: 123 })`
+- **Safe by design** — Fixed-size ring buffer, thread-local, every subscriber wrapped in rescue
+- **Async-compatible** — Breadcrumbs harvested before background job dispatch
+- **Deprecation warnings page** — Aggregate view across all errors at `/errors/deprecations`
+- **N+1 query patterns page** — Cross-error N+1 analysis at `/errors/n_plus_one_summary`
+- **Cache health page** — App-wide cache performance sorted worst-first at `/errors/cache_health_summary`
+
+```ruby
+config.enable_breadcrumbs = true
+config.breadcrumb_buffer_size = 40  # Max events per request
+```
+
+**📖 [Complete documentation →](docs/FEATURES.md#breadcrumbs--request-activity-trail-new)**
+
+#### 💓 System Health Snapshot (NEW!)
+
+**Know your app's runtime state at the moment of failure** — GC stats, process memory, thread count, connection pool utilization, and Puma thread stats captured automatically when errors occur.
+
+- **GC stats** — Heap live/free slots, major GC count, total allocated objects
+- **Process memory** — RSS in MB (Linux procfs only, no subprocess/fork)
+- **Thread count** — `Thread.list.count` (O(1), safe)
+- **Connection pool** — Size, busy, idle, dead, waiting connections
+- **Puma stats** — Running threads, max threads, pool capacity, backlog
+- **Sub-millisecond** — Total snapshot < 1ms, every metric individually rescue-wrapped
+- **Safe by design** — No ObjectSpace scanning, no Thread backtraces, no subprocess calls
+
+```ruby
+config.enable_system_health = true
+```
+
+**📖 [Complete documentation →](docs/FEATURES.md#system-health-snapshot-new)**
+
 #### 🆕 v0.2 Quick Wins (NEW!)
 
 **11 features that make error tracking smarter, safer, and more actionable:**
@@ -303,6 +362,9 @@ RailsErrorDashboard.configure do |config|
   config.dashboard_username = ENV.fetch('ERROR_DASHBOARD_USER', 'gandalf')
   config.dashboard_password = ENV.fetch('ERROR_DASHBOARD_PASSWORD', 'youshallnotpass')
 
+  # Or use your existing auth (Devise, Warden, etc.) instead of Basic Auth:
+  # config.authenticate_with = -> { warden.authenticated? }
+
   # ============================================================================
   # OPTIONAL FEATURES (Enable as needed)
   # ============================================================================
@@ -656,7 +718,7 @@ Clean, maintainable, testable architecture you can understand and modify.
 
 ## 🧪 Testing
 
-1,800+ tests covering unit, integration, and browser-based system tests.
+2,100+ tests covering unit, integration, and browser-based system tests.
 
 ### Running Tests
 
@@ -749,7 +811,7 @@ Rails Error Dashboard is available as open source under the terms of the [MIT Li
 <details>
 <summary><strong>Is this production-ready?</strong></summary>
 
-This is currently in **beta** but actively tested with 1,800+ passing tests across Rails 7.0-8.1 and Ruby 3.2-4.0. Many users are running it in production. See [production requirements](docs/FEATURES.md#production-readiness).
+This is currently in **beta** but actively tested with 2,100+ passing tests across Rails 7.0-8.1 and Ruby 3.2-4.0. Many users are running it in production. See [production requirements](docs/FEATURES.md#production-readiness).
 </details>
 
 <details>
@@ -958,6 +1020,12 @@ Want to contribute? Check out our [Contributing Guide](CONTRIBUTING.md)!
 
 ---
 
+## Support
+
+If this gem saves you some headaches (or some money on error tracking SaaS), consider [buying me a coffee](https://buymeacoffee.com/anjanj). It keeps the project going and lets me know people are finding it useful.
+
+---
+
 **Made with ❤️ by [Anjan](https://www.anjan.dev) for the Rails community**
 
 *One Gem to rule them all, One Gem to find them, One Gem to bring them all, and in the dashboard bind them.* 🧙‍♂️

data/app/controllers/rails_error_dashboard/errors_controller.rb

@@ -236,6 +236,67 @@ module RailsErrorDashboard
       @platform_specific_errors = correlation.platform_specific_errors
     end
 
+    def deprecations
+      unless RailsErrorDashboard.configuration.enable_breadcrumbs
+        flash[:alert] = "Breadcrumbs are not enabled. Enable them in config/initializers/rails_error_dashboard.rb"
+        redirect_to errors_path
+        return
+      end
+
+      days = (params[:days] || 30).to_i
+      @days = days
+      result = Queries::DeprecationWarnings.call(days, application_id: @current_application_id)
+      all_deprecations = result[:deprecations]
+
+      # Summary stats (computed before pagination)
+      @unique_count = all_deprecations.size
+      @total_count = all_deprecations.sum { |d| d[:count] }
+      @affected_count = all_deprecations.flat_map { |d| d[:error_ids] }.uniq.size
+
+      @pagy, @deprecations = pagy(:offset, all_deprecations, limit: params[:per_page] || 25)
+    end
+
+    def n_plus_one_summary
+      unless RailsErrorDashboard.configuration.enable_breadcrumbs
+        flash[:alert] = "Breadcrumbs are not enabled. Enable them in config/initializers/rails_error_dashboard.rb"
+        redirect_to errors_path
+        return
+      end
+
+      days = (params[:days] || 30).to_i
+      @days = days
+      result = Queries::NplusOneSummary.call(days, application_id: @current_application_id)
+      all_patterns = result[:patterns]
+
+      # Summary stats (computed before pagination)
+      @unique_count = all_patterns.size
+      @total_count = all_patterns.sum { |p| p[:count] }
+      @affected_count = all_patterns.flat_map { |p| p[:error_ids] }.uniq.size
+
+      @pagy, @patterns = pagy(:offset, all_patterns, limit: params[:per_page] || 25)
+    end
+
+    def cache_health_summary
+      unless RailsErrorDashboard.configuration.enable_breadcrumbs
+        flash[:alert] = "Breadcrumbs are not enabled. Enable them in config/initializers/rails_error_dashboard.rb"
+        redirect_to errors_path
+        return
+      end
+
+      days = (params[:days] || 30).to_i
+      @days = days
+      result = Queries::CacheHealthSummary.call(days, application_id: @current_application_id)
+      all_entries = result[:entries]
+
+      # Summary stats (computed before pagination)
+      @errors_with_cache = all_entries.size
+      non_nil_rates = all_entries.map { |e| e[:hit_rate] }.compact
+      @avg_hit_rate = non_nil_rates.any? ? (non_nil_rates.sum / non_nil_rates.size).round(1) : nil
+      @total_cache_ops = all_entries.sum { |e| e[:reads] + e[:writes] }
+
+      @pagy, @entries = pagy(:offset, all_entries, limit: params[:per_page] || 25)
+    end
+
     def settings
       @config = RailsErrorDashboard.configuration
     end
@@ -272,7 +333,33 @@ module RailsErrorDashboard
     end
 
     def authenticate_dashboard_user!
-      # Authentication is ALWAYS required - no bypass allowed in any environment
+      auth_lambda = RailsErrorDashboard.configuration.authenticate_with
+
+      if auth_lambda
+        authenticate_with_lambda(auth_lambda)
+      else
+        authenticate_with_basic_auth
+      end
+    end
+
+    def authenticate_with_lambda(auth_lambda)
+      authorized = begin
+        instance_exec(&auth_lambda)
+      rescue => e
+        Rails.logger.error(
+          "[RailsErrorDashboard] authenticate_with lambda raised #{e.class}: #{e.message}"
+        )
+        false
+      end
+
+      return if performed?
+
+      unless authorized
+        render plain: "Access Denied", status: :forbidden
+      end
+    end
+
+    def authenticate_with_basic_auth
       authenticate_or_request_with_http_basic do |username, password|
         ActiveSupport::SecurityUtils.secure_compare(
           username,

data/app/helpers/rails_error_dashboard/application_helper.rb

@@ -196,6 +196,31 @@ module RailsErrorDashboard
       )
     end
 
+    # Returns Bootstrap badge color class for breadcrumb category
+    # @param category [String] Breadcrumb category (sql, controller, cache, job, mailer, custom)
+    # @return [String] Bootstrap color class
+    def breadcrumb_badge_color(category)
+      case category.to_s
+      when "sql"        then "primary"
+      when "controller" then "success"
+      when "cache"      then "info"
+      when "job"        then "warning"
+      when "mailer"     then "secondary"
+      when "custom"     then "dark"
+      when "deprecation" then "danger"
+      else "light"
+      end
+    end
+
+    # Extracts table name from a SQL query string
+    # @param sql [String] SQL query (e.g., 'SELECT "users".* FROM "users" WHERE ...')
+    # @return [String, nil] The table name or nil if not extractable
+    def extract_table_from_sql(sql)
+      return nil if sql.blank?
+      match = sql.match(/FROM\s+["`]?(\w+)["`]?/i)
+      match ? match[1] : nil
+    end
+
     # Automatically converts URLs in text to clickable links that open in new window
     # Also highlights inline code wrapped in backticks with syntax highlighting
     # Also converts file paths to GitHub links if repository URL is configured

data/app/jobs/rails_error_dashboard/retention_cleanup_job.rb

@@ -3,7 +3,7 @@
 module RailsErrorDashboard
   # Background job to enforce the retention_days configuration.
   # Deletes error logs (and their associated records) older than the configured threshold.
-  # Uses find_each + destroy to respect dependent: :destroy on associations.
+  # Uses batch deletion (in_batches + delete_all) for performance on large tables.
   #
   # Schedule this job daily via your preferred scheduler (SolidQueue, Sidekiq, cron).
   #
@@ -20,13 +20,25 @@ module RailsErrorDashboard
       return 0 if retention_days.blank?
 
       cutoff = retention_days.days.ago
+      expired_scope = ErrorLog.where("occurred_at < ?", cutoff)
+      return 0 if expired_scope.none?
+
       deleted_count = 0
 
-      # Use find_each to process in batches (default 1000)
-      # destroy triggers dependent: :destroy on associations (occurrences, comments, cascades)
-      ErrorLog.where("occurred_at < ?", cutoff).find_each do |error_log|
-        error_log.destroy
-        deleted_count += 1
+      # Delete dependents first, then errors — all in batches to prevent table locks
+      expired_ids_scope = expired_scope.select(:id)
+
+      # Batch delete dependent records (occurrences, comments, cascade patterns)
+      ErrorOccurrence.where(error_log_id: expired_ids_scope).in_batches(of: 1000).delete_all
+      ErrorComment.where(error_log_id: expired_ids_scope).in_batches(of: 1000).delete_all
+      CascadePattern.where(parent_error_id: expired_ids_scope)
+                    .or(CascadePattern.where(child_error_id: expired_ids_scope))
+                    .in_batches(of: 1000).delete_all
+
+      # Now batch delete the error logs themselves
+      expired_scope.in_batches(of: 1000) do |batch|
+        batch_size = batch.delete_all
+        deleted_count += batch_size
       end
 
       if deleted_count > 0

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

@@ -3,6 +3,7 @@
   <head>
     <title><%= content_for?(:page_title) ? "#{content_for(:page_title)} | " : "" %><%= Rails.application.class.module_parent_name %> - Error Dashboard</title>
     <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="turbo-visit-control" content="reload">
     <% if respond_to?(:csrf_meta_tags) %>
       <%= csrf_meta_tags %>
     <% end %>
@@ -1379,10 +1380,136 @@ body.dark-mode .skeleton {
   vertical-align: middle;
   margin-right: 0.25em;
 }
+
+/* Section Navigation */
+#section-nav-wrapper {
+  position: sticky;
+  top: 0;
+  z-index: 1020;
+  background: #f3f4f6;
+  margin: 0 -12px;
+  padding: 0 12px;
+  transition: box-shadow 0.2s ease, background-color 0.3s;
+}
+
+#section-nav-wrapper.is-stuck {
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+  border-bottom: 1px solid #e5e7eb;
+}
+
+.section-nav-scroll {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+  mask-image: linear-gradient(to right, black 0, black calc(100% - 24px), transparent 100%);
+  -webkit-mask-image: linear-gradient(to right, black 0, black calc(100% - 24px), transparent 100%);
+  padding-right: 16px;
+}
+.section-nav-scroll::-webkit-scrollbar {
+  display: none;
+}
+
+.section-nav-label {
+  font-size: 0.85rem;
+  white-space: nowrap;
+  color: #9ca3af !important;
+}
+
+.section-nav-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 4px 10px;
+  border-radius: 20px;
+  font-size: 0.78rem;
+  font-weight: 500;
+  white-space: nowrap;
+  text-decoration: none;
+  color: #4b5563;
+  background: white;
+  border: 1px solid #e5e7eb;
+  border: 1px solid transparent;
+  transition: all 0.15s ease;
+  cursor: pointer;
+}
+
+.section-nav-pill:hover {
+  color: #1f2937;
+  background: #f3f4f6;
+  text-decoration: none;
+}
+
+.section-nav-pill.active {
+  color: white;
+  background: #3b82f6;
+  border-color: #3b82f6;
+}
+
+.section-nav-pill i {
+  font-size: 0.75rem;
+}
+
+/* Dark mode overrides for section nav */
+body.dark-mode #section-nav-wrapper { background: var(--ctp-base); }
+body.dark-mode #section-nav-wrapper.is-stuck { box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3); border-bottom-color: var(--ctp-surface0); }
+body.dark-mode .section-nav-label { color: var(--ctp-overlay2) !important; }
+body.dark-mode .section-nav-pill { color: var(--ctp-subtext0); background: var(--ctp-surface0); }
+body.dark-mode .section-nav-pill:hover { color: var(--ctp-text); background: var(--ctp-surface1); }
+body.dark-mode .section-nav-pill.active { color: var(--ctp-base); background: var(--ctp-blue); border-color: var(--ctp-blue); }
+
+/* Sidebar sub-section panels */
+.sidebar-section {
+  border-left: 3px solid #9ca3af;
+  padding-left: 10px;
+  margin-top: 16px;
+  margin-bottom: 8px;
+}
+.sidebar-section-blue { border-left-color: #3b82f6; }
+.sidebar-section-red { border-left-color: #ef4444; }
+
+.sidebar-section-title {
+  font-size: 0.8rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: #4b5563;
+  margin-bottom: 2px;
+}
+.sidebar-section-title i { margin-right: 4px; }
+
+.sidebar-section-hint {
+  font-size: 0.72rem;
+  color: #6b7280;
+  margin-bottom: 6px;
+  display: block;
+}
+
+.sidebar-section-body {
+  background: #f9fafb;
+  border-radius: 6px;
+  padding: 8px 10px;
+}
+
+/* Metadata field labels */
+.metadata-label {
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #4b5563;
+}
+body.dark-mode .metadata-label { color: var(--ctp-overlay2); }
+
+/* Dark mode overrides */
+body.dark-mode .sidebar-section { border-left-color: var(--ctp-overlay2); }
+body.dark-mode .sidebar-section-blue { border-left-color: var(--ctp-blue); }
+body.dark-mode .sidebar-section-red { border-left-color: var(--ctp-red); }
+body.dark-mode .sidebar-section-title { color: var(--ctp-subtext1); }
+body.dark-mode .sidebar-section-hint { color: var(--ctp-overlay2); }
+body.dark-mode .sidebar-section-body { background: var(--ctp-mantle); }
     </style>
   </head>
 
-  <body>
+  <body data-turbo="false">
     <!-- Toast Container -->
     <div class="toast-container position-fixed top-0 end-0 p-3" style="z-index: 9999;">
       <!-- Toasts will be dynamically inserted here -->
@@ -1513,6 +1640,23 @@ body.dark-mode .skeleton {
                   <i class="bi bi-gear"></i> Settings
                 <% end %>
               </li>
+              <% if RailsErrorDashboard.configuration.enable_breadcrumbs %>
+                <li class="nav-item">
+                  <%= link_to deprecations_errors_path(nav_params), class: "nav-link #{request.path == deprecations_errors_path ? 'active' : ''}" do %>
+                    <i class="bi bi-exclamation-triangle"></i> Deprecations
+                  <% end %>
+                </li>
+                <li class="nav-item">
+                  <%= link_to n_plus_one_summary_errors_path(nav_params), class: "nav-link #{request.path == n_plus_one_summary_errors_path ? 'active' : ''}" do %>
+                    <i class="bi bi-arrow-repeat"></i> N+1 Queries
+                  <% end %>
+                </li>
+                <li class="nav-item">
+                  <%= link_to cache_health_summary_errors_path(nav_params), class: "nav-link #{request.path == cache_health_summary_errors_path ? 'active' : ''}" do %>
+                    <i class="bi bi-lightning-charge"></i> Cache Health
+                  <% end %>
+                </li>
+              <% end %>
             </ul>
 
             <h6 class="mt-4">QUICK FILTERS</h6>