solid_observer 0.5.0 → 0.6.0

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

@@ -1,140 +1,7 @@
 <% content_for :title, "Dashboard" %>
 
-<div class="so-dashboard">
-  <% queue_enabled = SolidObserver.config.solid_queue_enabled? %>
-  <% queue_status_class = queue_enabled ? "so-badge--success" : "so-badge--warning" %>
-
-  <div class="so-content__header">
-    <h1>Queue overview</h1>
-    <div class="so-queue-overview__intro">
-      <span class="so-badge so-badge--pill <%= queue_status_class %>">
-        <svg class="so-badge__dot" viewBox="0 0 6 6" aria-hidden="true">
-          <circle r="3" cx="3" cy="3" />
-        </svg>
-        <%= queue_enabled ? "Available" : "Unavailable" %>
-      </span>
-      <% if queue_enabled %>
-        <p class="so-queue-overview__hint">Selected range: <%= range_label(@range) %></p>
-      <% end %>
-    </div>
-  </div>
-
-  <% if !queue_enabled %>
-    <section class="so-card so-card--section" aria-labelledby="so-queue-unavailable-heading">
-      <h2 id="so-queue-unavailable-heading">Queue Unavailable</h2>
-      <p class="so-dashboard-section__meta so-dashboard-section__meta--idle">Queue component is disabled or not installed. Enable SolidQueue to access dashboard controls.</p>
-    </section>
-  <% else %>
-  <%# Zone A: Toolbar — range selector, Refresh, Live toggle, help disclosure %>
-  <div class="so-dashboard-toolbar" data-so-live data-so-poll-url="<%= poll_data_path %>">
-    <form action="<%= request.path %>" method="get" class="so-dashboard-toolbar__left">
-      <label for="so-range" class="so-card__label so-filters__label">Range</label>
-      <select id="so-range" name="range" data-so-range-select onchange="this.form.submit()">
-        <% SolidObserver::QueueStats::RANGES.each_key do |key| %>
-          <option value="<%= key %>" <%= "selected" if key == @range %>><%= key %></option>
-        <% end %>
-      </select>
-      <button type="button" class="so-btn so-btn--refresh" data-so-refresh aria-busy="false">Refresh data</button>
-      <span class="so-toolbar-freshness" data-so-freshness aria-live="polite"></span>
-      <input type="hidden" name="live" value="<%= @live ? 'on' : '' %>">
-    </form>
-    <div class="so-dashboard-toolbar__right">
-      <label class="so-toggle so-toggle--pill <%= "so-toggle--on" if @live %>">
-        <input type="checkbox" name="live" value="on" <%= "checked" if @live %> data-so-live-toggle>
-        <span class="so-toggle__track" aria-hidden="true">
-          <span class="so-toggle__thumb"></span>
-        </span>
-        <span class="so-toggle__label">Live</span>
-        <span class="so-toggle__sep" aria-hidden="true"> · </span>
-        <span class="so-toggle__cadence" aria-live="polite"><%= @live ? "5s" : "off" %></span>
-        <span class="so-toggle__dot" aria-hidden="true"></span>
-      </label>
-      <div class="so-help-wrapper" data-so-help-wrapper>
-        <button type="button" class="so-btn so-btn--help" data-so-help-btn aria-expanded="false" aria-controls="so-help-panel">(?)
-        </button>
-        <div id="so-help-panel" class="so-help-panel" data-so-help-panel hidden>
-          <p>Live mode polls every 5 seconds for current queue state. Throughput and chart data update only on range change or manual refresh.</p>
-        </div>
-      </div>
-    </div>
-  </div>
-
-  <%# Zone B: Right now — live state %>
-  <section class="so-dashboard-section" aria-labelledby="so-live-state-heading">
-    <div class="so-dashboard-section__header">
-      <h2 class="so-dashboard-section__title" id="so-live-state-heading">Right now</h2>
-      <span class="so-dashboard-section__meta"><span class="so-badge so-badge--pill so-badge--success"><svg class="so-badge__dot" viewBox="0 0 6 6" aria-hidden="true"><circle r="3" cx="3" cy="3" fill="var(--so-live-marker, var(--so-success))"/></svg></span> current</span>
-    </div>
-    <%= render "live_state", stats: @stats %>
-  </section>
-
-  <%# Zone C: Throughput in selected range %>
-  <% if persistence_mode? && @stats[:available] %>
-    <section class="so-dashboard-section" aria-labelledby="so-throughput-heading">
-      <div class="so-dashboard-section__header">
-        <h2 class="so-dashboard-section__title" id="so-throughput-heading">Throughput in selected range</h2>
-        <span class="so-dashboard-section__meta"><span class="so-badge so-badge--pill so-badge--info"><svg class="so-badge__dot" viewBox="0 0 6 6" aria-hidden="true"><circle r="3" cx="3" cy="3" fill="var(--so-range-marker, var(--so-info))"/></svg></span> <span data-so-range-copy><%= range_label(@range) %></span></span>
-      </div>
-      <%= render "throughput", stats: @stats, range: @range %>
-    </section>
-  <% end %>
-
-  <%# Zone D: Charts %>
-  <% if @stats[:available] %>
-    <section class="so-dashboard-section" aria-labelledby="so-chart-heading">
-      <div class="so-dashboard-section__header">
-        <h2 class="so-dashboard-section__title" id="so-chart-heading">Charts</h2>
-      </div>
-      <%= render "chart", range: @range %>
-    </section>
-  <% end %>
-
-  <%# Zone E: Per-queue table %>
-  <%= render "queue_table", stats: @stats, range: @range %>
-
-  <%# Zone F: Stability strip %>
-  <% if @stats[:available] && persistence_mode? %>
-    <section class="so-stability" data-so-zone="stability" aria-labelledby="so-stability-heading">
-      <span class="so-stability__label" id="so-stability-heading">Stability</span>
-      <%= stability_badge(@stats) %>
-      <span class="so-stability__detail"><%= stability_detail(@stats) %></span>
-      <%= link_to "View failures →", events_path(event_type: "job_failed"), class: "so-stability__link" %>
-    </section>
-  <% end %>
-
-  <%# Zone G: Recent Events %>
-  <% if @stats[:available] && persistence_mode? %>
-    <% if defined?(@recent_events) && @recent_events.present? %>
-      <div class="so-card">
-        <div class="so-card__label">Recent Events</div>
-        <table class="so-table so-table--card">
-          <caption class="sr-only">Recent queue events</caption>
-          <thead>
-            <tr>
-              <th>Event</th>
-              <th>Job Class</th>
-              <th>Queue</th>
-              <th>Time</th>
-            </tr>
-          </thead>
-          <tbody>
-            <% @recent_events.each do |event| %>
-              <tr>
-                <td><%= event.event_type.humanize %></td>
-                <td><%= event.job_class %></td>
-                <td><%= event.queue_name %></td>
-                <td><%= time_ago_in_words(event.recorded_at) %> ago</td>
-              </tr>
-            <% end %>
-          </tbody>
-        </table>
-      </div>
-    <% else %>
-      <div class="so-card">
-        <div class="so-card__label">Recent Events</div>
-        <p class="so-dashboard-section__meta so-dashboard-section__meta--empty-events">No recent events yet. Queue activity will appear here after jobs are enqueued, performed, or failed.</p>
-      </div>
-    <% end %>
-  <% end %>
-  <% end %>
-</div>
+<% if @component == "home" %>
+  <%= render "home", health: @health, feed: @feed %>
+<% else %>
+  <%= render "queue" %>
+<% end %>

