railwatch 0.1.4 → 0.2.0

data/app/models/railwatch/issue_detection_presenter.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Builds the same discriminated performance/anomaly detail contract for the
+  # Inertia page, REST API, and MCP. The durable detector snapshot remains useful
+  # after raw data is pruned; live rollups add trend and deploy comparison when
+  # they are still available.
+  class IssueDetectionPresenter
+    TREND_DAYS = 30
+    DEPLOY_LIMIT = 20
+    EXECUTION_TYPES = IssueDetectionSnapshot::EXECUTION_TYPES
+    SCHEMA_VERSION = 1
+    NUMERIC_FIELDS = {
+      "measurement" => %w[value limit],
+      "baseline" => %w[mean stddev sigmas days deviation]
+    }.freeze
+    RULE_STRING_FIELDS = %w[type target_kind target task_key schedule last_run expected].freeze
+    EXECUTION_SOURCES = %w[request job job_attempt scheduled_task command].freeze
+    CHILD_TYPES = %w[query outgoing_request].freeze
+    TARGET_KIND_FOR = {
+      "request" => "requests", "job_attempt" => "jobs", "command" => "commands",
+      "query" => "queries", "scheduled_task" => "scheduled_tasks",
+      "outgoing_request" => "outgoing_requests"
+    }.freeze
+
+    def initialize(issue)
+      @issue = issue
+      @details = issue.sample["detection"]
+    end
+
+    def as_json
+      return unless @issue.kind.in?(%w[performance anomaly])
+      return unavailable_json unless @details.is_a?(Hash)
+
+      validate_details!
+      live = @issue.environment.with_telemetry { live_details }
+      @details.deep_symbolize_keys.merge(
+        available: true,
+        count_label: "Breached evaluation windows",
+        breached_windows: @issue.occurrences,
+        event_count: live[:event_count],
+        trend: live[:trend],
+        deploy_comparison: live[:deploy_comparison],
+        representative_references: representative_references,
+        representative_records: representatives
+      )
+    rescue KeyError, ArgumentError, TypeError
+      unavailable_json
+    end
+
+    private
+
+    def unavailable_json
+      {
+        kind: @issue.kind, available: false,
+        count_label: "Breached evaluation windows", breached_windows: @issue.occurrences,
+        message: "Typed detector context was not captured for this historical issue."
+      }
+    end
+
+    def validate_details!
+      raise ArgumentError unless @details.fetch("schema_version") == SCHEMA_VERSION
+      raise ArgumentError unless @details.fetch("kind") == @issue.kind
+      telemetry_type = @details.fetch("telemetry_type")
+      raise ArgumentError unless telemetry_type.in?(EXECUTION_TYPES + %w[query outgoing_request])
+      target_kind = TARGET_KIND_FOR.fetch(telemetry_type)
+      allowed_target_kinds = @issue.kind == "anomaly" ? AnomalyRule::TARGET_KINDS : Threshold::TARGET_KINDS
+      raise ArgumentError unless target_kind.in?(allowed_target_kinds)
+      %w[telemetry_group_hash target metric unit].each do |key|
+        raise ArgumentError unless @details.fetch(key).is_a?(String) && @details.fetch(key).present?
+      end
+      metric = @details.fetch("metric")
+      allowed_metrics = @issue.kind == "anomaly" ? AnomalyRule::METRICS : Threshold::METRICS
+      raise ArgumentError unless metric.in?(allowed_metrics)
+      raise ArgumentError if metric == "missed" && @details.fetch("telemetry_type") != "scheduled_task"
+      expected_unit = IssueDetectionSnapshot::UNITS[metric]
+      raise ArgumentError unless expected_unit && @details.fetch("unit") == expected_unit
+      validate_window!
+      NUMERIC_FIELDS.each { |key, fields| validate_numeric_object!(key, fields) }
+      validate_rule!
+      validate_detector_shape!
+      validate_representatives!
+    end
+
+    def validate_window!
+      window = @details.fetch("window")
+      raise ArgumentError unless window.is_a?(Hash)
+      from = Time.iso8601(window.fetch("from"))
+      to = Time.iso8601(window.fetch("to"))
+      minutes = window.fetch("minutes")
+      raise ArgumentError unless finite_number?(minutes) && minutes.positive? && to > from
+      raise ArgumentError unless (minutes - ((to - from) / 60.0).round(2)).abs <= 0.01
+      return if @details.fetch("metric") == "missed"
+
+      raise ArgumentError unless minutes == minutes.to_i
+      maximum = @issue.kind == "anomaly" ? AnomalyRule::MAX_WINDOW_MINUTES : Threshold::MAX_WINDOW_MINUTES
+      raise ArgumentError if minutes > maximum
+    end
+
+    def validate_numeric_object!(key, fields)
+      value = @details[key]
+      return if value.nil?
+      raise ArgumentError unless value.is_a?(Hash)
+      fields.each { |field| raise ArgumentError if value.key?(field) && !finite_number?(value[field]) }
+      if key == "measurement"
+        %w[value limit].each { |field| raise ArgumentError if value.key?(field) && value[field].negative? }
+        raise ArgumentError if value.key?("limit") && !value["limit"].positive?
+      else
+        %w[mean stddev].each { |field| raise ArgumentError if value.key?(field) && value[field].negative? }
+        raise ArgumentError if value.key?("days") && (!value["days"].is_a?(Integer) || !value["days"].positive?)
+        raise ArgumentError if value.key?("deviation") && !value["deviation"].positive?
+      end
+    end
+
+    def validate_rule!
+      rule = @details["rule"]
+      if rule.nil?
+        raise ArgumentError if @details.fetch("metric") == "missed"
+        return
+      end
+      raise ArgumentError unless rule.is_a?(Hash)
+      RULE_STRING_FIELDS.each do |field|
+        raise ArgumentError if rule.key?(field) && (!rule[field].is_a?(String) || rule[field].blank?)
+      end
+      raise ArgumentError if rule.key?("id") && (!rule["id"].is_a?(Integer) || !rule["id"].positive?)
+      %w[last_run expected].each { |field| Time.iso8601(rule[field]) if rule.key?(field) }
+      return unless @details.fetch("metric") == "missed"
+
+      raise ArgumentError unless rule["type"] == "schedule"
+      %w[task_key schedule last_run expected].each { |field| raise ArgumentError unless rule[field].is_a?(String) && rule[field].present? }
+    end
+
+    def validate_detector_shape!
+      if @issue.kind == "anomaly"
+        require_numeric_fields!("measurement", %w[value])
+        baseline = require_numeric_fields!("baseline", %w[mean stddev sigmas days deviation])
+        raise ArgumentError unless baseline.fetch("sigmas").positive?
+        raise ArgumentError unless baseline.fetch("days").between?(
+          AnomalyRule::MIN_BASELINE_DAYS, AnomalyRule::MAX_BASELINE_DAYS
+        )
+        raise ArgumentError if baseline.fetch("deviation") > AnomalyRule::MAX_DEVIATION
+        require_detector_rule!("anomaly")
+      elsif @details.fetch("metric") != "missed"
+        measurement = require_numeric_fields!("measurement", %w[value limit])
+        raise ArgumentError if measurement.fetch("limit") > Threshold::MAX_LIMIT
+        raise ArgumentError if @details.fetch("metric").end_with?("rate") && measurement.fetch("limit") > 100
+        require_detector_rule!("threshold")
+      end
+    end
+
+    def require_numeric_fields!(key, fields)
+      object = @details.fetch(key)
+      raise ArgumentError unless object.is_a?(Hash)
+      fields.each { |field| raise ArgumentError unless finite_number?(object.fetch(field)) }
+      object
+    end
+
+    def require_detector_rule!(type)
+      rule = @details.fetch("rule")
+      raise ArgumentError unless rule.is_a?(Hash) && rule.fetch("type") == type
+      raise ArgumentError unless rule.fetch("id").is_a?(Integer) && rule.fetch("id").positive?
+      raise ArgumentError unless rule.fetch("target").is_a?(String) && rule.fetch("target").present?
+      expected_target_kind = TARGET_KIND_FOR.fetch(@details.fetch("telemetry_type"))
+      raise ArgumentError unless rule.fetch("target_kind") == expected_target_kind
+    end
+
+    def validate_representatives!
+      references = @details.fetch("representative_records", [])
+      raise ArgumentError unless references.is_a?(Array) && references.size <= IssueDetectionSnapshot::REPRESENTATIVE_LIMIT
+
+      references.each do |reference|
+        raise ArgumentError unless reference.is_a?(Hash)
+        raise ArgumentError unless reference["record_type"] == @details.fetch("telemetry_type")
+        raise ArgumentError unless reference["record_id"].is_a?(Integer) && reference["record_id"].positive?
+        raise ArgumentError unless reference["group_hash"] == @details.fetch("telemetry_group_hash")
+        execution_id = reference["execution_id"]
+        raise ArgumentError unless execution_id.nil? || (execution_id.is_a?(String) && execution_id.present?)
+        raise ArgumentError if reference["record_type"] != "query" && execution_id.blank?
+        source = reference["execution_source"]
+        if CHILD_TYPES.include?(reference["record_type"])
+          raise ArgumentError unless source.is_a?(String) && source.present? && source.in?(EXECUTION_SOURCES)
+        else
+          raise ArgumentError unless source == reference["record_type"]
+        end
+      end
+    end
+
+    def finite_number?(value)
+      value.is_a?(Numeric) && (!value.respond_to?(:finite?) || value.finite?)
+    end
+
+    def live_details
+      type = @details.fetch("telemetry_type")
+      group_hash = @details.fetch("telemetry_group_hash")
+      window = @details.fetch("window")
+      from = Time.iso8601(window.fetch("from"))
+      to = Time.iso8601(window.fetch("to"))
+      rollups = Telemetry::Rollup.for_type(type).where(group_hash: group_hash)
+      window_summary = Telemetry::Rollup.summarize(rollups.between(from, to))
+      now = Time.current
+      # Rollup.between includes the whole lower-bound hour, so the denominator
+      # for count rates must begin at that same boundary.
+      trend_from = (now - TREND_DAYS.days).beginning_of_hour
+      trend_rows = rollups.between(trend_from, now).order(:bucket).to_a.group_by { |row| row.bucket.to_date }
+      {
+        event_count: window_summary[:count],
+        trend: trend_rows.map { |day, rows| trend_point(day, rows, trend_from, now) },
+        deploy_comparison: deploy_comparison(type, group_hash)
+      }
+    end
+
+    def trend_point(day, rows, trend_from, now)
+      summary = Telemetry::Rollup.summarize(rows)
+      day_start = day.in_time_zone.beginning_of_day
+      minutes = ([ day_start + 1.day, now ].min - [ day_start, trend_from ].max) / 60.0
+      { day: day.iso8601, value: metric_value(@details.fetch("metric"), summary, minutes: minutes), count: summary[:count] }
+    end
+
+    def metric_value(metric, summary, minutes: nil)
+      case metric
+      when "p95" then milliseconds(summary[:p95])
+      when "max" then milliseconds(summary[:max])
+      when "avg" then milliseconds(summary[:avg])
+      when "error_rate", "failure_rate"
+        summary[:count].zero? ? nil : (summary[:errors] * 100.0 / summary[:count]).round(2)
+      when "count" then minutes&.positive? ? (summary[:count] / minutes).round(2) : nil
+      end
+    end
+
+    def deploy_comparison(type, group_hash)
+      scope = record_scope(type, group_hash).where(occurred_at: TREND_DAYS.days.ago..).where.not(deploy: nil)
+      scope.group(:deploy).pluck(:deploy, Arel.sql("COUNT(*)"), Arel.sql("AVG(duration)"), Arel.sql("MAX(duration)"))
+        .map { |deploy, count, avg, max| { deploy: deploy, events: count, avg_ms: milliseconds(avg), max_ms: milliseconds(max) } }
+        .sort_by { |row| -row[:events] }.first(DEPLOY_LIMIT)
+    end
+
+    def record_scope(type, group_hash)
+      if type.in?(EXECUTION_TYPES)
+        Telemetry::Execution.of_kind(type).where(group_hash: group_hash)
+      elsif type == "query"
+        Telemetry::Query.where(group_hash: group_hash).with_sql
+      elsif type == "outgoing_request"
+        Telemetry::OutgoingRequest.where(group_hash: group_hash)
+      else
+        raise ArgumentError, "unsupported detection telemetry type: #{type}"
+      end
+    end
+
+    def representatives
+      references = Array(@details["representative_records"]).select { |record| record.is_a?(Hash) }
+      return [] if references.empty?
+
+      type = @details.fetch("telemetry_type")
+      group_hash = @details.fetch("telemetry_group_hash")
+      records = @issue.environment.with_telemetry do
+        record_scope(type, group_hash).where(id: references.filter_map { |record| record["record_id"] }).index_by(&:id)
+      end
+      references.filter_map do |reference|
+        record = records[reference["record_id"]]
+        record_json(record, type)&.merge(drilldown: drilldown(reference))
+      end
+    end
+
+    def representative_references
+      Array(@details["representative_records"]).filter_map do |reference|
+        next unless reference.is_a?(Hash)
+        reference.slice("record_type", "record_id", "group_hash", "execution_id", "execution_source").deep_symbolize_keys
+          .merge(drilldown: drilldown(reference))
+      end
+    end
+
+    def record_json(record, type)
+      return unless record
+
+      common = {
+        record_type: type, record_id: record.id, group_hash: record.group_hash,
+        execution_id: record.execution_id, execution_source: record.execution_source,
+        execution_preview: record.execution_preview, occurred_at: record.occurred_at,
+        duration_ms: milliseconds(record.duration), deploy: record.deploy,
+        user_ref: record.user_ref, tenant: record.app_tenant
+      }
+      case record
+      when Telemetry::Execution
+        common.merge(name: record.name, status: record.status, outcome: record.outcome)
+      when Telemetry::Query
+        common.merge(name: record.sql.to_s.first(300), source: record.source,
+          connection: record.connection, role: record.role)
+      when Telemetry::OutgoingRequest
+        common.merge(name: "#{record.method} #{record.host}", status: record.status_code,
+          source: record.source)
+      end
+    end
+
+    # Identifiers only: app/frontend/lib/execution-path.ts turns these into
+    # links, and it already accepts both the "job" child wire name and the
+    # "job_attempt" parent kind.
+    def drilldown(record)
+      if record["record_type"] == "query"
+        { kind: "query", group_hash: record["group_hash"] }
+      elsif record["execution_id"].present?
+        { kind: record["execution_source"].presence || record["record_type"], execution_id: record["execution_id"] }
+      end
+    end
+
+    def milliseconds(value)
+      value.nil? ? nil : (value.to_f / 1000.0).round(3)
+    end
+  end
+end

