solid_stack_web 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7932ddf2c50cc9ae63a884c0dabdc0fe4553c9dfb823870d3e1b15b4dc2a3a6
-  data.tar.gz: 04d6d15b941d21dfae0d1562095e6cdb4cd67a7e1163efa3bc2d33563df2fb92
+  metadata.gz: 1717d75a5baabd8728f6f9877b5146849be9322a627cf295bd922690aa284592
+  data.tar.gz: ae814ccee9aa89798575f914652ccfbb51137473961d7fd1a22b7a4461449102
 SHA512:
-  metadata.gz: 37ac38026dbde5e629d132f18795797f84a7b48b8e19689435b0288f44c57abf73e7dae5aa9e51884021920b4b336160597529b4f87c44cac027e9b88c1293d6
-  data.tar.gz: c233686b589092befdcc5b19ca7bfd09a2f10e9f1d95b894f58afff4fb67475ddcae308bf6b65386f9af5479d670256dde1cd02cf3cf2b5466eadcd00a051a2d
+  metadata.gz: e0d79705beafccb16561d20a28cac815607f2a202bc6d0839449c501f8d4f5bd93bd83ccb4a7c4be0d6b701ecb69b9aca8fa5ee2a3d4462712fc8399c935162a
+  data.tar.gz: 2663a57cf04ca3aa26463732638020c63ce76d10046979dbd22baae8f5b529d3092e3597aa9c4a8b9b06b0a43b9a648e0a573349bca1f39d6f944fe4a8313884

data/README.md

@@ -21,23 +21,13 @@ Run:
 bundle install
 ```
 
-Mount the engine in `config/routes.rb`:
-
-```ruby
-mount SolidStackWeb::Engine, at: "/solid_stack"
-```
-
-The dashboard will be available at `/solid_stack` (or whatever path you choose).
-
-### Install generator
-
 Run the install generator to create a documented initializer and wire up the mount point in one step:
 
 ```bash
 rails generate solid_stack_web:install
 ```
 
-This creates `config/initializers/solid_stack_web.rb` with every configuration option commented inline, and injects `mount SolidStackWeb::Engine, at: "/solid_stack"` into `config/routes.rb`.
+This creates `config/initializers/solid_stack_web.rb` with every configuration option commented inline, and injects `mount SolidStackWeb::Engine, at: "/solid_stack"` into `config/routes.rb`. The dashboard will then be available at `/solid_stack` (or whatever path you choose).
 
 ---
 
@@ -77,7 +67,7 @@ This creates `config/initializers/solid_stack_web.rb` with every configuration o
 
 ## General configuration
 
-Create an initializer at `config/initializers/solid_stack_web.rb`:
+The install generator creates `config/initializers/solid_stack_web.rb` with all options documented inline. The available options are:
 
 ```ruby
 SolidStackWeb.configure do |config|
@@ -152,16 +142,17 @@ The dashboard is designed to be mounted behind your application's existing authe
 
 ### Features
 
-- **Overview dashboard** — live counts across all queue statuses; done (1h/24h), healthy/stale process counts, and optionally slow jobs (when `slow_job_threshold` is configured); 12-hour throughput sparkline with per-bar hover tooltips
+- **Overview dashboard** — live counts across all queue statuses; done (1h/24h), healthy/stale process counts, and optionally slow jobs (when `slow_job_threshold` is configured); 12-hour throughput sparkline and a 12-hour failures sparkline (red bars) with per-bar hover tooltips — failure spikes visible before clicking into the failed jobs list
 - **Job browser** — browse jobs by status (ready, scheduled, claimed, blocked) with filtering by job class, queue name, priority, and time period; **Discard All** bulk-discards every job matching the current filters in one request; **CSV export** downloads jobs respecting active filters
 - **Bulk selection** — checkbox-select individual jobs for discard; select-all support
 - **Per-queue browser** — click any queue name or size to drill into its ready jobs with per-row and bulk discard; pause/resume controls on the queue page
 - **Queue depth sparklines** — Queues index shows a 12-hour depth chart per queue; each bar is the ready-job count at an hourly snapshot with an instant hover tooltip
 - **Job detail page** — full arguments (pretty-printed JSON), queue, priority, enqueued time, Active Job ID, concurrency key, scheduled/blocked-until metadata, and a Discard button
 - **Failed jobs** — list with retry / discard / bulk retry / bulk discard; **Failed job detail page** — full error, backtrace, and an inline JSON argument editor; submit to update arguments and retry in one action