data/app/views/solid_observer/events/index.html.erb

@@ -38,7 +38,12 @@
     <tbody>
       <% @events.each do |event| %>
         <tr>
-          <td><%= link_to event.event_type.humanize, event_path(event.id) %></td>
+          <td>
+            <%= link_to event.event_type.humanize, event_path(event.id) %>
+            <% if event.correlation_id.present? %>
+              <%= link_to "Trace →", trace_path(event.correlation_id), class: "so-trace__link" %>
+            <% end %>
+          </td>
           <td><%= event.job_class %></td>
           <td><%= event.queue_name %></td>
           <td><%= duration_with_semantic(event.duration, event.event_type) %></td>

data/app/views/solid_observer/traces/show.html.erb

@@ -0,0 +1,80 @@
+<% content_for :title, "Trace #{params[:id]}" %>
+
+<div class="so-trace">
+  <div class="so-back-link">
+    <%= link_to "← Back to Events", events_path, class: "so-btn" %>
+  </div>
+
+  <div class="so-content__header">
+    <h1>Trace <span class="so-trace__correlation"><%= params[:id] %></span></h1>
+  </div>
+
+  <% if @rows.any? %>
+    <p class="so-trace__meta">Showing newest <%= @rows.size %> events (maximum 100)</p>
+  <% end %>
+
+  <% if @unavailable_components.any? %>
+    <div class="so-flash so-flash--notice" role="status">
+      Some components could not be read: <%= @unavailable_components.map(&:to_s).sort.join(", ") %>. Showing available events only.
+    </div>
+  <% end %>
+
+  <% if @rows.any? %>
+    <% component_tones = {queue: "info", cache: "success", cable: "warning"} %>
+    <table class="so-table so-table--listing so-trace__table">
+      <caption class="sr-only">Trace timeline for correlation ID <%= params[:id] %></caption>
+      <thead>
+        <tr>
+          <th class="so-trace__time">Time</th>
+          <th class="so-trace__component">Component</th>
+          <th class="so-trace__event">Event</th>
+          <th class="so-trace__details">Details</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% @rows.each do |row| %>
+          <tr>
+            <td class="so-trace__time"><%= row[:recorded_at].strftime("%Y-%m-%d %H:%M:%S") %></td>
+            <td class="so-trace__component">
+              <% component_tone = component_tones[row[:component]] || "default" %>
+              <span class="so-badge so-badge--pill so-badge--<%= component_tone %>">
+                <svg class="so-badge__dot" viewBox="0 0 6 6" aria-hidden="true"><circle r="3" cx="3" cy="3" /></svg>
+                <%= row[:component].to_s.capitalize %>
+              </span>
+            </td>
+            <td class="so-trace__event"><%= row[:event_type] %></td>
+            <td class="so-trace__details">
+              <% if row[:event_type] == "cable_summary" %>
+                <%= row[:collapsed_count] %> additional Cable broadcast events collapsed
+              <% else %>
+                <% case row[:component]
+                   when :queue %>
+                  <%= [
+                    ("job=#{row[:job_class]}" if row[:job_class]),
+                    ("queue=#{row[:queue_name]}" if row[:queue_name]),
+                    ("duration=#{format_duration(row[:duration])}" if row[:duration])
+                  ].compact.join(" ") %>
+                <% when :cache %>
+                  <%= [
+                    ("hit=#{row[:hit]}" unless row[:hit].nil?),
+                    ("error=#{row[:error_class]}" if row[:error_class]),
+                    ("duration=#{format_duration(row[:duration])}" if row[:duration])
+                  ].compact.join(" ") %>
+                <% when :cable %>
+                  <%= [
+                    ("channel=#{row[:channel_class]}" if row[:channel_class]),
+                    ("error=#{row[:error_class]}" if row[:error_class]),
+                    ("duration=#{format_duration(row[:duration])}" if row[:duration]),
+                    ("collapsed=#{row[:collapsed_count]}" if row[:collapsed_count])
+                  ].compact.join(" ") %>
+                <% end %>
+              <% end %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% else %>
+    <%= render "solid_observer/shared/empty_state", message: "No events found for correlation ID #{params[:id]}. The trace may have expired, not yet recorded, or belong to an unavailable component." %>
+  <% end %>
+</div>