data/app/models/railwatch/issue_detection_snapshot.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Durable, typed context for synthetic performance/anomaly issues. Detector
+  # group hashes identify the rule, not the telemetry rows behind the breach;
+  # this snapshot preserves that original identity and a bounded set of
+  # drill-down identifiers even after raw telemetry is pruned. Record payloads
+  # remain subject to the telemetry retention policy and are never copied into
+  # the primary database.
+  class IssueDetectionSnapshot
+    REPRESENTATIVE_LIMIT = 10
+    EXECUTION_TYPES = %w[request job_attempt scheduled_task command].freeze
+    UNITS = {
+      "p95" => "milliseconds", "max" => "milliseconds", "avg" => "milliseconds",
+      "error_rate" => "percent", "failure_rate" => "percent", "count" => "events_per_minute",
+      "missed" => "schedule"
+    }.freeze
+
+    def self.capture(environment:, kind:, telemetry_type:, telemetry_group_hash:, target:, metric:, from:, to:,
+      value: nil, limit: nil, baseline: nil, rule: {}, representative_from: nil)
+      new(environment, telemetry_type, telemetry_group_hash).capture(
+        kind: kind, target: target, metric: metric, from: from, to: to,
+        value: value, limit: limit, baseline: baseline, rule: rule, representative_from: representative_from
+      )
+    end
+
+    def initialize(environment, telemetry_type, telemetry_group_hash)
+      @environment = environment
+      @telemetry_type = telemetry_type
+      @telemetry_group_hash = telemetry_group_hash
+    end
+
+    def capture(kind:, target:, metric:, from:, to:, value:, limit:, baseline:, rule:, representative_from:)
+      representatives = @environment.with_telemetry do
+        representative_scope(representative_from || from, to).order(duration: :desc).limit(REPRESENTATIVE_LIMIT)
+          .map { |record| record_json(record) }
+      end
+      {
+        schema_version: 1, kind: kind, telemetry_type: @telemetry_type,
+        telemetry_group_hash: @telemetry_group_hash, target: target, metric: metric,
+        unit: UNITS.fetch(metric, "value"),
+        window: { from: from.iso8601(6), to: to.iso8601(6), minutes: ((to - from) / 60.0).round(2) },
+        measurement: { value: value, limit: limit }.compact,
+        baseline: baseline&.compact,
+        rule: rule.compact,
+        representative_records: representatives
+      }.compact
+    end
+
+    private
+
+    def representative_scope(from, to)
+      model = record_model
+      # SQLite compares its stored six-digit timestamp strings lexically. A
+      # frozen whole-second upper bound serializes without the fraction and
+      # would otherwise exclude a record at that exact instant.
+      scope = model.where(group_hash: @telemetry_group_hash, occurred_at: from...(to + 1.second))
+      EXECUTION_TYPES.include?(@telemetry_type) ? scope.of_kind(@telemetry_type) : scope
+    end
+
+    def record_model
+      return Telemetry::Execution if EXECUTION_TYPES.include?(@telemetry_type)
+      return Telemetry::Query if @telemetry_type == "query"
+      return Telemetry::OutgoingRequest if @telemetry_type == "outgoing_request"
+
+      raise ArgumentError, "unsupported detection telemetry type: #{@telemetry_type}"
+    end
+
+    def record_json(record)
+      {
+        record_type: @telemetry_type, record_id: record.id, group_hash: record.group_hash,
+        execution_id: record.execution_id,
+        execution_source: record.is_a?(Telemetry::Execution) ? record.kind : record.execution_source
+      }
+    end
+  end
+end