+- **Error frequency report** — `GET /failed_jobs/errors` groups all failed jobs by exception class and message prefix with a count and expandable sample backtrace; links through to a filtered list for each error group
 - **Scheduled job management** — "Run Now" and offset buttons (+1h / +24h / +7d) per row update the scheduled time inline via Turbo Stream; "Run All Now (N)" back-dates all matching executions at once
 - **Recurring task list** — enumerates all `SolidQueue::RecurringTask` records with cron schedule, job class or command, queue, next-run and last-run times, and a static/dynamic badge; each row has a "Run Now" button
-- **Performance statistics page** — `GET /stats` aggregates finished jobs by class name with execution count, avg, p50, p95, min, and max duration; click any column header to sort; defaults to p95 descending
+- **Performance statistics page** — `GET /stats` aggregates finished jobs by class name with execution count, avg, p50, p95, p99, std dev, min, and max duration; click any column header to sort; defaults to p95 descending; high std dev flags inconsistent jobs worth investigating
 - **Job history view** — paginated list of all finished jobs with class name, queue, duration, and finished-at time; filterable by queue (click a badge), class substring, and time period; CSV export respects active filters
 - **Auto-refresh** — dashboard, jobs, processes, and history views poll automatically; pauses when the tab is hidden or a checkbox is checked; intervals configurable via `dashboard_refresh_interval` and `default_refresh_interval`
 - **Turbo Stream** job discard — removes the row inline without a full page reload

data/app/assets/stylesheets/solid_stack_web/_07_dashboard.css

@@ -86,6 +86,10 @@ a.sqw-inline-stat:hover { opacity: 0.7; text-decoration: none; }
   color: var(--primary);
 }
 