data/config/routes.rb

@@ -21,4 +21,5 @@ SolidObserver::Engine.routes.draw do
 
   resource :storage, only: %i[show]
   resources :events, only: %i[index show]
+  resources :traces, only: [:show]
 end

data/db/migrate/20260630000001_add_correlation_id_to_cache_events.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddCorrelationIdToCacheEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_column :solid_observer_cache_events, :correlation_id, :string, limit: 64
+    add_index :solid_observer_cache_events, :correlation_id, where: "correlation_id IS NOT NULL"
+  end
+end

data/db/migrate/20260630000002_add_correlation_id_to_cable_events.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddCorrelationIdToCableEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_column :solid_observer_cable_events, :correlation_id, :string, limit: 64
+    add_index :solid_observer_cable_events, :correlation_id, where: "correlation_id IS NOT NULL"
+  end
+end

data/lib/generators/solid_observer/templates/initializer.rb.tt

@@ -41,6 +41,9 @@ SolidObserver.configure do |config|
   # config.cable_rejection_threshold = 0.05   # Rejection rate → Degraded stability
   # config.cable_backlog_threshold = 0.10     # Backlog ratio threshold
   # config.cable_error_threshold = 0.0        # Error rate threshold
+# === Trace & Health Observability (v0.6.0) ===
+# Health scoring (Services::HealthScore) is auto-computed and config-free.
+# Cross-component trace lookup uses correlation_id across Queue, Cache, and Cable.
 
   # Data Retention
   config.event_retention = 30.days    # How long to keep event records