data/app/models/railwatch/maintenance_task.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # One row per maintenance task (Railwatch::Maintenance::TASKS): when it last
+  # ran and who holds it now. Every process on the host runs the maintenance
+  # clock; this is how exactly one of them runs each task. The claim is a
+  # single conditional UPDATE, so SQLite's write lock is the arbiter and there
+  # is no window between checking and taking the lease.
+  class MaintenanceTask < ApplicationRecord
+    self.table_name = "railwatch_maintenance_tasks"
+
+    # The token for a claim this process won, or nil: the task is due
+    # (last_run_at older than `every`, or never) and nobody holds a live
+    # lease on it. A lease left by a process that died expires on its own.
+    # The token is per claim, not per process, so a claim that outlived its
+    # lease cannot later release the lease the next claimant holds.
+    def self.claim(name, every:, lease:, owner:, now: Time.current)
+      ensure_row(name)
+      token = "#{owner}:#{SecureRandom.hex(8)}"
+      won = where(name: name)
+        .where("lease_expires_at IS NULL OR lease_expires_at < ?", now)
+        .where("last_run_at IS NULL OR last_run_at <= ?", now - every)
+        .update_all(lease_owner: token, lease_expires_at: now + lease, updated_at: now) == 1
+      won ? token : nil
+    end
+
+    # Releases only the lease this token holds. A task that succeeded records
+    # the run so the interval starts again; one that failed records nothing,
+    # so it is eligible on the next tick rather than a full interval later.
+    def self.release(name, token:, ran_at:, succeeded:)
+      changes = { lease_owner: nil, lease_expires_at: nil, updated_at: ran_at }
+      changes[:last_run_at] = ran_at if succeeded
+      where(name: name, lease_owner: token).update_all(changes)
+    end
+
+    # The newest tick across every task: what the doctor reports as "last
+    # maintenance", and the signal that the clock is alive somewhere.
+    def self.last_tick_at
+      maximum(:last_run_at)
+    end
+
+    # Two processes racing to create the same row: one loses on the unique
+    # index, and the row it wanted now exists.
+    def self.ensure_row(name)
+      return if exists?(name: name)
+
+      create!(name: name)
+    rescue ActiveRecord::RecordNotUnique
+      nil
+    end
+    private_class_method :ensure_row
+  end
+end