+.sqw-sparkline-wrap--failures {
+  color: var(--danger);
+}
+
 .sqw-sparkline-label {
   display: block;
   font-size: 10px;

data/app/assets/stylesheets/solid_stack_web/_09_detail.css

@@ -84,6 +84,29 @@
 
 .sqw-value-truncated { font-size: 12px; margin-top: 0.5rem; }
 
+.sqw-error-details > summary {
+  cursor: pointer;
+  list-style: none;
+  display: block;
+  max-width: 480px;
+}
+.sqw-error-details > summary::-webkit-details-marker { display: none; }
+.sqw-error-details[open] > summary { margin-bottom: 0.5rem; }
+
+.sqw-error-backtrace {
+  font-family: ui-monospace, "SFMono-Regular", Menlo, monospace;
+  font-size: 11px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 0.5rem 0.75rem;
+  overflow-x: auto;
+  white-space: pre;
+  max-height: 200px;
+  overflow-y: auto;
+  margin-top: 0.25rem;
+}
+
 .sqw-link { color: var(--primary); text-decoration: none; }
 .sqw-link:hover { text-decoration: underline; }
 

data/app/controllers/solid_stack_web/dashboard_controller.rb

@@ -5,6 +5,7 @@ module SolidStackWeb
       @cache_stats = CacheStats.new.to_h
       @cable_stats = CableStats.new.to_h
       @throughput  = ThroughputSparkline.new
+      @failures    = FailedJobSparkline.new
     end
   end
 end

data/app/controllers/solid_stack_web/failed_jobs/errors_controller.rb

@@ -0,0 +1,9 @@
+module SolidStackWeb
+  module FailedJobs
+    class ErrorsController < ApplicationController
+      def index
+        @groups = ErrorFrequencyReport.new.groups
+      end
+    end
+  end
+end

data/app/controllers/solid_stack_web/failed_jobs_controller.rb

@@ -4,6 +4,8 @@ module SolidStackWeb
       respond_to do |format|
         format.html do
           scope = ::SolidQueue::FailedExecution.includes(:job).order(created_at: :desc)
+          @error_class = params[:error_class].presence
+          scope = scope.where(id: ids_for_error_class(@error_class)) if @error_class
           @pagy, @executions = pagy(scope)
         end
         format.csv do
@@ -41,6 +43,15 @@ module SolidStackWeb
 
     private
 
+    def ids_for_error_class(ec)
+      ::SolidQueue::FailedExecution.pluck(:id, :error).filter_map do |id, raw|
+        error = raw.is_a?(Hash) ? raw : JSON.parse(raw)
+        id if error["exception_class"] == ec
+      rescue StandardError
+        nil
+      end
+    end
+
     def failed_jobs_csv
       CSV.generate(headers: true) do |csv|
         csv << %w[id class_name queue_name error_class error_message failed_at]

data/app/controllers/solid_stack_web/stats_controller.rb

@@ -1,6 +1,6 @@
 module SolidStackWeb
   class StatsController < ApplicationController
-    SORTABLE_COLUMNS = %w[class_name count avg p50 p95 min max].freeze
+    SORTABLE_COLUMNS = %w[class_name count avg p50 p95 p99 stddev min max].freeze
 
     def index
       @sort      = params[:sort].presence_in(SORTABLE_COLUMNS) || "p95"
@@ -18,14 +18,17 @@ module SolidStackWeb
       jobs.group_by(&:class_name).map do |class_name, group|
         durations = group.map { |j| (j.finished_at - j.created_at).to_f }.sort
         count     = durations.size
+        avg = durations.sum / count
         {
           class_name: class_name,
           count:      count,
-          avg:        durations.sum / count,
+          avg:        avg,
           min:        durations.first,
           max:        durations.last,
           p50:        percentile(durations, 50),
-          p95:        percentile(durations, 95)
+          p95:        percentile(durations, 95),
+          p99:        percentile(durations, 99),
+          stddev:     stddev(durations, avg)
         }
       end
     end
@@ -35,5 +38,11 @@ module SolidStackWeb
       k = (sorted.size - 1) * pct / 100.0
       sorted[k.floor] + (sorted[k.ceil] - sorted[k.floor]) * (k - k.floor)
     end
+
+    def stddev(durations, avg)
+      return 0.0 if durations.size < 2
+      variance = durations.sum { |d| (d - avg)**2 } / durations.size
+      Math.sqrt(variance)
+    end
   end
 end

data/app/helpers/solid_stack_web/application_helper.rb

@@ -87,6 +87,17 @@ module SolidStackWeb
       end
     end
 
+    def failed_job_sparkline_svg(sparkline)
+      build_sparkline_svg(sparkline, aria_label: "Failed jobs over the last 12 hours") do |count, i|
+        hours_ago = SolidStackWeb::FailedJobSparkline::HOURS - i
+        if hours_ago == 1
+          "#{count} #{count == 1 ? "failure" : "failures"} in the last hour"
+        else
+          "#{count} #{count == 1 ? "failure" : "failures"} (#{hours_ago}h–#{hours_ago - 1}h ago)"
+        end
+      end
+    end
+
     private
 
     def build_sparkline_svg(sparkline, css_class: "sqw-sparkline", aria_label: nil, &tooltip_text)

data/app/models/solid_stack_web/error_frequency_report.rb

@@ -0,0 +1,34 @@
+module SolidStackWeb
+  class ErrorFrequencyReport
+    Row = Data.define(:exception_class, :message_prefix, :count, :sample_backtrace)
+
+    MESSAGE_LIMIT = 120
+
+    def groups
+      ::SolidQueue::FailedExecution
+        .order(created_at: :desc)
+        .each_with_object({}) do |execution, acc|
+          key = [execution.exception_class.to_s, message_prefix(execution.message)]
+          entry = acc[key] ||= { count: 0, sample_backtrace: nil }
+          entry[:count] += 1
+          entry[:sample_backtrace] ||= execution.backtrace
+        end
+        .map do |(exception_class, prefix), data|
+          Row.new(
+            exception_class:  exception_class,
+            message_prefix:   prefix,
+            count:            data[:count],
+            sample_backtrace: data[:sample_backtrace]
+          )
+        end
+        .sort_by { |row| -row.count }
+    end
+
+    private
+
+    def message_prefix(message)
+      return "" if message.nil?
+      message.length > MESSAGE_LIMIT ? "#{message[0, MESSAGE_LIMIT]}…" : message
+    end
+  end
+end

data/app/models/solid_stack_web/failed_job_sparkline.rb

@@ -0,0 +1,23 @@
+module SolidStackWeb
+  class FailedJobSparkline
+    HOURS = 12
+
+    def buckets
+      @buckets ||= begin
+        now    = Time.current
+        origin = now - HOURS.hours
+        times  = ::SolidQueue::FailedExecution.where(created_at: origin..now).pluck(:created_at)
+
+        HOURS.times.map do |i|
+          from = origin + i.hours
+          to   = origin + (i + 1).hours
+          times.count { |t| t >= from && t < to }
+        end
+      end
+    end
+
+    def max
+      buckets.max || 0
+    end
+  end
+end

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

@@ -68,6 +68,18 @@
         <span>now</span>
       </div>
     </div>
+    <div class="sqw-sparkline-wrap sqw-sparkline-wrap--failures" data-controller="sparkline-tooltip">
+      <span class="sqw-sparkline-label">Failures — last 12 hours</span>
+      <div class="sqw-sparkline-positioner">
+        <%= failed_job_sparkline_svg(@failures) %>
+        <div class="sqw-sparkline-tip" data-sparkline-tooltip-target="tip" hidden></div>
+      </div>
+      <div class="sqw-sparkline-axis">
+        <span>12h ago</span>
+        <span>6h ago</span>
+        <span>now</span>
+      </div>
+    </div>
   </div>
 
   <div class="sqw-gem-card sqw-gem-card--cache">

data/app/views/solid_stack_web/failed_jobs/errors/index.html.erb

@@ -0,0 +1,48 @@
+<div class="sqw-page-header sqw-page-header--split">
+  <h1 class="sqw-page-title">Error Summary</h1>
+  <div class="sqw-header-actions">
+    <%= link_to "← Failed Jobs", failed_jobs_path, class: "sqw-btn sqw-btn--muted sqw-btn--sm" %>
+  </div>
+</div>
+
+<% if @groups.any? %>
+  <table class="sqw-table">
+    <thead>
+      <tr>
+        <th scope="col">Error Class</th>
+        <th scope="col">Message</th>
+        <th scope="col">Count</th>
+        <th scope="col"><span class="sqw-sr-only">Actions</span></th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @groups.each do |group| %>
+        <tr>
+          <td class="sqw-monospace"><%= group.exception_class.presence || "—" %></td>
+          <td>
+            <% if group.sample_backtrace.present? %>
+              <details class="sqw-error-details">
+                <summary class="sqw-muted sqw-truncate" title="<%= group.message_prefix %>">
+                  <%= group.message_prefix.presence || "—" %>
+                </summary>
+                <pre class="sqw-error-backtrace"><%= Array(group.sample_backtrace).first(10).join("\n") %></pre>
+              </details>
+            <% else %>
+              <span class="sqw-muted sqw-truncate" title="<%= group.message_prefix %>"><%= group.message_prefix.presence || "—" %></span>
+            <% end %>
+          </td>
+          <td><%= group.count %></td>
+          <td class="sqw-actions">
+            <%= link_to "View Jobs", failed_jobs_path(error_class: group.exception_class),
+                  class: "sqw-btn sqw-btn--muted sqw-btn--sm" %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% else %>
+  <div class="sqw-empty">
+    <p class="sqw-empty__title">No failed jobs</p>
+    <p class="sqw-empty__hint">All clear — your jobs are running without errors.</p>
+  </div>
+<% end %>

data/app/views/solid_stack_web/failed_jobs/index.html.erb

@@ -1,6 +1,15 @@
 <div class="sqw-page-header sqw-page-header--split">
-  <h1 class="sqw-page-title">Failed Jobs</h1>
+  <div>
+    <h1 class="sqw-page-title">Failed Jobs</h1>
+    <% if @error_class %>
+      <div class="sqw-breadcrumb">
+        Filtered by <span class="sqw-monospace"><%= @error_class %></span>
+        — <%= link_to "Clear filter", failed_jobs_path %>
+      </div>
+    <% end %>
+  </div>
   <div class="sqw-header-actions">
+    <%= link_to "Error Summary", failed_job_errors_path, class: "sqw-btn sqw-btn--muted sqw-btn--sm" %>
     <%= link_to "Export CSV", failed_jobs_path(format: :csv),
           class: "sqw-btn sqw-btn--muted sqw-btn--sm", data: { turbo: false } %>
   </div>

data/app/views/solid_stack_web/stats/index.html.erb

@@ -12,6 +12,8 @@
           ["avg",        "Avg"],
           ["p50",        "p50"],
           ["p95",        "p95"],
+          ["p99",        "p99"],
+          ["stddev",     "Std Dev"],
           ["min",        "Min"],
           ["max",        "Max"]
         ].each do |col, label| %>