@@ -57,9 +60,10 @@ SolidObserver.configure do |config|
   # Sampling (reduce overhead in high-traffic apps)
   config.sampling_rate = 1.0  # 1.0 = 100% (capture all events)
 
-  # Correlation ID (for distributed tracing)
+  # Correlation ID (for cross-component tracing & APM integration)
+  # Stamped correlation_id powers `rails solid_observer:trace[CORRELATION_ID]` CLI
+  # and the Web UI at /solid_observer/traces/:correlation_id.
   # Integrate with your APM tool (Datadog, Sentry, OpenTelemetry, etc.)
-  # config.correlation_id_generator = -> {
   #   # Example for Datadog APM
   #   Datadog::Tracing.active_trace&.id
   #

data/lib/solid_observer/cli/health.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Health < Base
+      STATUS_COLORS = {stable: :green, degraded: :yellow, critical: :red}.freeze
+      NAME_WIDTH = 8
+      UNAVAILABLE_SUFFIX = "  (unavailable)"
+
+      def call
+        health = SolidObserver::Services::HealthScore.call
+
+        print_header
+        print_overall(health[:overall])
+        print_components(health[:components])
+        output("")
+      end
+
+      private
+
+      def print_header
+        output("\n🩺 SolidObserver Health", color: :red)
+        output("=" * 50, color: :red)
+        output("")
+      end
+
+      def print_overall(overall)
+        output("Overall: #{overall}", color: STATUS_COLORS[overall])
+        output("")
+      end
+
+      def print_components(components)
+        return warning("⚠️  No components enabled") if components.empty?
+
+        output("Components", color: :green)
+        output("")
+        components.each { |name, entry| print_component(name, entry[:status], entry[:available]) }
+      end
+
+      # Renders the status verbatim: HealthScore owns the worst-of ladder, so an
+      # unrecognised status stays uncoloured rather than being coerced to stable.
+      # :reek:ControlParameter
+      def print_component(name, status, available)
+        suffix = available ? "" : UNAVAILABLE_SUFFIX
+        output("  #{name.to_s.ljust(NAME_WIDTH)}#{status}#{suffix}", color: STATUS_COLORS[status])
+      end
+    end
+  end
+end