data/app/models/railwatch/saved_view.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # A named, shareable filter on one environment page: "5xx checkout requests",
+  # "acme tenant logs". Pinned views appear in the sidebar under the page.
+  class SavedView < ApplicationRecord
+    self.table_name = "railwatch_saved_views"
+    # page => the index route helper the view links back to. The link is built
+    # server-side so the sidebar, the menu, and a pasted URL all agree.
+    PAGE_PATHS = {
+      "requests" => :application_environment_requests_path,
+      "jobs" => :application_environment_jobs_path,
+      "scheduled_tasks" => :application_environment_scheduled_tasks_path,
+      "commands" => :application_environment_commands_path,
+      "exceptions" => :application_environment_exceptions_path,
+      "queries" => :application_environment_queries_path,
+      "spans" => :application_environment_spans_path,
+      "logs" => :application_environment_logs_path,
+      "visits" => :application_environment_visits_path,
+      "people" => :application_environment_people_path,
+      "tenants" => :application_environment_tenants_path,
+      "llm_calls" => :application_environment_llm_calls_path,
+      "outgoing_requests" => :application_environment_outgoing_requests_path,
+      "cache_events" => :application_environment_cache_events_path,
+      "mails" => :application_environment_mails_path,
+      "notifications" => :application_environment_notifications_path
+    }.freeze
+    PAGES = PAGE_PATHS.keys.freeze
+
+    def environment = Environment.current
+    def user
+      User.find_by(id: viewer_id)
+    end
+
+    def user=(u)
+      self.viewer_id = u&.id&.to_s
+    end
+
+    validates :name, presence: true, length: { maximum: 80 }
+    validates :page, inclusion: { in: PAGES }
+
+    scope :pinned, -> { where(pinned: true) }
+    scope :visible_to, ->(user) { where(shared: true).or(where(viewer_id: user.id.to_s)) }
+
+    # The props every environment page shares, ready for the sidebar and the
+    # Views menu: one entry per view this user is allowed to see.
+    def self.props_for(environment, user)
+      where(environment_id: environment.id).visible_to(user).order(:name).map { |view| view.props(environment, user) }
+    end
+
+    def props(environment, user)
+      { id: id, name: name, page: page, query: query, window: window, params: params, pinned: pinned, shared: shared,
+        mine: viewer_id == user&.id, url: path_for(environment) }
+    end
+
+    # This page's index path with the view's window, query, and extra params
+    # (sort/dir) applied -- the shareable URL.
+    def path_for(environment)
+      Railwatch::Engine.routes.url_helpers.public_send(PAGE_PATHS.fetch(page), environment.application_id, environment.id,
+        { window: window.presence, q: query.presence, **params.to_h.symbolize_keys }.compact)
+    end
+  end
+end