@@ -35,6 +37,8 @@
           <td class="sqw-muted"><%= format_duration(row[:avg]) %></td>
           <td class="sqw-muted"><%= format_duration(row[:p50]) %></td>
           <td><strong><%= format_duration(row[:p95]) %></strong></td>
+          <td class="sqw-muted"><%= format_duration(row[:p99]) %></td>
+          <td class="sqw-muted"><%= format_duration(row[:stddev]) %></td>
           <td class="sqw-muted"><%= format_duration(row[:min]) %></td>
           <td class="sqw-muted"><%= format_duration(row[:max]) %></td>
         </tr>

data/config/routes.rb

@@ -20,6 +20,8 @@ SolidStackWeb::Engine.routes.draw do
     end
   end
 
+  get "failed_jobs/errors", to: "failed_jobs/errors#index", as: :failed_job_errors
+
   resources :failed_jobs, only: [:index, :show, :destroy] do
     member { post :retry }
     resource :arguments, only: [:update], controller: "failed_jobs/arguments"

data/lib/solid_stack_web/version.rb

@@ -1,3 +1,3 @@
 module SolidStackWeb
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_stack_web
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -160,6 +160,7 @@ files:
 - app/controllers/solid_stack_web/cache_entries_controller.rb
 - app/controllers/solid_stack_web/dashboard_controller.rb
 - app/controllers/solid_stack_web/failed_jobs/arguments_controller.rb