data/lib/solid_observer/cli/trace.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module CLI
+    class Trace < Base
+      DETAIL_FORMATTERS = {
+        queue: :format_queue_details,
+        cache: :format_cache_details,
+        cable: :format_cable_details
+      }.freeze
+
+      EVENT_FORMATTERS = {
+        "cable_summary" => ->(row) { "and #{row[:collapsed_count]} more cable events" }
+      }.freeze
+
+      def call(correlation_id:, limit: nil)
+        return output("Trace unavailable in realtime mode.") if SolidObserver.config.realtime_mode?
+
+        result = SolidObserver::Queries::TraceQuery.new.call(correlation_id: correlation_id, limit: limit)
+        return warning("No events found for correlation_id: #{correlation_id}") if (rows = result.rows).empty?
+
+        print_trace_table(rows)
+        print_unavailable_components(result.unavailable_components)
+      end
+
+      private
+
+      def print_trace_table(rows)
+        print_section_header("Trace")
+        table(
+          headers: ["Time", "Component", "Event", "Details"],
+          rows: rows.map { |row| format_cells(row) }
+        )
+        output("")
+      end
+
+      def print_unavailable_components(unavailable)
+        unavailable.each { |component| warning("#{component} unavailable") }
+      end
+
+      def format_cells(row)
+        recorded_at, component, event_type = row.values_at(:recorded_at, :component, :event_type)
+        [
+          format_time(recorded_at),
+          component.to_s,
+          event_type,
+          format_details(row)
+        ]
+      end
+
+      def format_details(row)
+        event_type, component = row.values_at(:event_type, :component)
+        event_formatter = EVENT_FORMATTERS[event_type]
+        return event_formatter.call(row) if event_formatter
+
+        component_formatter = DETAIL_FORMATTERS[component]
+        send(component_formatter, row) if component_formatter
+      end
+
+      def format_queue_details(row)
+        job_class, queue_name, duration = row.values_at(:job_class, :queue_name, :duration)
+        [label("job", job_class), label("queue", queue_name), duration_part(duration)].compact.join(" ")
+      end
+
+      def format_cache_details(row)
+        hit, error_class, duration = row.values_at(:hit, :error_class, :duration)
+        [hit_part(hit), error_part(error_class), duration_part(duration)].compact.join(" ")
+      end
+
+      def format_cable_details(row)
+        channel_class, duration, error_class, collapsed_count = row.values_at(:channel_class, :duration, :error_class, :collapsed_count)
+        [label("channel", channel_class), error_part(error_class), duration_part(duration), ("collapsed=#{collapsed_count}" if collapsed_count)].compact.join(" ")
+      end
+
+      def label(name, value)
+        "#{name}=#{value}" if value
+      end
+
+      def error_part(error_class)
+        "error=#{error_class}" if error_class
+      end
+
+      def hit_part(hit)
+        "hit=#{hit}" if [true, false].include?(hit)
+      end
+
+      def duration_part(duration)
+        "duration=#{format_duration(duration)}" if duration
+      end
+
+      def format_duration(duration)
+        duration ? "#{duration.round(3)}s" : nil
+      end
+
+      def format_time(time)
+        time.strftime("%Y-%m-%d %H:%M:%S")
+      end
+
+      def print_section_header(title)
+        output("\n#{title}", color: :red)
+        output("=" * 50, color: :red)
+        output("")
+      end
+    end
+  end
+end

data/lib/solid_observer/configuration.rb

@@ -21,8 +21,7 @@ module SolidObserver
     # Observer Settings
     attr_accessor :observe_queue
 
-    # Observer Settings (planned for a future release)
-    # @note Cable observer is not yet fully implemented
+    # Cache & Cable Observer Settings
     attr_accessor :observe_cache,
       :observe_cable,
       :cache_sampling_rate,
@@ -36,8 +35,6 @@ module SolidObserver
     # Retention Settings
     attr_accessor :event_retention
 
-    # Retention Settings (planned for a future release)
-    # @note Metrics cleanup is not yet implemented
     attr_accessor :metrics_retention
 
     # Storage Settings

data/lib/solid_observer/correlated.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Correlated
+    def self.included(base)
+      base.around_perform do |job, block|
+        SolidObserver::Correlated.stamp(job.job_id) { block.call }
+      end
+    end
+
+    def self.stamp(correlation_id)
+      thread_local = Thread.current
+      previous = thread_local[:solid_observer_correlation_id]
+      thread_local[:solid_observer_correlation_id] = correlation_id if correlation_id.present?
+
+      yield
+    ensure
+      thread_local[:solid_observer_correlation_id] = previous
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_job) { include SolidObserver::Correlated }

