rails_pulse 0.5.0.pre.1 → 0.5.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a494a9f4ff4c1f388ed3f87f6911cfae02b9efb329673f1b697b8af5c589f4a
-  data.tar.gz: bd9fc701eccf980bca1c8aa1269dc5549fa3882f905c8691cb9fb70cc842b399
+  metadata.gz: 208274704510167233904a19653cfe5bffcf6f29080344d088e9cbee8c425a87
+  data.tar.gz: fbbe9e3a6c35a09236a81158d47026a9ab913f1db6e79800b8c71183df4d9d63
 SHA512:
-  metadata.gz: 642d5edc8eb02e9b7d4b5e393995ebd84782f2068eef36e075820ce9fed47db44ec3ce8bce4fec076e9a4d2b055a95b7c390309ab83dc51a3c13f2c4babc8608
-  data.tar.gz: adcc2d2f7ce7176cbadd781abe14cc13df14002a4ba5e48f178c2853074118a0996d0c09e752077b65cf5c4eab77387f49a5ffff5b45b08422a460fab7a4f95a
+  metadata.gz: 83b22f6771f0c1a99bada73bd60e1af0abb7a7931b5523afa9c1a852c85bf7664d4af32ec025d955ff6db47dfde7c3b2563fee86301d2a7032b0a6f7f1615543
+  data.tar.gz: '08fd08858f4eafa689a17e92c922623f15f11ff9663de193b3f99830faa59a171bef0a7c5357dbb7bcd2df9afd1ab97f7f6c3ff52ca4cb0f67d7835f11c99730'

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0.pre.2] - 2026-10-11
+
+### Added
+
+- **Before-and-after comparison for every deployment.** The deployments API, `rails-pulse deployments list` and the `rails_pulse_deployments` tool now say whether each release made things worse: response time or error rate materially worse in the hour after the deploy finished than in the hour before it started, or too little traffic to tell.
+- **What needs attention, and whether the thresholds fit.** `GET /rails_pulse/api/v1/insights`, `rails-pulse insights show` and the `rails_pulse_insights` tool list the routes, queries and jobs past their thresholds over one hour, day, week or month, and suggest an initializer line when `route_thresholds` or `query_thresholds` is too noisy or never fires.
+- **Exact lookups for the keys Rails Pulse Cloud holds.** The API, CLI and MCP tools can now find a query by `hashed_sql`, an exception group by `fingerprint`, a route by exact path and controller action, a deployment by revision, and requests by path prefix, so a Cloud alert leads straight to the local detail.
+- **Rails Pulse Cloud sync.** With `config.cloud.api_key` and `config.cloud.application` set, hourly summaries, exception groups, deployments and a per-minute health update are sent to Rails Pulse Cloud (never request URLs, SQL values or exception messages), and `rails rails_pulse:cloud:preview` prints exactly what would be sent; to use it, run `rails generate rails_pulse:install_cloud`, migrate, and schedule `RailsPulse::CloudHealthJob` every minute.
+- **`rails rails_pulse:status` checks how the install is run.** It reports whether `SummaryJob` has skipped hours and whether `CleanupJob` is running, how long hourly summaries are kept, and whether jobs are tracked, and lists suggestions for each without changing the exit status. Each cleanup run is now recorded in `rails_pulse_events` so the task can tell.
+
+### Changed
+
+- **A query is the same query however many values it loads.** `WHERE id IN (…)` with 3 ids and with 12 ids, and a batch insert of 2 rows and of 50, used to be tracked as separate queries, each with its own stats, N+1 flags and EXPLAIN; they are now one entry. Entries recorded by earlier versions keep their old form until retention removes them, so a query may appear twice on the Queries page for a while after upgrading.
+- **Hourly summaries are kept for 7 days instead of 2.** Deployment comparisons and hour-precise change points read them, so at 2 days a deploy from earlier in the week could no longer be compared; `config.hourly_summary_retention` tunes it.
+
+### Fixed
+
+- **Normalised SQL no longer shows some string values.** A value written in one of SQL's less common string forms — only possible in hand-written SQL — stayed visible in the normalised query on the dashboard, the API and the MCP server, and split that query's stats into one entry per value; it is now replaced with `?` like any other value. On MySQL the same happened to any value containing an apostrophe or any double-quoted value shaped like a column name, and on every database to very small or very large decimals. (#335, #313)
+- **The dashboard no longer counts every Rails Pulse table on each load.** On PostgreSQL and MySQL its storage panel now shows the database's row estimates, and on SQLite it leaves record counts to the Storage page, so large installs no longer wait tens of seconds per page view; the storage-pressure checks also run once per page instead of four times. On MySQL 8, record counts and disk sizes on the dashboard and the Storage page are read current instead of from a statistics cache up to a day old. (#363)
+- **Needs Attention and System Health no longer overcount traffic.** Request, error, query and exception counts were added up once per summary granularity, which inflated them and could raise an exception group's severity; today's traffic now counts in windows longer than a day. (#338)
+- **Threshold recommendations no longer suggest a critical threshold equal to `very_slow` or below a rarely run slow query.** A suggested critical threshold now sits at least one step above `very_slow`, and the query check reads the period's slowest query rather than only its most expensive ones.
+- **The dashboard no longer reports cleanup as blocked when it is not.** The critical "summarize first" Storage item appeared whenever expired requests were waiting for the next daily cleanup, which deletes them by age regardless of summaries; it has been removed, and a stalled summary job is still flagged.
+- **PostgreSQL Unicode escape strings (`U&'…'`) are normalised to `?`** like other prefixed strings, instead of leaving `U&?` in the normalised query.
+- **Daily charts no longer go blank after a daylight-saving change.** In a `config.time_zone` with daylight saving, every day after the clocks changed was drawn empty in a range that crossed the change; chart days now follow the zone's calendar.
+
 ## [0.5.0.pre.1] - 2026-10-03
 
 ### Added

data/README.md

@@ -120,7 +120,7 @@ rails-pulse routes list --since 2026-06-01T00:00:00Z
 rails-pulse install claude     # Claude Code skill: when and how to use the tools
 ```
 
-Add `gem "mcp"` to your Gemfile (a development group is enough), register `rails-pulse mcp` as an MCP server, and the agent gets ten read-only tools: routes, slow requests, errors, exception groups and their backtraces, one endpoint in depth, expensive and N+1 queries, job health, deployments, and what has actually been recorded. Nothing the agent can call changes production. [Agent tooling](https://railspulse.com/documentation/mcp)
+Add `gem "mcp"` to your Gemfile (a development group is enough), register `rails-pulse mcp` as an MCP server, and the agent gets eleven read-only tools: routes, slow requests, errors, exception groups and their backtraces, one endpoint in depth, expensive and N+1 queries, job health, deployments and whether each one made things worse, what needs attention and whether your thresholds fit, and what has actually been recorded. Nothing the agent can call changes production. [Agent tooling](docs/api.md)
 
 **Keep it in its own database.** `rails generate rails_pulse:install --database=separate` puts the tables somewhere your primary never has to vacuum. [Database setup](https://railspulse.com/documentation/database)
 

data/app/controllers/rails_pulse/api/v1/base_controller.rb

@@ -28,7 +28,10 @@ module RailsPulse
 
         # Parameters every endpoint reads as one string. A repeated or nested
         # one (`search[]=x`) is refused rather than reaching a String method.
-        SCALAR_PARAMS = %i[limit offset min_requests occurrences since until search route status sort job].freeze
+        SCALAR_PARAMS = %i[
+          limit offset min_requests occurrences since until search route status sort job period at
+          hashed_sql fingerprint path controller_action path_prefix revision
+        ].freeze
         INTEGER_PARAMS = %i[limit offset min_requests occurrences].freeze
 
         # Past any real table, and inside a 64-bit integer on every adapter.

data/app/controllers/rails_pulse/api/v1/deployments_controller.rb

@@ -10,14 +10,30 @@ module RailsPulse
           collection = RailsPulse::Deployment.recent.order(id: :desc)
           collection = collection.where(started_at: since_start..) if since_start
           collection = collection.where(started_at: ..until_end) if until_end
+          collection = apply_revision_filter(collection)
 
           data, meta = paginated(collection)
+          deployments = data.to_a
+          comparisons = RailsPulse::DeploymentComparison.for(deployments)
 
           render json: {
-            data: data.map { |deployment| DeploymentSerializer.serialize(deployment) },
+            data: deployments.map { |deployment| DeploymentSerializer.serialize(deployment, comparison: comparisons[deployment.id]) },
             meta: meta
           }
         end
+
+        private
+
+        # The full revision or the start of one, so the short SHA a person
+        # reads from the CLI finds the same deployment as the full SHA.
+        def apply_revision_filter(scope)
+          return scope unless params[:revision].present?
+
+          scope.where(
+            "revision LIKE :prefix #{RailsPulse::LikePattern::CLAUSE}",
+            prefix: RailsPulse::LikePattern.starting_with(params[:revision])
+          )
+        end
       end
     end
   end

data/app/controllers/rails_pulse/api/v1/exceptions_controller.rb

@@ -33,6 +33,7 @@ module RailsPulse
 
           collection = RailsPulse::ExceptionGroup.order(sort => :desc, id: :desc)
           collection = collection.where(status: status) if status
+          collection = collection.where(fingerprint: params[:fingerprint]) if params[:fingerprint].present?
           collection = collection.where(last_seen_at: since_start..) if since_start
           collection = collection.where(last_seen_at: ..until_end) if until_end
           collection = apply_search(collection)

data/app/controllers/rails_pulse/api/v1/insights_controller.rb

@@ -0,0 +1,62 @@
+module RailsPulse
+  module Api
+    module V1
+      # What needs attention over one summary period, and whether the
+      # configured route and query thresholds fit what that period recorded.
+      # One period rather than a since/until window because a P95 cannot be
+      # combined across periods: an hour, day, week or month is read from its
+      # own summary rows.
+      class InsightsController < BaseController
+        PERIOD_TYPES = RailsPulse::Summary::PERIOD_TYPES
+        DEFAULT_PERIOD_TYPE = "week".freeze
+        STEPS = { "hour" => 1.hour, "day" => 1.day, "week" => 1.week, "month" => 1.month }.freeze
+
+        def show
+          period_type = params[:period].presence || DEFAULT_PERIOD_TYPE
+          unless PERIOD_TYPES.include?(period_type)
+            return render_bad_request("Unknown period '#{period_type}'. Use one of: #{PERIOD_TYPES.join(', ')}.")
+          end
+
+          at = parse_time_param(:at)
+          return if performed?
+
+          period_start = period_start_for(period_type, at)
+          period_end = RailsPulse::Summary.calculate_period_end(period_type, period_start)
+
+          render json: {
+            period: {
+              type:       period_type,
+              start:      period_start,
+              end:        period_end,
+              summarized: summarized?(period_type, period_start)
+            },
+            thresholds: {
+              routes:  RailsPulse.configuration.route_thresholds,
+              queries: RailsPulse.configuration.query_thresholds,
+              jobs:    RailsPulse.configuration.job_thresholds
+            },
+            needs_attention: RailsPulse::PeriodInsights.new(period_type: period_type, period_start: period_start).to_insights_data,
+            threshold_recommendations: RailsPulse::ConfigRecommendations
+              .for_period(period_type: period_type, period_start: period_start)
+              .to_recommendations
+          }
+        end
+
+        private
+
+        # The period containing `at`, or the latest one that has ended: the
+        # current period has no summary until it is over.
+        def period_start_for(period_type, at)
+          time = at ? at.in_time_zone : Time.current - STEPS[period_type]
+          RailsPulse::Summary.normalize_period_start(period_type, time)
+        end
+
+        # SummaryJob writes the overall request row for every period it
+        # summarizes, even an empty one.
+        def summarized?(period_type, period_start)
+          RailsPulse::Summary.overall_requests.exists?(period_type: period_type, period_start: period_start)
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/queries_controller.rb

@@ -20,16 +20,25 @@ module RailsPulse
             since_start ||= 24.hours.ago if until_end.nil?
             render_with_stats(since_start..until_end, sort || "total_duration")
           else
-            data, meta = paginated(RailsPulse::Query.all.order(:id))
+            data, meta = paginated(queries_scope.order(:id))
             render json: { data: data.map { |query| QuerySerializer.serialize(query) }, meta: meta }
           end
         end
 
         private
 
+        # `hashed_sql` is the key Rails Pulse Cloud holds for a query, so an
+        # exact match on it is how a caller gets from Cloud back to the SQL.
+        def queries_scope
+          scope = RailsPulse::Query.all
+          scope = scope.where(hashed_sql: params[:hashed_sql]) if params[:hashed_sql].present?
+          scope
+        end
+
         def render_with_stats(range, sort)
           base = RailsPulse::Operation.where.not(query_id: nil).where(occurred_at: range)
           base = apply_route_filter(base)
+          base = base.where(query_id: queries_scope.select(:id)) if params[:hashed_sql].present?
           total = base.distinct.count(:query_id)
 
           rows = base

data/app/controllers/rails_pulse/api/v1/requests_controller.rb

@@ -6,7 +6,7 @@ module RailsPulse
         STATUS_CODE  = /\A\d{3}\z/
 
         def index
-          collection = RailsPulse::Request.all.order(occurred_at: :desc, id: :desc)
+          collection = RailsPulse::Request.preload(:route).order(occurred_at: :desc, id: :desc)
 
           parsed_range = time_range
           return unless parsed_range
@@ -15,6 +15,7 @@ module RailsPulse
           collection = collection.where(occurred_at: since_start..) if since_start
           collection = collection.where(occurred_at: ..until_end) if until_end
           collection = apply_route_filter(collection)
+          collection = apply_path_prefix_filter(collection)
           collection = apply_status_filter(collection)
           return if performed?
 
@@ -38,6 +39,21 @@ module RailsPulse
           )
         end
 
+        # Requests whose route path starts with the prefix. A request the
+        # router did not recognise is stored under its raw path, so this is how
+        # a caller finds the paths behind a burst of 404s. A trailing `*` is
+        # dropped, so a grouped prefix such as `/wp-admin/*` can be passed as
+        # it is; `/*` and `*` therefore match every path.
+        def apply_path_prefix_filter(scope)
+          return scope unless params[:path_prefix].present?
+
+          prefix = params[:path_prefix].to_s.delete_suffix("*")
+          scope.joins(:route).where(
+            "rails_pulse_routes.path LIKE :prefix #{RailsPulse::LikePattern::CLAUSE}",
+            prefix: RailsPulse::LikePattern.starting_with(prefix)
+          )
+        end
+
         def apply_status_filter(scope)
           return scope unless params[:status].present?
 

data/app/controllers/rails_pulse/api/v1/routes_controller.rb

@@ -15,6 +15,11 @@ module RailsPulse
           end
 
           scope = RailsPulse::Route.all
+          # Exact matches, unlike `search`: a route is identified by its path
+          # and controller action together, and a substring would also return
+          # `/orders/:id/items` for `/orders/:id`.
+          scope = scope.where(path: params[:path]) if params[:path].present?
+          scope = scope.where(controller_action: params[:controller_action]) if params[:controller_action].present?
           if params[:search].present?
             term = RailsPulse::LikePattern.containing(params[:search].downcase)
             scope = scope.where(
@@ -37,7 +42,7 @@ module RailsPulse
 
         def render_with_stats(scope, range, sort)
           base = RailsPulse::Request.where(occurred_at: range)
-          base = base.where(route_id: scope.select(:id)) if params[:search].present?
+          base = base.where(route_id: scope.select(:id)) if %i[search path controller_action].any? { |name| params[name].present? }
 
           # HAVING rather than a filter over the fetched page: a route busy
           # enough to qualify can rank below the limit, and dropping it after

data/app/controllers/rails_pulse/dashboard_controller.rb

@@ -31,13 +31,17 @@ module RailsPulse
       @response_time_percentiles_chart_data = RailsPulse::Dashboard::Charts::ResponseTimePercentiles.new(**card_and_chart_options).to_chart_data
       @throughput_and_errors_chart_data = RailsPulse::Dashboard::Charts::ThroughputAndErrors.new(**card_and_chart_options).to_chart_data
 
+      # One StoragePressure serves the whole page: its items cost several
+      # aggregate queries, and three panels below ask for them.
+      storage_pressure = RailsPulse::Dashboard::StoragePressure.new
+
       # Needs Attention panel
-      @needs_attention = RailsPulse::Dashboard::NeedsAttention.new(disabled_tags: disabled_tags, show_non_tagged: show_non_tagged, period: period, window: window).to_attention_data
+      @needs_attention = RailsPulse::Dashboard::NeedsAttention.new(disabled_tags: disabled_tags, show_non_tagged: show_non_tagged, period: period, period_type: period_type, window: window, storage_pressure: storage_pressure).to_attention_data
 
       # System Health bar
-      @health_summary = RailsPulse::Dashboard::HealthSummary.new(disabled_tags: disabled_tags, show_non_tagged: show_non_tagged, period: period, window: window).to_health_data
+      @health_summary = RailsPulse::Dashboard::HealthSummary.new(disabled_tags: disabled_tags, show_non_tagged: show_non_tagged, period: period, period_type: period_type, window: window, storage_pressure: storage_pressure).to_health_data
 
-      @storage_status = RailsPulse::Dashboard::StorageStatus.new(cached_sizes: true)
+      @storage_status = RailsPulse::Dashboard::StorageStatus.new(estimated: true, storage_pressure: storage_pressure)
 
       # Deployments panel — scoped to the same window as the chart markers so
       # the panel and the markers drawn on the charts always agree.

data/app/jobs/rails_pulse/cloud_health_job.rb

@@ -0,0 +1,11 @@
+module RailsPulse
+  # Sends the health update for the minute just ended to Rails Pulse Cloud,
+  # deployments recorded since the last run, and any buffered batches whose
+  # retry is due. Schedule it every minute alongside SummaryJob. Does nothing
+  # unless config.cloud is set.
+  class CloudHealthJob < ApplicationJob
+    def perform
+      Cloud::Sync.new.minutely
+    end
+  end
+end

data/app/jobs/rails_pulse/cloud_sync_job.rb

@@ -0,0 +1,11 @@
+module RailsPulse
+  # Sends newly summarized hours, changed exception groups and deployments to
+  # Rails Pulse Cloud. SummaryJob enqueues it once its summaries are written,
+  # so it needs no schedule of its own. Does nothing unless config.cloud is
+  # set.
+  class CloudSyncJob < ApplicationJob
+    def perform
+      Cloud::Sync.new.hourly
+    end
+  end
+end

data/app/jobs/rails_pulse/summary_job.rb

@@ -19,6 +19,8 @@ module RailsPulse
         # Check if we should run monthly summary (first day of month)
         process_monthly_summary((target_hour.to_date - 1.month).beginning_of_month) if first_of_month?(target_hour)
       end
+
+      enqueue_cloud_sync
     rescue StandardError => e
       log_error(e)
       raise
@@ -26,6 +28,17 @@ module RailsPulse
 
     private
 
+    # Cloud receives an hour only once it is summarized, so the sync follows
+    # this job rather than running on a schedule of its own. A queue that
+    # refuses the job must not fail the summaries already written.
+    def enqueue_cloud_sync
+      return unless RailsPulse.configuration.cloud.enabled?
+
+      CloudSyncJob.perform_later
+    rescue StandardError => e
+      RailsPulse.logger.error "Could not enqueue the Rails Pulse Cloud sync: #{e.class} - #{e.message}"
+    end
+
     def midnight?(time)
       time.hour == 0
     end

data/app/models/rails_pulse/charts/base.rb

@@ -24,23 +24,14 @@ module RailsPulse
           .then { |q| @subject ? q.where(summarizable_id: @subject.id) : q }
       end
 
-      # Common helper for time step calculation
-      def time_step
-        @period_type.to_s == "hour" ? 3600 : 86400
-      end
-
       # Abstract method - must be implemented by subclasses
       def summarizable_type
         raise NotImplementedError, "#{self.class} must implement summarizable_type"
       end
 
-      # Common helper for padding missing data points with zeros
-      def pad_data_with_zeros(raw_data, start_time, end_time, step)
-        {}.tap do |padded|
-          (start_time.to_i..end_time.to_i).step(step) do |timestamp|
-            padded[timestamp] = raw_data[timestamp] || 0
-          end
-        end
+      # Every bucket in the window, with zero where there is no data.
+      def pad_data_with_zeros(raw_data)
+        @window.bucket_timestamps(@period_type).index_with { |timestamp| raw_data[timestamp] || 0 }
       end
     end
   end

data/app/models/rails_pulse/charts/percentile_chart_base.rb

@@ -47,9 +47,8 @@ module RailsPulse
         end
 
         # Convert to final values (weighted averages) and pad missing data
-        step = @period_type.to_s == "hour" ? 3600 : 86400
         daily_data = {}
-        (@window.start_time.to_i..@window.end_time.to_i).step(step) do |timestamp|
+        @window.bucket_timestamps(@period_type).each do |timestamp|
           if raw_data[timestamp]
             count = raw_data[timestamp][:total_count]
             daily_data[timestamp] = {

data/app/models/rails_pulse/cleanup_run.rb

@@ -0,0 +1,32 @@
+module RailsPulse
+  # One CleanupService run, stored as an Event of kind cleanup_run: `value`
+  # is the rows it deleted, `outcome` completed or failed, and `metadata` the
+  # per-table counts and any stages that failed. rails_pulse:status reads the
+  # latest to say whether cleanup is running at all; nothing else depends on
+  # these rows, so event retention prunes them like any other kind.
+  class CleanupRun
+    KIND = "cleanup_run".freeze
+    SUBJECT = "cleanup".freeze
+
+    class << self
+      def events
+        RailsPulse::Event.of_kind(KIND)
+      end
+
+      def record!(stats:, failed_stages: [], ran_at: Time.current)
+        RailsPulse::Event.create!(
+          kind:        KIND,
+          subject:     SUBJECT,
+          outcome:     failed_stages.any? ? "failed" : "completed",
+          value:       stats[:total_deleted].to_i,
+          occurred_at: ran_at,
+          metadata:    { time_based: stats[:time_based], count_based: stats[:count_based], failed_stages: failed_stages }.to_json
+        )
+      end
+
+      def latest
+        events.recent.first
+      end
+    end
+  end
+end

data/app/models/rails_pulse/cloud/buffered_batch.rb

@@ -0,0 +1,55 @@
+require "zlib"
+
+module RailsPulse
+  module Cloud
+    # A batch waiting to be sent to Rails Pulse Cloud, stored gzipped. It
+    # keeps its batch_id across retries, so Cloud recognises a resend. The
+    # buffer holds at most MAX_AGE or MAX_BYTES of batches, dropping the
+    # oldest first, so an outage cannot grow it without bound.
+    class BufferedBatch < RailsPulse::ApplicationRecord
+      self.table_name = "rails_pulse_cloud_batches"
+
+      MAX_AGE = 7.days
+      MAX_BYTES = 50.megabytes
+
+      validates :batch_id, :payload, :byte_size, :item_count, :next_attempt_at, presence: true
+
+      scope :due, ->(now = Time.current) { where(next_attempt_at: ..now).order(:created_at, :id) }
+
+      def self.ransackable_attributes(_auth_object = nil)
+        %w[batch_id byte_size item_count attempts next_attempt_at created_at]
+      end
+
+      def self.ransackable_associations(_auth_object = nil)
+        []
+      end
+
+      def self.enqueue!(batch, now: Time.current)
+        payload = Zlib.gzip(batch.to_json)
+        create!(batch_id: batch.batch_id, payload: payload, byte_size: payload.bytesize, item_count: batch.items.size,
+                next_attempt_at: now)
+      end
+
+      # Drops batches past MAX_AGE, then the oldest until the rest fit in
+      # MAX_BYTES. Returns how many were dropped.
+      def self.prune!(now = Time.current)
+        dropped = where(created_at: ...(now - MAX_AGE)).delete_all
+        total = sum(:byte_size)
+        return dropped if total <= MAX_BYTES
+
+        order(:created_at, :id).pluck(:id, :byte_size).each do |id, size|
+          break if total <= MAX_BYTES
+
+          dropped += where(id: id).delete_all
+          total -= size
+        end
+        dropped
+      end
+
+      # The stored batch as a hash with string keys.
+      def contents
+        JSON.parse(Zlib.gunzip(payload))
+      end
+    end
+  end
+end

data/app/models/rails_pulse/cloud/installation.rb

@@ -0,0 +1,55 @@
+module RailsPulse
+  module Cloud
+    # The one row naming this Rails Pulse database to Rails Pulse Cloud, and
+    # where its sync has got to. Hosts that share the database share the row,
+    # so their data is counted once; hosts with separate databases are
+    # separate installations, and Cloud adds them together.
+    class Installation < RailsPulse::ApplicationRecord
+      self.table_name = "rails_pulse_cloud_installations"
+
+      validates :installation_id, presence: true
+
+      def self.ransackable_attributes(_auth_object = nil)
+        %w[installation_id last_success_at last_error_at paused_until created_at]
+      end
+
+      def self.ransackable_associations(_auth_object = nil)
+        []
+      end
+
+      # The row, created with a new installation ID the first time it is
+      # asked for. A second process creating it at the same moment loses on
+      # the unique index and reads the winner's.
+      def self.current
+        first || create!(installation_id: SecureRandom.uuid)
+      rescue ActiveRecord::RecordNotUnique
+        first!
+      end
+
+      # The row if one exists, without creating it.
+      def self.existing
+        first
+      rescue ActiveRecord::ActiveRecordError
+        nil
+      end
+
+      def paused?(now = Time.current)
+        paused_until.present? && paused_until > now
+      end
+
+      def record_success!(deprecated_on: nil, now: Time.current)
+        update!(last_success_at: now, last_error: nil, last_error_at: nil, paused_until: nil, pause_reason: nil,
+                contract_deprecated_on: deprecated_on)
+      end
+
+      def record_error!(message, now: Time.current)
+        update!(last_error: message.to_s.truncate(2_000), last_error_at: now)
+      end
+
+      def pause!(until_time, reason, now: Time.current)
+        update!(paused_until: until_time, pause_reason: reason.to_s.truncate(2_000),
+                last_error: reason.to_s.truncate(2_000), last_error_at: now)
+      end
+    end
+  end
+end

data/app/models/rails_pulse/dashboard/concerns/attention_classification.rb

@@ -0,0 +1,104 @@
+module RailsPulse
+  module Dashboard
+    module Concerns
+      # How a route, query or job earns a place in a needs-attention list,
+      # shared by the dashboard panel (NeedsAttention, over the selected
+      # window) and the API's PeriodInsights (over one summary period) so the
+      # two never disagree about what is critical.
+      #
+      # Each classify method returns nil for something healthy, otherwise
+      # [severity, reason, metric, metric_sub, sort_score]. The includer sets
+      # @route_thresholds, @query_thresholds and @job_thresholds.
+      module AttentionClassification
+        include ThresholdConstants
+
+        private
+
+        # `span` finishes the error-rate reason: "this week", "this period".
+        def classify_route(p95, total, errors, error_rate, span)
+          if p95 >= @route_thresholds[:critical] || error_rate >= CRITICAL_ERROR_RATE
+            if error_rate >= CRITICAL_ERROR_RATE
+              [ :critical,
+                "#{error_rate}% error rate · #{total} requests #{span}",
+                "#{errors} errors",
+                "P95 #{p95.round(0).to_i}ms",
+                errors * total.to_f ]
+            else
+              [ :critical,
+                "#{p95.round(0).to_i}ms P95 · exceeds #{@route_thresholds[:critical]}ms threshold",
+                "#{p95.round(0).to_i}ms P95",
+                "#{total} requests",
+                p95 ]
+            end
+          elsif p95 >= @route_thresholds[:slow] || error_rate >= WARNING_ERROR_RATE
+            if error_rate >= WARNING_ERROR_RATE && p95 < @route_thresholds[:slow]
+              [ :warning,
+                "#{error_rate}% error rate · #{total} requests #{span}",
+                "#{errors} errors",
+                "P95 #{p95.round(0).to_i}ms",
+                errors * total.to_f ]
+            else
+              [ :warning,
+                "#{p95.round(0).to_i}ms P95 · #{error_rate > 0 ? "#{error_rate}% error rate" : "above slow threshold"}",
+                "#{p95.round(0).to_i}ms P95",
+                "#{total} requests",
+                p95 ]
+            end
+          end
+        end
+
+        def classify_query(p95, count)
+          if p95 >= @query_thresholds[:critical]
+            severity = :critical
+            reason   = "#{p95.round(0).to_i}ms P95 · exceeds #{@query_thresholds[:critical]}ms threshold"
+          elsif p95 >= @query_thresholds[:slow]
+            severity = :warning
+            reason   = "#{p95.round(0).to_i}ms P95 · above #{@query_thresholds[:slow]}ms slow threshold"
+          else
+            return
+          end
+
+          [ severity, reason, "#{p95.round(0).to_i}ms P95", "#{count} execution#{count == 1 ? "" : "s"}", p95 ]
+        end
+
+        def classify_job(failure_rate, p95, runs, failures, queue)
+          if failure_rate >= CRITICAL_JOB_FAILURE_RATE || p95 >= @job_thresholds[:critical]
+            if failure_rate >= CRITICAL_JOB_FAILURE_RATE
+              [ :critical,
+                "#{queue} queue · #{failure_rate}% failure rate",
+                "#{failures} / #{runs} failed",
+                "P95 #{p95.round(0).to_i}ms",
+                failures * runs.to_f ]
+            else
+              [ :critical,
+                "P95 #{p95.round(0).to_i}ms · exceeds #{@job_thresholds[:critical]}ms threshold",
+                "#{p95.round(0).to_i}ms P95",
+                "#{runs} runs",
+                p95 ]
+            end
+          elsif failure_rate >= WARNING_JOB_FAILURE_RATE || p95 >= @job_thresholds[:slow]
+            if failure_rate >= WARNING_JOB_FAILURE_RATE
+              [ :warning,
+                "#{queue} queue · #{failure_rate}% failure rate",
+                "#{failures} / #{runs} failed",
+                "P95 #{p95.round(0).to_i}ms",
+                failures * runs.to_f ]
+            else
+              [ :warning,
+                "P95 #{p95.round(0).to_i}ms · above slow threshold",
+                "#{p95.round(0).to_i}ms P95",
+                "#{runs} runs",
+                p95 ]
+            end
+          end
+        end
+
+        def truncate_sql(sql)
+          return "" if sql.blank?
+          cleaned = sql.gsub(/\s+/, " ").strip
+          cleaned.length > 80 ? "#{cleaned[0..79]}..." : cleaned
+        end
+      end
+    end
+  end
+end