+- app/controllers/solid_stack_web/failed_jobs/errors_controller.rb
 - app/controllers/solid_stack_web/failed_jobs/selections_controller.rb
 - app/controllers/solid_stack_web/failed_jobs_controller.rb
 - app/controllers/solid_stack_web/history_controller.rb
@@ -187,6 +188,8 @@ files:
 - app/models/solid_stack_web/cache_size_stats.rb
 - app/models/solid_stack_web/cache_stats.rb
 - app/models/solid_stack_web/cache_timeline.rb
+- app/models/solid_stack_web/error_frequency_report.rb
+- app/models/solid_stack_web/failed_job_sparkline.rb
 - app/models/solid_stack_web/job.rb
 - app/models/solid_stack_web/queue_depth_sparkline.rb
 - app/models/solid_stack_web/queue_stats.rb
@@ -201,6 +204,7 @@ files:
 - app/views/solid_stack_web/errors/internal_server_error.html.erb
 - app/views/solid_stack_web/errors/not_found.html.erb
 - app/views/solid_stack_web/failed_jobs/destroy.turbo_stream.erb
+- app/views/solid_stack_web/failed_jobs/errors/index.html.erb
 - app/views/solid_stack_web/failed_jobs/index.html.erb
 - app/views/solid_stack_web/failed_jobs/show.html.erb
 - app/views/solid_stack_web/history/index.html.erb