railwatch 0.9.3 → 1.0.0

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

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class Process < TelemetryRecord
-      self.table_name = "processes"
-      scope :recent, -> { order(booted_at: :desc) }
-    end
-  end
-end

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

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # A sampled stack profile of one execution. `stacks` is gzip of collapsed
-    # stacks ("outer;inner;leaf count\n"), the format flamegraph tools read.
-    class Profile < TelemetryRecord
-      include Child
-
-      # Railwatch's profiler caps collapsed stacks at 4 MiB before compression.
-      # Enforce the same contract here even when a client lies about its size.
-      MAX_INGEST_BYTES = 4.megabytes
-
-      # A minute of wall profiling can decompress to tens of megabytes; the
-      # page only ever renders a flamegraph, so the payload is cut here rather
-      # than shipped whole to the browser.
-      MAX_COLLAPSED_BYTES = 2.megabytes
-
-      def collapsed
-        BoundedGzip.utf8!(BoundedGzip.decompress(stacks, max_bytes: MAX_INGEST_BYTES))
-      end
-
-      # [text, truncated?] - cut on a line boundary so the parser never sees
-      # half a stack line.
-      def collapsed_capped(limit = MAX_COLLAPSED_BYTES)
-        text, truncated = BoundedGzip.decompress_capped(stacks, limit: [ limit, MAX_INGEST_BYTES ].min)
-        text = text.sub(/[^\n]*\z/, "") if truncated
-
-        [ BoundedGzip.utf8!(text), truncated ]
-      end
-
-      def timeline_label
-        "#{profiler} profile (#{samples} samples)"
-      end
-    end
-  end
-end

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

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class Query < TelemetryRecord
-      include Child
-
-      # Raised when a row's SQL is read on a relation that did not resolve it.
-      class SqlNotResolved < StandardError; end
-
-      # The statement, from the row or from its group's shape (QueryShape).
-      # A correlated lookup rather than a join: the queries page sorts a
-      # window of millions of rows before taking 50, and a LEFT JOIN there
-      # was paid per candidate row (47 s against 0.8 s on the 5M-row window).
-      SQL = Arel.sql("COALESCE(NULLIF(queries.sql, ''), " \
-                     "(SELECT query_shapes.sql FROM query_shapes WHERE query_shapes.group_hash = queries.group_hash), '') AS resolved_sql").freeze
-
-      # Rows with their SQL resolved in the same statement, so a page loaded
-      # inside Environment#with_telemetry can be rendered after the block.
-      # Replaces the select list: count with count(:all), and pluck
-      # resolved_sql, not sql.
-      scope :with_sql, -> { select("queries.*", SQL) }
-
-      # Free-text search over the statement, wherever it is stored.
-      scope :matching, ->(text) {
-        pattern = "%#{sanitize_sql_like(text)}%"
-        where("queries.sql LIKE :pattern ESCAPE '\\' OR queries.name LIKE :pattern ESCAPE '\\' " \
-              "OR queries.group_hash IN (SELECT group_hash FROM query_shapes WHERE sql LIKE :pattern ESCAPE '\\')", pattern: pattern)
-      }
-
-      def self.timeline_scope(execution_id)
-        in_execution(execution_id).with_sql
-      end
-
-      # Always a String. A row whose text lives on its shape can only answer
-      # through with_sql; asking without it is a bug, not an empty statement.
-      def sql
-        return self[:resolved_sql].to_s if has_attribute?(:resolved_sql)
-
-        text = self[:sql].to_s
-        raise SqlNotResolved, "Telemetry::Query##{id} stores its SQL on its shape; load it through Query.with_sql" if text.empty? && group_hash
-        text
-      end
-
-      def as_row
-        { id: id, group_hash: group_hash, sql: sql.first(2_000), name: name, duration: duration_ms.round(3), occurred_at: occurred_at,
-          deploy: deploy, execution_id: execution_id, execution_preview: execution_preview, source: source,
-          connection: connection, role: role, adapter: adapter, row_count: row_count, tenant: app_tenant, user_ref: user_ref,
-          explain: explain.present? }
-      end
-
-      def timeline_label
-        sql.to_s.first(120)
-      end
-    end
-  end
-end

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

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # One query group's normalized statement, stored once. The group hash is
-    # the gem's digest of the connection name and that statement, so a row
-    # whose own text digests to its group carries the statement and stores
-    # "" instead (Ingest::Writer); any other text stays on the row. See
-    # docs/architecture.md.
-    class QueryShape < TelemetryRecord
-      self.primary_key = :group_hash
-
-      BACKFILL_BATCH = 20_000
-
-      # Backfill for rows written before this table existed. Files a shape
-      # for each group whose earliest or newest row normalizes back to the
-      # group hash (a tenant's earliest rows may predate the gem sending
-      # normalized text; its newest will not), then blanks every row whose
-      # text is its group's shape, in id-range batches so no statement holds
-      # the tenant's write lock for long. Idempotent, and never blanks a row
-      # whose text is not on file. Returns what it did.
-      def self.dedupe_rows!(batch: BACKFILL_BATCH)
-        before = count
-        file_shapes!
-        moved = Query.where.not(sql: "")
-                     .where("queries.sql = (SELECT s.sql FROM query_shapes s WHERE s.group_hash = queries.group_hash)")
-                     .in_batches(of: batch, use_ranges: true).update_all(sql: "")
-        { shapes: count - before, rows: moved }
-      end
-
-      def self.file_shapes!
-        ends = "SELECT MIN(id) AS id FROM queries WHERE group_hash IS NOT NULL GROUP BY group_hash " \
-               "UNION SELECT MAX(id) FROM queries WHERE group_hash IS NOT NULL GROUP BY group_hash"
-        candidates = Query.joins("JOIN (#{ends}) ends ON ends.id = queries.id").where.not(sql: "")
-                          .pluck(:group_hash, :sql, :adapter, :connection)
-        shapes = candidates.filter_map do |group_hash, sql, adapter, connection|
-          digest, normalized = Railwatch::SqlNormalizer.group_and_normalized(sql, adapter: adapter, connection_name: connection)
-          { group_hash: group_hash, sql: normalized } if digest == group_hash
-        end
-        shapes.uniq { |shape| shape[:group_hash] }.each_slice(500) { |slice| insert_all(slice) }
-      end
-      private_class_method :file_shapes!
-    end
-  end
-end

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

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # Hourly release health per deploy, recomputed from raw `sessions` rows by
-    # ReleaseHealthRollupJob. The deploy *is* the release -- the gem stamps it
-    # on every record it ships -- so counting sessions per deploy is all this
-    # needs. Sentry's crash-free session rate, crash-free user rate, and
-    # adoption, over the same data.
-    #
-    # A session that spans two hours is counted in both buckets, like every
-    # other rollup here: the bucket, not the session, is the unit these numbers
-    # sum over. Every method must run inside environment.with_telemetry { }.
-    class ReleaseHealth < TelemetryRecord
-      self.table_name = "release_health"
-
-      scope :between, ->(from, to) { where(bucket: from.beginning_of_hour..to) }
-      # A nil deploy means "every release in the window", which is what the
-      # index page's headline numbers are.
-      scope :for_release, ->(deploy) { deploy ? where(deploy: deploy) : all }
-
-      TOTALS = %i[sessions sessions_errored sessions_crashed users users_crashed duration_sum duration_count].freeze
-
-      # Window totals for one release. Rates come back nil, not zero, when there
-      # is nothing to divide by, so an environment with no sessions yet never
-      # renders as "0% crash-free".
-      def self.for_deploy(deploy, from, to)
-        sessions, errored, crashed, users, users_crashed, duration_sum, duration_count =
-          between(from, to).for_release(deploy).pick(*TOTALS.map { |column| Arel.sql("COALESCE(SUM(#{column}), 0)") })
-        {
-          sessions: sessions, users: users,
-          crash_free_sessions: rate(sessions - crashed, sessions),
-          crash_free_users: rate(users - users_crashed, users),
-          errored: rate(errored, sessions),
-          avg_duration_ms: duration_count.zero? ? nil : (duration_sum / duration_count / 1000.0).round(2)
-        }
-      end
-
-      # Points for the stacked sessions-by-status chart, one per `step` across
-      # the window. The table is hourly and a session is counted once per hour
-      # it was seen, so a step under an hour is drawn at an hour: raw session
-      # rows would count a live session on every flush.
-      def self.series(deploy, from, to, step: nil)
-        step = [ Telemetry::Aggregations::STEPS.fetch(step || Telemetry::Aggregations.default_step(from, to)), 1.hour ].max
-        bucket = Telemetry::Aggregations.bucket_sql("bucket", step)
-        points = between(from, to).for_release(deploy).group(bucket).order(bucket)
-          .pluck(bucket, Arel.sql("SUM(sessions)"), Arel.sql("SUM(sessions_errored)"), Arel.sql("SUM(sessions_crashed)"))
-          .map { |b, sessions, errored, crashed|
-            { t: Time.at(b).utc, sessions: sessions, ok: sessions - errored - crashed, errored: errored, crashed: crashed }
-          }
-        Telemetry::Aggregations.fill(points, from, to, step) { |t| { t: t, sessions: 0, ok: 0, errored: 0, crashed: 0 } }
-      end
-
-      # Each release's share of the window's sessions, as a percentage -- how
-      # far a new release has rolled out.
-      def self.adoption(from, to)
-        counts = between(from, to).group(:deploy).sum(:sessions)
-        total = counts.values.sum
-        return counts.transform_values { 0.0 } if total.zero?
-        counts.transform_values { |n| (n * 100.0 / total).round(1) }
-      end
-
-      def self.rate(numerator, denominator)
-        return nil if denominator.to_i.zero?
-        (numerator * 100.0 / denominator).round(2)
-      end
-    end
-  end
-end

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

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  require "tdigest"
-
-  module Telemetry
-    # Hourly aggregate per (record_type, group). Percentiles are exact within
-    # an hour and merged across hours with t-digest, so a 30-day p95 for a
-    # route is one query over 720 small rows.
-    class Rollup < TelemetryRecord
-      scope :for_type, ->(type) { where(record_type: type) }
-      scope :between, ->(from, to) { where(bucket: from.beginning_of_hour..to) }
-
-      def self.bucket_for(time)
-        time.utc.beginning_of_hour
-      end
-
-      # Merge a list of duration samples (microseconds) into the bucket.
-      def self.absorb!(record_type:, group_hash:, name:, bucket:, durations:, errors: 0, client_errors: 0, extra: {})
-        return if durations.empty?
-        row = find_or_initialize_by(record_type: record_type, group_hash: group_hash, bucket: bucket)
-        row.name = name
-        digest = row.digest ? TDigest::TDigest.from_bytes(row.digest) : TDigest::TDigest.new(0.01)
-        durations.each { |d| digest.push(d) }
-        digest.compress!
-        row.count += durations.size
-        row.error_count += errors
-        row.client_error_count += client_errors
-        row.duration_sum += durations.sum
-        row.duration_max = [ row.duration_max, durations.max ].max
-        row.p50 = digest.percentile(0.5).to_i
-        row.p95 = digest.percentile(0.95).to_i
-        row.p99 = digest.percentile(0.99).to_i
-        row.digest = digest.as_small_bytes
-        row.extra = row.extra.merge(extra) { |_k, a, b| a.is_a?(Numeric) && b.is_a?(Numeric) ? a + b : b }
-        row.save!
-        row
-      end
-
-      # The row absorb! would write over an empty bucket, as attributes for
-      # insert_all. RollupJob deletes an hour's rows and writes every group in
-      # one statement, so the read absorb! does per group is wasted there.
-      def self.fresh_attributes(record_type:, group_hash:, name:, bucket:, durations:, errors: 0, client_errors: 0, extra: {})
-        digest = TDigest::TDigest.new(0.01)
-        durations.each { |d| digest.push(d) }
-        digest.compress!
-        { record_type: record_type, group_hash: group_hash, name: name, bucket: bucket,
-         count: durations.size, error_count: errors, client_error_count: client_errors,
-         duration_sum: durations.sum, duration_max: durations.max,
-         p50: digest.percentile(0.5).to_i, p95: digest.percentile(0.95).to_i, p99: digest.percentile(0.99).to_i,
-         digest: digest.as_small_bytes, extra: extra }
-      end
-
-      # Aggregate a relation of rollups into one summary with merged percentiles.
-      def self.summarize(relation)
-        rows = relation.to_a
-        return { count: 0, errors: 0, client_errors: 0, avg: 0, p50: 0, p95: 0, p99: 0, max: 0, extra: {} } if rows.empty?
-        p50, p95, p99 = merged_percentiles(rows, [ 0.5, 0.95, 0.99 ])
-        count = rows.sum(&:count)
-        {
-          count: count,
-          errors: rows.sum(&:error_count),
-          client_errors: rows.sum(&:client_error_count),
-          avg: count.zero? ? 0 : (rows.sum(&:duration_sum) / count),
-          p50: p50,
-          p95: p95,
-          p99: p99,
-          max: rows.map(&:duration_max).max,
-          # Everything a type puts in `extra` -- llm_call's cost_nanos and
-          # token counts, cache_event's hits and misses -- merged the way
-          # absorb! merges it: numbers add up, anything else is last-wins.
-          # Spend is a sum over a window rather than a percentile of
-          # durations, so a rule about money has nowhere else to read from.
-          extra: merge_extras(rows)
-        }
-      end
-
-      # Percentiles of the union of every row's centroids, read straight out
-      # of the stored bytes. Merging through TDigest pushed each centroid into
-      # a red-black tree one at a time: 2.8 s for a week of the platform's
-      # own query rollups (18,674 rows) and 7 s for thirty days, on every
-      # cold page load. Sorting the centroids once and walking their
-      # cumulative counts answers the same question without re-clustering:
-      # 353 ms and 1 s for those two windows. The answer is the first
-      # centroid whose running total reaches n * p, which is nearest rank --
-      # the rule raw_series uses for sub-hour buckets, so both readings of a
-      # window agree. (TDigest#percentile compares each centroid's midpoint
-      # instead, which puts the median of 1,000 sevens and 300 nines at 9.)
-      def self.merged_percentiles(rows, ps)
-        means = []
-        counts = []
-        rows.each { |row| centroids(row.digest, means, counts) if row.digest }
-        return ps.map { 0 } if means.empty?
-
-        order = (0...means.size).sort_by { |i| means[i] }
-        total = counts.sum
-        targets = ps.map { |p| total * p }
-        found = []
-        seen = 0
-        order.each do |i|
-          seen += counts[i]
-          found << means[i] while found.size < targets.size && seen >= targets[found.size]
-          break if found.size == targets.size
-        end
-        found << means[order.last] while found.size < targets.size
-        found.map(&:to_i)
-      end
-
-      # Appends one stored digest's centroid means and weights, in either of
-      # the tdigest gem's encodings (TDigest.from_bytes reads the same two).
-      def self.centroids(bytes, means, counts)
-        format, _compression, size = bytes.unpack("LdL")
-        case format
-        when TDigest::TDigest::VERBOSE_ENCODING
-          means.concat(bytes.unpack("@16d#{size}"))
-          counts.concat(bytes.unpack("@#{16 + 8 * size}L#{size}"))
-        when TDigest::TDigest::SMALL_ENCODING
-          # Means are delta-encoded 4-byte floats; weights are 7-bit varints,
-          # one byte each unless a centroid holds 128 or more samples.
-          mean = 0.0
-          bytes.unpack("@16f#{size}").each { |delta| means << (mean += delta) }
-          weights = bytes.byteslice(16 + 4 * size, bytes.bytesize).unpack("C*")
-          if weights.size == size
-            counts.concat(weights)
-          else
-            at = 0
-            size.times do
-              byte = weights[at]
-              at += 1
-              weight = byte & 0x7f
-              shift = 7
-              while byte & 0x80 != 0
-                byte = weights[at] || 0
-                at += 1
-                weight += (byte & 0x7f) << shift
-                shift += 7
-              end
-              counts << weight
-            end
-          end
-        else
-          raise ArgumentError, "unknown t-digest encoding #{format}"
-        end
-      end
-      private_class_method :centroids
-
-      def self.merge_extras(rows)
-        rows.each_with_object({}) do |row, out|
-          row.extra.each do |key, value|
-            existing = out[key]
-            out[key] = existing.is_a?(Numeric) && value.is_a?(Numeric) ? existing + value : value
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # One session of the monitored application, for release health: a browser
-    # tab (reported by the gem's beacon client) or a server-side session (the
-    # gem's request middleware). The gem re-sends a live session on every flush
-    # interval, so the same session_id arrives many times and gets collapsed to
-    # one session per bucket by ReleaseHealthRollupJob.
-    class Session < TelemetryRecord
-      include Child
-
-      STATUSES = %w[started ok errored crashed].freeze
-
-      def crashed?
-        status == "crashed"
-      end
-
-      def timeline_label
-        session_id
-      end
-    end
-  end
-end

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

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # A custom span recorded with Railwatch.span("name") { }, a child of the
-    # request/job/command it ran inside.
-    class Span < TelemetryRecord
-      include Child
-
-      scope :failed, -> { where(status: "failed") }
-
-      # The wire record calls the user payload "attributes"; the column is
-      # `payload` because `attributes` is Active Record's own method.
-      def timeline_label
-        name.to_s.first(120)
-      end
-    end
-  end
-end

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

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class StorageOp < TelemetryRecord
-      include Child
-
-      def timeline_label
-        key.to_s.first(120)
-      end
-    end
-  end
-end

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