data/app/models/railwatch/telemetry/aggregations.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Railwatch
+  module Telemetry
+    # Pure per-environment rollup aggregation: time-bucketed series, grouped
+    # tables, and window-over-window summaries. Takes explicit from/to rather
+    # than reading a controller's window params, so it's the same math for the
+    # web dashboard (EnvironmentScoped) and the public API (Api::V1).
+    class Aggregations
+      GROUPED_SORT_FIELDS = %i[count p50 p95 p99 errors avg max].freeze
+
+      # Time-bucketed series from rollups for charts: [{t, count, errors, p50, p95, p99}]
+      def self.series(environment, record_type, from:, to:, group_hash: nil, name: nil)
+        environment.with_telemetry do
+          scope = Telemetry::Rollup.for_type(record_type).between(from, to)
+          scope = scope.where(group_hash: group_hash) if group_hash
+          scope = scope.where(name: name) if name
+          scope.group(:bucket).order(:bucket)
+               .pluck(:bucket, Arel.sql("SUM(count)"), Arel.sql("SUM(error_count)"), Arel.sql("SUM(client_error_count)"), Arel.sql("SUM(duration_sum)"), Arel.sql("MAX(p50)"), Arel.sql("MAX(p95)"), Arel.sql("MAX(p99)"))
+               .map { |b, c, e, ce, ds, p50, p95, p99| { t: b, count: c, errors: e, client_errors: ce, avg: c.zero? ? 0 : ds / c / 1000.0, p50: p50 / 1000.0, p95: p95 / 1000.0, p99: p99 / 1000.0 } }
+        end
+      end
+
+      # Per-group table rows for a record type in the window: count/error totals,
+      # merged percentiles (via Telemetry::Rollup.summarize), and a sparkline.
+      def self.grouped(environment, record_type, from:, to:, limit: 100, order: nil, dir: nil)
+        order = GROUPED_SORT_FIELDS.include?(order.to_s.to_sym) ? order.to_s.to_sym : :count
+        sign = dir.to_s == "asc" ? 1 : -1
+        # Same minute cache as summary_with_delta, for the same reason: the
+        # 200 busiest query groups on the rebulk environment span 1,500 rollup
+        # rows and 55,000 centroids, and merging those digests is 480ms that
+        # only changes when RollupJob writes.
+        key = [ "aggregations", "grouped", environment.id, record_type, limit, order, sign, from.to_i / 60, to.to_i / 60 ]
+        cached(key) { grouped_uncached(environment, record_type, from: from, to: to, limit: limit, order: order, sign: sign) }
+      end
+
+      def self.grouped_uncached(environment, record_type, from:, to:, limit:, order:, sign:)
+        environment.with_telemetry do
+          rows = Telemetry::Rollup.for_type(record_type).between(from, to).to_a
+          groups = rows.group_by(&:group_hash)
+          # Merging t-digests is the expensive part (the queries page has 2,000
+          # groups over 8,500 rows: 500ms of digest merges for a table that
+          # shows 200). Sort on what the columns already hold -- counts, sums
+          # and maxima need no digest -- and only merge percentiles for the
+          # groups that make the cut. A percentile sort falls back to the full
+          # merge, since the ranking itself needs the digest.
+          cheap = %i[count errors avg max].include?(order)
+          ranked = groups.map { |group_hash, group_rows| [ group_hash, group_rows, cheap ? cheap_summary(group_rows) : Telemetry::Rollup.summarize(group_rows) ] }
+          ranked.sort_by! { |_, _, summary| summary[order] * sign }
+          ranked.first(limit).map do |group_hash, group_rows, summary|
+            summary = Telemetry::Rollup.summarize(group_rows) if cheap
+            {
+              group_hash: group_hash, name: group_rows.max_by(&:bucket).name,
+              count: summary[:count], errors: summary[:errors], client_errors: summary[:client_errors],
+              avg: (summary[:avg] / 1000.0).round(2), p50: (summary[:p50] / 1000.0).round(2),
+              p95: (summary[:p95] / 1000.0).round(2), p99: (summary[:p99] / 1000.0).round(2),
+              max: (summary[:max] / 1000.0).round(2), sparkline: sparkline(group_rows, from, to)
+            }
+          end
+        end
+      end
+
+      # The minute cache exists because the platform's rollups only change
+      # when RollupJob writes. Embedded, every batch updates them and one
+      # person is looking, so the cache would only make the page a minute
+      # stale for nothing.
+      def self.cached(key, &block)
+        return yield if Railwatch.config.local?
+
+        Rails.cache.fetch(key, expires_in: 1.minute, &block)
+      end
+
+      # The digest-free half of Rollup.summarize: everything the sort keys
+      # that are not percentiles need.
+      def self.cheap_summary(rows)
+        count = rows.sum(&:count)
+        { count: count, errors: rows.sum(&:error_count),
+         avg: count.zero? ? 0 : (rows.sum(&:duration_sum) / count), max: rows.map(&:duration_max).max }
+      end
+
+      # { current: Summary, previous: Summary } so pages/endpoints can show deltas.
+      # Cached for a minute per window. The two totals merge every rollup
+      # digest in both windows (18,000 rows, 355ms on the rebulk environment's
+      # queries page) to produce four numbers that only move when RollupJob
+      # writes, which is at most once a minute per bucket; without this the
+      # merge ran again on every page load.
+      def self.summary_with_delta(environment, record_type, from:, to:, previous_from:, previous_to:, group_hash: nil)
+        key = [ "aggregations", "summary_with_delta", environment.id, record_type, group_hash,
+               from.to_i / 60, to.to_i / 60, previous_from.to_i / 60, previous_to.to_i / 60 ]
+        cached(key) do
+          environment.with_telemetry do
+            current = Telemetry::Rollup.for_type(record_type).between(from, to)
+            previous = Telemetry::Rollup.for_type(record_type).between(previous_from, previous_to)
+            if group_hash
+              current = current.where(group_hash: group_hash)
+              previous = previous.where(group_hash: group_hash)
+            end
+            { current: Telemetry::Rollup.summarize(current), previous: Telemetry::Rollup.summarize(previous) }
+          end
+        end
+      end
+
+      # Hourly counts for a set of same-window rollup rows, zero-filled, coarsened
+      # to at most 30 points for wide windows (7d/30d).
+      def self.sparkline(rows, from, to)
+        hours = [ ((to - from) / 1.hour).ceil, 1 ].max
+        coarsen = (hours / 30.0).ceil
+        base = from.beginning_of_hour
+        buckets = Hash.new(0)
+        rows.each { |r| buckets[((r.bucket - base) / 1.hour).to_i / coarsen] += r.count }
+        bucket_count = (hours.to_f / coarsen).ceil
+        (0...bucket_count).map { |i| buckets[i] }
+      end
+    end
+  end
+end

data/app/models/railwatch/telemetry/attachment.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Railwatch
+  module Telemetry
+    # A file an app attached to an execution or exception with Railwatch.attach.
+    # `data` is gzip of the original bytes.
+    class Attachment < TelemetryRecord
+      include Child
+
+      # A record has to fit inside the API's decoded request ceiling. Keeping
+      # the per-attachment ceiling equal to it preserves every valid existing
+      # payload while bounding reads of legacy rows.
+      MAX_BODY_BYTES = IngestRequestBodyLimit::MAX_BYTES
+
+      def body
+        BoundedGzip.decompress(data, max_bytes: MAX_BODY_BYTES)
+      end
+
+      # Only text-ish payloads are safe to render in the browser; everything
+      # else downloads. Rendered as text/plain either way, so a stored
+      # text/html attachment can never execute against our origin.
+      def viewable?
+        content_type.to_s.start_with?("text/") || content_type.to_s.split(";").first == "application/json"
+      end
+
+      def timeline_label
+        name.to_s.first(120)
+      end
+    end
+  end
+end