data/lib/solid_observer/queries/trace_query.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module SolidObserver
+  module Queries
+    class TraceQuery
+      DEFAULT_LIMIT = 100
+      CABLE_CAP = 50
+
+      Result = Struct.new(:rows, :unavailable_components, keyword_init: true)
+
+      COMPONENT_PRIORITY = {queue: 0, cache: 1, cable: 2}.freeze
+
+      COMPONENT_CONFIG = {
+        queue: {
+          enabled: :solid_queue_enabled?,
+          model: :QueueEvent,
+          columns: [:recorded_at, :event_type, :job_class, :queue_name, :duration, :id]
+        },
+        cache: {
+          enabled: :solid_cache_enabled?,
+          model: :CacheEvent,
+          columns: [:recorded_at, :event_type, :hit, :error_class, :duration, :id]
+        },
+        cable: {
+          enabled: :solid_cable_enabled?,
+          model: :CableEvent,
+          columns: [:recorded_at, :event_type, :channel_class, :broadcasting_digest, :error_class, :duration, :id]
+        }
+      }.freeze
+
+      CONNECTION_ERRORS = [
+        ActiveRecord::ConnectionNotEstablished,
+        ActiveRecord::StatementInvalid,
+        *([PG::ConnectionBad] if defined?(PG::ConnectionBad)),
+        *([Mysql2::Error::ConnectionError] if defined?(Mysql2::Error::ConnectionError)),
+        *([Trilogy::Error] if defined?(Trilogy::Error)),
+        *([SQLite3::CantOpenException] if defined?(SQLite3::CantOpenException))
+      ].freeze
+
+      def call(correlation_id:, limit: DEFAULT_LIMIT)
+        rows, unavailable = gather_rows(correlation_id)
+        effective_limit = limit.to_i
+        effective_limit = DEFAULT_LIMIT unless effective_limit.positive?
+        Result.new(rows: process_rows(rows, effective_limit), unavailable_components: unavailable)
+      end
+
+      private
+
+      def gather_rows(correlation_id)
+        COMPONENT_CONFIG.each_with_object([[], []]) do |(component, config), (rows, unavailable)|
+          next unless SolidObserver.config.public_send(config[:enabled])
+
+          component_rows = fetch_component_rows(component, config, correlation_id)
+          component_rows ? rows.concat(component_rows) : unavailable << component
+        end
+      end
+
+      def fetch_component_rows(component, config, correlation_id)
+        model = SolidObserver.const_get(config[:model])
+        return nil unless data_source_available?(model)
+
+        pluck_rows(model, component, correlation_id)
+      rescue *CONNECTION_ERRORS, TypeError
+        nil
+      end
+
+      def data_source_available?(model)
+        table_name = model.table_name.to_s
+        table_name.present? && model.connection.data_source_exists?(table_name)
+      end
+
+      def pluck_rows(model, component, correlation_id)
+        columns = COMPONENT_CONFIG[component][:columns]
+        model.where(correlation_id: correlation_id)
+          .order(:recorded_at)
+          .pluck(*columns)
+          .map { |values| build_row(component, columns, values) }
+      end
+
+      def build_row(component, columns, values)
+        row = {component: component}
+        columns.each_with_index { |column, index| row[column] = values[index] }
+        row
+      end
+
+      def process_rows(rows, limit)
+        collapsed = collapse_cable_rows(rows)
+        capped = apply_cable_cap(collapsed)
+        sorted = sort_rows(capped)
+        return sorted if capped.size <= limit
+
+        sort_rows(sorted.last(limit))
+      end
+
+      def collapse_cable_rows(rows)
+        cable_rows, other_rows = rows.partition { |row| row[:component] == :cable }
+        return rows if cable_rows.empty?
+
+        other_rows + cable_rows.chunk_while(&method(:collapse_match?)).map(&method(:collapse_group))
+      end
+
+      def collapse_match?(first_row, second_row)
+        return false unless first_row[:event_type] == "broadcast" && second_row[:event_type] == "broadcast"
+
+        digest = first_row[:broadcasting_digest]
+        digest.present? && digest == second_row[:broadcasting_digest]
+      end
+
+      def collapse_group(group)
+        row = group.first
+        size = group.size
+        row[:collapsed_count] = size if size > 1
+        row.delete(:broadcasting_digest)
+        row
+      end
+
+      def apply_cable_cap(rows)
+        cable_rows, other_rows = rows.partition { |row| row[:component] == :cable }
+        total = cable_rows.size
+        return rows if total <= CABLE_CAP
+
+        other_rows + cap_cable_rows(cable_rows, total)
+      end
+
+      def cap_cable_rows(cable_rows, total)
+        keep_count = CABLE_CAP - 1
+        [build_summary_row(cable_rows.first(total - keep_count))] + tail_rows(cable_rows, keep_count)
+      end
+
+      def tail_rows(rows, count)
+        rows.last(count)
+      end
+
+      def build_summary_row(overflow)
+        {
+          recorded_at: overflow.last[:recorded_at],
+          component: :cable,
+          event_type: "cable_summary",
+          duration: nil,
+          channel_class: nil,
+          collapsed_count: overflow.size,
+          id: -1
+        }
+      end
+
+      def sort_rows(rows)
+        rows.sort_by { |row| [row[:recorded_at], COMPONENT_PRIORITY[row[:component]], row[:id] || 0] }
+      end
+    end
+  end
+end