@@ -1,240 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # A tenant of the monitored application, as seen in its telemetry. Not an
-    # Active Record table: `app_tenant` is a column on every telemetry row (the
-    # gem fills it from Railwatch::Context.current_tenant, which multi-tenant
-    # Rails apps get from ActiveRecord::Tenanted / TenantRecord.current_tenant),
-    # so a "tenant" only exists as a GROUP BY over the raw tables.
-    #
-    # Telemetry::Rollup -- what every other page's numbers come from -- is keyed
-    # by record type and group_hash only and has no tenant dimension, so all of
-    # this is computed from raw rows in the window. Every method must run inside
-    # environment.with_telemetry { }.
-    class Tenant
-      MAX_TENANTS = 200
-      # A p95 costs one ordered query per tenant (SQLite has no percentile
-      # aggregate), so only the busiest tenants get one; the rest report 0.
-      P95_TENANTS = 50
-      SPARKLINE_BUCKETS = 12
-      # Tenant names are bound one variable each, and SQLite allows 32,766
-      # per statement; an app with more tenants than that is asked in slices.
-      TENANT_SLICE = 1_000
-      SORTS = { "requests" => :requests, "errors" => :errors, "p95" => :p95, "users" => :users }.freeze
-
-      ERRORS_SQL = Arel.sql("SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END)")
-      CLIENT_ERRORS_SQL = Arel.sql("SUM(CASE WHEN status BETWEEN 400 AND 499 THEN 1 ELSE 0 END)")
-      FAILED_SQL = Arel.sql("SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END)")
-      COUNT_SQL = Arel.sql("COUNT(*)")
-      USERS_SQL = Arel.sql("COUNT(DISTINCT user_ref)")
-
-      # One aggregate row per tenant seen in the window, filtered by `q`
-      # (a substring of the tenant name), sorted, and capped at MAX_TENANTS.
-      def self.index(from, to, q: nil, sort: nil, dir: nil)
-        rows = Hash.new { |h, tenant| h[tenant] = blank_row(tenant) }
-        absorb_requests(rows, from, to, q)
-        absorb_jobs(rows, from, to, q)
-        absorb_counts(rows, filtered(Telemetry::Exception.between(from, to), q), :exceptions)
-        absorb_counts(rows, filtered(Telemetry::Log.between(from, to), q), :logs)
-        absorb_last_seen(rows, from, to, q)
-        absorb_sparklines(rows, from, to)
-        absorb_p95s(rows.values.max_by(P95_TENANTS) { |r| r[:requests] }, from, to)
-        sorted(rows.values, sort, dir)
-      end
-
-      # Headline numbers for the index page, computed from the rows it shows
-      # (so the top-tenant share is a share of the listed tenants' requests)
-      # plus the share of requests in the window that carry no tenant at all.
-      #
-      # The untagged count is the window's requests less the tagged ones,
-      # and the tagged ones are counted per tenant in app_tenant's index.
-      # Counting either side with app_tenant IS [NOT] NULL read every request
-      # in the window instead: 1 s on an untagged app, 24 s on a tagged one.
-      def self.overview(rows, from, to)
-        requests = Telemetry::Execution.requests.between(from, to)
-        total = requests.count
-        tagged_total = tagged_tenants(from, to).each_slice(TENANT_SLICE).sum { |slice| requests.where(app_tenant: slice).count }
-        tagged = rows.sum { |r| r[:requests] }
-        top = rows.max_by { |r| r[:requests] }
-        {
-          tenants: rows.size, top_tenant: top && top[:tenant],
-          top_share: tagged.zero? ? 0.0 : (top[:requests] * 100.0 / tagged).round(1),
-          with_errors: rows.count { |r| r[:errors].positive? },
-          untagged_share: total.zero? ? 0.0 : ((total - tagged_total) * 100.0 / total).round(1)
-        }
-      end
-
-      # Every tenant that sent anything in the window, from the tenant-led
-      # index (a skip-scan over distinct values, not the window's rows).
-      def self.tagged_tenants(from, to)
-        Telemetry::Execution.between(from, to).where.not(app_tenant: nil).distinct.pluck(:app_tenant)
-      end
-
-      # Window totals for one tenant. Durations in milliseconds, like the rest
-      # of the tenant props.
-      def self.summary(tenant, from, to)
-        requests = Telemetry::Execution.requests.between(from, to).where(app_tenant: tenant)
-        count, errors, users = requests.pick(COUNT_SQL, ERRORS_SQL, USERS_SQL)
-        jobs, failed_jobs = Telemetry::Execution.jobs.between(from, to).where(app_tenant: tenant).pick(COUNT_SQL, FAILED_SQL)
-        {
-          requests: count, errors: errors.to_i, p95: p95_ms(requests, count), jobs: jobs, failed_jobs: failed_jobs.to_i,
-          exceptions: Telemetry::Exception.between(from, to).where(app_tenant: tenant).count,
-          users: users, logs: Telemetry::Log.between(from, to).where(app_tenant: tenant).count
-        }
-      end
-
-      # Request volume and duration bucketed over the window at `step`,
-      # SeriesPoint-shaped so the same charts render it. Rollups carry no tenant,
-      # so every step reads raw rows (Telemetry::Aggregations.points does that
-      # for a tenant), with exact percentiles per bucket.
-      def self.series(tenant, from, to, step: nil)
-        Telemetry::Aggregations.points("request", from: from, to: to, step: step, tenant: tenant)
-      end
-
-      def self.routes(tenant, from, to, limit: 20)
-        grouped_executions(Telemetry::Execution.requests, tenant, from, to, ERRORS_SQL, :errors, limit)
-      end
-
-      def self.job_classes(tenant, from, to, limit: 10)
-        grouped_executions(Telemetry::Execution.jobs, tenant, from, to, FAILED_SQL, :failed, limit)
-      end
-
-      def self.exceptions(tenant, from, to, limit: 20)
-        Telemetry::Exception.between(from, to).where(app_tenant: tenant).recent.limit(limit).map do |e|
-          { id: e.id, class_name: e.class_name, message: e.message.first(500), occurred_at: e.occurred_at,
-            execution_id: e.execution_id, group_hash: e.group_hash }
-        end
-      end
-
-      def self.people(tenant, limit: 20)
-        Telemetry::Person.where(app_tenant: tenant).recent.limit(limit).map do |person|
-          { ref: person.ref, name: person.display_name, email: person.email, last_seen_at: person.last_seen_at }
-        end
-      end
-
-      # The tenant page's "Recent requests" table.
-      def self.recent_requests(tenant, from, to, limit: 50)
-        Telemetry::Execution.requests.between(from, to).where(app_tenant: tenant).recent.limit(limit).map(&:as_row)
-      end
-
-      # -- Aggregation steps -----------------------------------------------------
-
-      # The per-tenant sums read through idx_executions_tenant_summary, which
-      # holds every column they need for tagged rows only. SQLite prefers the
-      # narrower (app_tenant, occurred_at) index on its own estimate and then
-      # fetches every row from the table (8 s against 131 ms over 30 days).
-      def self.summary_scope(kind)
-        scope = Telemetry::Execution
-        scope = scope.from("#{scope.quoted_table_name} INDEXED BY idx_executions_tenant_summary") if TelemetryRecord.sqlite?
-        scope.where(kind: kind).where.not(app_tenant: nil)
-      end
-
-      def self.absorb_requests(rows, from, to, q)
-        filtered(summary_scope("request").between(from, to), q).group(:app_tenant)
-          .pluck(:app_tenant, COUNT_SQL, ERRORS_SQL, Arel.sql("AVG(duration)"), Arel.sql("MAX(duration)"), USERS_SQL)
-          .each do |tenant, count, errors, avg, max, users|
-            rows[tenant].merge!(requests: count, errors: errors, avg: ms(avg), max: ms(max), users: users)
-          end
-      end
-
-      def self.absorb_jobs(rows, from, to, q)
-        filtered(summary_scope("job_attempt").between(from, to), q).group(:app_tenant)
-          .pluck(:app_tenant, COUNT_SQL, FAILED_SQL)
-          .each { |tenant, count, failed| rows[tenant].merge!(jobs: count, failed_jobs: failed) }
-      end
-
-      def self.absorb_counts(rows, scope, key)
-        scope.group(:app_tenant).count.each { |tenant, count| rows[tenant][key] = count }
-      end
-
-      def self.absorb_last_seen(rows, from, to, q)
-        filtered(summary_scope(Telemetry::Execution::KINDS).between(from, to), q).group(:app_tenant).maximum(:occurred_at)
-          .each { |tenant, at| rows[tenant][:last_seen_at] = at }
-      end
-
-      # Only for the tenants already found, by name: grouped by tenant and a
-      # time expression SQLite would not seek the app_tenant index and read
-      # every request in the window instead -- 11 s over a week on an app
-      # with no tenants at all, to draw nothing.
-      def self.absorb_sparklines(rows, from, to)
-        tenants = rows.keys.compact
-        return if tenants.empty?
-
-        width = bucket_width(from, to, SPARKLINE_BUCKETS)
-        counts = tenants.each_slice(TENANT_SLICE).flat_map do |slice|
-          Telemetry::Execution.requests.between(from, to).where(app_tenant: slice)
-            .group(:app_tenant, bucket_sql(from, width)).count.to_a
-        end
-        counts.each do |(tenant, index), count|
-          rows[tenant][:sparkline][[ index.to_i, SPARKLINE_BUCKETS - 1 ].min] += count
-        end
-      end
-
-      def self.absorb_p95s(rows, from, to)
-        rows.each do |row|
-          scope = Telemetry::Execution.requests.between(from, to).where(app_tenant: row[:tenant])
-          row[:p95] = p95_ms(scope, row[:requests])
-        end
-      end
-
-      # -- Helpers ---------------------------------------------------------------
-
-      def self.blank_row(tenant)
-        { tenant: tenant, requests: 0, errors: 0, avg: 0.0, max: 0.0, p95: 0.0, jobs: 0, failed_jobs: 0,
-          exceptions: 0, logs: 0, users: 0, last_seen_at: nil, sparkline: Array.new(SPARKLINE_BUCKETS, 0) }
-      end
-
-      # Tenant-tagged rows only: a NULL app_tenant never matches LIKE either.
-      def self.filtered(scope, q)
-        return scope.where.not(app_tenant: nil) if q.blank?
-        scope.where("app_tenant LIKE ?", "%#{TelemetryRecord.sanitize_sql_like(q.to_s)}%")
-      end
-
-      def self.sorted(rows, sort, dir)
-        key = SORTS.fetch(sort.to_s, :requests)
-        sign = dir.to_s == "asc" ? 1 : -1
-        rows.sort_by { |row| row[key] * sign }.first(MAX_TENANTS)
-      end
-
-      # The 95th percentile as the duration `count * 5%` rows from the slowest
-      # end -- one indexed query, no percentile function needed.
-      def self.p95_ms(scope, count)
-        return 0.0 if count.to_i.zero?
-        ms(scope.order(duration: :desc).offset((count * 0.05).floor).limit(1).pluck(:duration).first)
-      end
-
-      def self.grouped_executions(scope, tenant, from, to, error_sql, error_key, limit)
-        scope.between(from, to).where(app_tenant: tenant).group(:group_hash, :name)
-          .pluck(:group_hash, :name, COUNT_SQL, error_sql, Arel.sql("AVG(duration)"), Arel.sql("MAX(duration)"))
-          .map { |group_hash, name, count, errors, avg, max|
-            { group_hash: group_hash, name: name, count: count, error_key => errors, avg: ms(avg), max: ms(max) }
-          }.sort_by { |row| -row[:count] }.first(limit)
-      end
-
-      # Microseconds on the wire, milliseconds in every prop.
-      def self.ms(duration)
-        duration ? (duration / 1000.0).round(2) : 0.0
-      end
-
-      def self.bucket_width(from, to, buckets)
-        [ (to - from) / buckets, 1.0 ].max
-      end
-
-      # Bucket index per row: epoch seconds since `from` over the bucket width.
-      # Windows are an hour or more, so second resolution is plenty.
-      # Both interpolations are coerced to numbers first (`from` is a Time, `width`
-      # a Float from bucket_width), so the fragment can only ever contain two
-      # numeric literals -- never a caller-supplied string.
-      def self.bucket_sql(from, width)
-        Arel.sql("CAST((strftime('%s', occurred_at) - #{Integer(from.to_i)}) / #{Float(width)} AS INTEGER)")
-      end
-
-      # A row landing exactly on `to` indexes one bucket past the end; clamp it
-      # into the last one.
-      def self.bucket_at(from, width, index, buckets)
-        from + ([ index.to_i, buckets - 1 ].min * width)
-      end
-    end
-  end
-end