rails_pulse 0.4.2 → 0.5.0.pre.2

data/lib/generators/rails_pulse/templates/db/rails_pulse_schema.rb

@@ -7,7 +7,7 @@ require "rails_pulse/route_indexes" unless defined?(RailsPulse::RouteIndexes)
 RailsPulse::Schema = lambda do |connection|
   adapter = connection.adapter_name.downcase
   # Skip if all tables already exist to prevent conflicts
-  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences ]
+  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences, :rails_pulse_events ]
 
   # Check which tables already exist
   existing_tables = required_tables.select { |table| connection.table_exists?(table) }
@@ -249,7 +249,7 @@ RailsPulse::Schema = lambda do |connection|
       t.string   :request_url,     comment: "Nullable — web requests only"
       t.string   :request_method,  comment: "GET, POST, etc."
       t.string   :environment,     comment: "production, staging, etc."
-      t.string   :deploy_sha,       comment: "Captured now even though Pro uses it — cannot backfill later"
+      t.string   :deploy_sha,       comment: "Captured at occurrence time — cannot backfill later"
       t.text     :request_params,   comment: "JSON hash of filtered request params — web requests only"
       t.datetime :occurred_at,      null: false
       t.timestamps
@@ -259,6 +259,24 @@ RailsPulse::Schema = lambda do |connection|
     connection.add_index :rails_pulse_exception_occurrences, :exception_group_id, name: "index_rp_exception_occurrences_on_group_id"
   end
 
+  unless connection.table_exists?(:rails_pulse_events)
+    connection.create_table :rails_pulse_events do |t|
+      t.string   :kind,        null: false, comment: "What noticed it, e.g. writer_heartbeat"
+      t.string   :subject,                  comment: "Who it is about: host:pid, rule name, job name, exception class"
+      t.string   :outcome,     null: false, comment: "sampled, triggered, clean, insufficient_data, ran"
+      t.decimal  :value,       precision: 15, scale: 6, comment: "The number behind it: requests dropped since the last sample, or the triggered metric value"
+      t.datetime :occurred_at, null: false
+      t.text     :message
+      t.text     :metadata,                 comment: "JSON with the kind-specific detail"
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_events, [ :kind, :occurred_at ],
+      name: "index_rp_events_on_kind_and_occurred_at"
+    connection.add_index :rails_pulse_events, [ :kind, :subject, :occurred_at ],
+      name: "index_rp_events_on_kind_subject_and_occurred_at"
+  end
+
   # Add indexes to existing tables for efficient aggregation
   unless connection.index_exists?(:rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation")
     connection.add_index :rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation"

data/lib/generators/rails_pulse/templates/migrations/install_rails_pulse_cloud_tables.rb

@@ -0,0 +1,30 @@
+# Generated by rails_pulse:install_cloud - loads the Rails Pulse Cloud schema definition
+class InstallRailsPulseCloudTables < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+  def up
+    if rails_pulse_cloud_installed?
+      say "Rails Pulse Cloud tables already exist. Skipping installation.", :yellow
+      return
+    end
+
+    # Load and execute the Cloud schema directly, so this migration always
+    # creates the tables as db/rails_pulse_cloud_schema.rb describes them.
+    schema_file = File.join(::Rails.root.to_s, "db/rails_pulse_cloud_schema.rb")
+    raise "Rails Pulse Cloud schema file not found at db/rails_pulse_cloud_schema.rb" unless File.exist?(schema_file)
+
+    say "Loading Rails Pulse Cloud schema from db/rails_pulse_cloud_schema.rb"
+    load schema_file
+    RailsPulse::CloudSchema.call(connection)
+    say "Rails Pulse Cloud tables created successfully"
+  end
+
+  def down
+    drop_table :rails_pulse_cloud_batches if table_exists?(:rails_pulse_cloud_batches)
+    drop_table :rails_pulse_cloud_installations if table_exists?(:rails_pulse_cloud_installations)
+  end
+
+  private
+
+  def rails_pulse_cloud_installed?
+    table_exists?(:rails_pulse_cloud_installations) && table_exists?(:rails_pulse_cloud_batches)
+  end
+end

data/lib/generators/rails_pulse/templates/rails_pulse.rb

@@ -327,22 +327,36 @@ RailsPulse.configure do |config|
   # }
 
   # ====================================================================================================
-  #                                             DEPLOYMENT TRACKING
+  #                                    API TOKENS AND DEPLOYMENT TRACKING
   # ====================================================================================================
-  # Record deployments to display vertical marker lines on performance charts, making it easy
-  # to correlate performance changes with specific releases.
+  # Two tokens authenticate what is not the dashboard, so a credential given to a coding agent
+  # cannot write anything. Both are sent as an `X-Rails-Pulse-Token` header.
   #
-  # API token for the POST /rails_pulse/deployments endpoint.
-  # When set, requests must include an `X-Rails-Pulse-Token` header matching this value.
-  # When nil, the endpoint falls back to the standard dashboard authentication.
+  # api_token reads the JSON API under /rails_pulse/api/v1 — what the `rails-pulse` CLI and the
+  # MCP server your coding agent uses talk to. Every endpoint under it is read-only.
+  #   config.api_token = Rails.application.credentials.dig(:rails_pulse, :api_token)
+  #   config.api_token = ENV["RAILS_PULSE_API_TOKEN"]
   #
-  # Set this in your CI/CD pipeline and store the value in credentials or an environment variable:
-  #   config.deployment_api_token = Rails.application.credentials.dig(:rails_pulse, :deployment_api_token)
-  #   config.deployment_api_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
+  # deployment_token records a release through POST /rails_pulse/deployments, which your CI calls.
+  # It is the only credential that endpoint accepts: api_token is refused there.
+  #   config.deployment_token = Rails.application.credentials.dig(:rails_pulse, :deployment_token)
+  #   config.deployment_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
   #
-  # Limits: revision ≤ 255 characters, metadata ≤ 4 KB serialized, started_at at most
-  # one hour in the future. Rows beyond max_table_records[:rails_pulse_deployments]
-  # are pruned oldest-first by the cleanup task.
+  # Set both to the same value if you would rather run one credential for both.
+  #
+  # With no api_token the JSON API refuses every request. With no deployment_token the deployments
+  # endpoint refuses every request too; a dashboard login is never accepted in its place. The
+  # rails_pulse:record_deployment and finish_deployment rake tasks need no token. (deployment_api_token
+  # is the pre-0.5 name for deployment_token and still works.)
+  #
+  # Point the CLI and MCP server at this app with `rails-pulse configure`, or set RAILS_PULSE_URL
+  # and RAILS_PULSE_TOKEN in the agent's environment. The MCP server needs `gem "mcp"` in this
+  # app's Gemfile (a development group is enough); Rails Pulse does not pull it into production.
+  #
+  # Deployments draw vertical markers on the charts so a change in performance can be lined up
+  # with the release that caused it. Limits: revision ≤ 255 characters, metadata ≤ 4 KB
+  # serialized, started_at at most one hour in the future. Rows beyond
+  # max_table_records[:rails_pulse_deployments] are pruned oldest-first by the cleanup task.
   #
   # Record a deployment from your CI/CD pipeline:
   #   curl -X POST https://yourapp.com/rails_pulse/deployments \
@@ -356,7 +370,37 @@ RailsPulse.configure do |config|
   # Metadata for the rake task comes from an environment variable, as a JSON object:
   #   RAILS_PULSE_DEPLOYMENT_METADATA='{"environment":"production"}' rake rails_pulse:record_deployment[abc1234]
 
-  # config.deployment_api_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
+  # config.api_token = ENV["RAILS_PULSE_API_TOKEN"]
+  # config.deployment_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
+
+  # ====================================================================================================
+  #                                            RAILS PULSE CLOUD
+  # ====================================================================================================
+  # Off unless both api_key and application are set; until then Rails Pulse makes no network calls.
+  # When on, it sends Rails Pulse Cloud an hourly summary of each route, query, job and exception,
+  # exception group and deployment records, and a health update every minute. It never sends request
+  # URLs or parameters, values in SQL, exception messages, backtraces or job arguments; the detail stays
+  # in this database. Everything in deployment metadata is sent as recorded.
+  # Run `rails rails_pulse:cloud:preview` to print exactly what would be sent.
+  #
+  # Cloud keeps its state in two tables of its own. Add them with
+  # `rails generate rails_pulse:install_cloud`, then migrate.
+  #
+  # The hourly sync runs after RailsPulse::SummaryJob. Schedule the health update every minute:
+  #   # config/recurring.yml
+  #   rails_pulse_cloud_health:
+  #     class: RailsPulse::CloudHealthJob
+  #     schedule: every minute
+  #
+  # The key comes from your Application's settings in Rails Pulse Cloud; application is its slug.
+  # config.cloud.api_key = ENV["RAILS_PULSE_CLOUD_API_KEY"]
+  # config.cloud.application = "your-app"
+  # Defaults to Rails.env.
+  # config.cloud.environment = Rails.env
+  # config.cloud.url = "https://ingest.railspulse.com"
+  # Hosts are named by hostname, which can show internal addresses and changes with every container.
+  # Set a stable label instead (defaults to RAILS_PULSE_HOST_LABEL).
+  # config.cloud.host_label = ENV["RAILS_PULSE_HOST_LABEL"]
 
   # ====================================================================================================
   #                                               DATA CLEANUP
@@ -376,6 +420,14 @@ RailsPulse.configure do |config|
   # Time-based retention - delete records older than this period
   config.full_retention_period = 30.days
 
+  # How long rows in rails_pulse_events are kept. The background writer's
+  # heartbeats are pruned after a day regardless.
+  config.event_retention_period = 90.days
+
+  # Event kinds exempt from event_retention_period — for rows a writer updates
+  # in place rather than appends.
+  config.event_retention_exempt_kinds = []
+
   # Count-based retention - maximum records to keep per table
   # After time-based cleanup, if tables still exceed these limits,
   # the oldest remaining records will be deleted to stay under the limit
@@ -404,12 +456,12 @@ RailsPulse.configure do |config|
   # config.baseline_window   = 28.days
   # config.comparison_window = 1.day
 
-  # Hourly summaries decide how precisely a change point can be placed. They are
-  # pruned at this age because the 1-day view is otherwise the only thing that
-  # reads them. Inside this window Rails Pulse can say a route slowed down at
-  # 14:00; beyond it, the finest answer is the day. Raising this buys precision
-  # at the cost of summary table growth.
-  # config.hourly_summary_retention = 2.days
+  # Hourly summaries decide how precisely a change point can be placed, and
+  # deployment comparisons read them. Inside this window Rails Pulse can say a
+  # route slowed down at 14:00 and compare a deploy's hour before and after;
+  # beyond it, the finest answer is the day and a deploy can no longer be
+  # compared. Raising this buys precision at the cost of summary table growth.
+  # config.hourly_summary_retention = 7.days
 
   # A change is reported as a regression only when it clears both the ratio and
   # the absolute floor for its unit. The ratio alone flags trivial millisecond

data/lib/generators/rails_pulse/upgrade_generator.rb

@@ -60,22 +60,6 @@ module RailsPulse
         end
       end
 
-      def has_separate_database_config?
-        config_path = File.join(root_path, "config/database.yml")
-        return false unless File.exist?(config_path)
-
-        require "yaml"
-        require "erb"
-        # Process ERB before YAML parsing — database.yml files commonly use ERB
-        # for environment-specific values. YAML.safe_load alone raises SyntaxError
-        # on ERB tags.
-        yaml_content = ERB.new(File.read(config_path)).result
-        db_config = YAML.safe_load(yaml_content, aliases: true)
-        db_config.values.any? { |env| env.is_a?(Hash) && env.key?("rails_pulse") }
-      rescue
-        false
-      end
-
       def rails_pulse_tables_exist?
         return false unless defined?(ActiveRecord::Base)
 
@@ -129,6 +113,7 @@ module RailsPulse
         # Refresh the schema file so fresh databases (test, CI) built from
         # db/rails_pulse_schema.rb include all current columns and tables.
         copy_file "db/rails_pulse_schema.rb", "db/rails_pulse_schema.rb", force: true
+        refresh_cloud_schema
         sync_initializer
 
         gem_migrations = get_gem_migrations
@@ -152,6 +137,14 @@ module RailsPulse
         end
       end
 
+      # Only an app that ran rails_pulse:install_cloud has the Cloud schema
+      # file; it is refreshed like the main one, never added.
+      def refresh_cloud_schema
+        return unless File.exist?(File.join(root_path, "db/rails_pulse_cloud_schema.rb"))
+
+        copy_file "db/rails_pulse_cloud_schema.rb", "db/rails_pulse_cloud_schema.rb", force: true
+      end
+
       def announce_new_features(new_migrations)
         notices = FEATURE_NOTICES.filter_map do |migration_key, notice|
           notice if new_migrations.any? { |filename| filename.include?(migration_key) }

data/lib/rails_pulse/cleanup_service.rb

@@ -29,9 +29,11 @@ module RailsPulse
 
       perform_time_based_cleanup
       perform_count_based_cleanup
+      perform_event_cleanup
       perform_summary_cleanup
 
       log_cleanup_summary
+      record_run
       raise @failures.first[:error] if @failures.any?
 
       @stats
@@ -116,6 +118,22 @@ module RailsPulse
       end
     end
 
+    # event_retention_exempt_kinds are rows a writer updates in place, which
+    # must survive so "last ran" never becomes "never ran"
+    def perform_event_cleanup
+      return unless @config.event_retention_period
+      return unless RailsPulse::Event.table_available?
+
+      cutoff_time = [ @config.event_retention_period.ago, 1.hour.ago ].min
+      run_stage(:time_based, :events) do
+        delete_in_batches(
+          RailsPulse::Event
+            .where.not(kind: @config.event_retention_exempt_kinds)
+            .where(occurred_at: ...cutoff_time)
+        )
+      end
+    end
+
     def perform_count_based_cleanup
       return unless @config.max_table_records&.any?
 
@@ -313,37 +331,26 @@ module RailsPulse
       RailsPulse::ExceptionOccurrence.where.not(exception_group_id: preserved_ids)
     end
 
-    # Prune oldest non-preserved, non-ignored groups when over the configured cap.
-    # Child occurrences must be deleted first — there is no ON DELETE CASCADE on the FK.
+    # Prune the oldest deletable groups when over the configured cap. Preserved
+    # and ignored groups are outside the cap: counting them would make a cap
+    # that they alone fill impossible to satisfy, so every run would trim the
+    # deletable groups for no gain (decision 0017). Child occurrences must be
+    # deleted first — there is no ON DELETE CASCADE on the FK.
     def cleanup_exception_groups_by_count
       max_records = @config.max_table_records[:rails_pulse_exception_groups]
       return 0 unless max_records
 
-      current_count = RailsPulse::ExceptionGroup.count
-      return 0 if current_count <= max_records
-
-      overage = current_count - max_records
       scope = RailsPulse::ExceptionGroup.where(preserve: false).where.not(status: "ignored")
-      # Only delete as many as the deletable population allows — if ignored/preserved
-      # groups dominate, we delete what we can and log when the cap cannot be met.
-      deletable_count = scope.count
-      records_to_delete = [ overage, deletable_count ].min
-      return 0 if records_to_delete <= 0
+      overage = scope.count - max_records
+      return 0 if overage <= 0
 
-      deleted = delete_parents_in_batches(
+      delete_parents_in_batches(
         scope,
         order_column: :last_seen_at,
         children: RailsPulse::ExceptionOccurrence,
         foreign_key: :exception_group_id,
-        limit: records_to_delete
+        limit: overage
       )
-
-      if overage > deletable_count
-        RailsPulse.logger.warn("[RailsPulse] Exception group cap #{max_records} cannot be met: " \
-          "#{current_count - deleted} remain (#{current_count - deletable_count} are preserved/ignored)")
-      end
-
-      deleted
     end
 
     # Delete groups whose last occurrence was removed — the orphan check and
@@ -374,6 +381,16 @@ module RailsPulse
       end
     end
 
+    # rails_pulse:status reads this to tell whether cleanup is scheduled. A
+    # failure to record must not turn a successful cleanup into a failed one.
+    def record_run
+      return unless RailsPulse::Event.table_available?
+
+      RailsPulse::CleanupRun.record!(stats: @stats, failed_stages: @failures.map { |failure| failure[:stage] })
+    rescue StandardError => e
+      RailsPulse.logger.error "Could not record the cleanup run: #{e.class}: #{e.message}"
+    end
+
     # Returns the period_end of the most recent completed hourly overall-request
     # summary, or nil if the summary job has never run. Records with occurred_at
     # before this timestamp have been fully aggregated and are safe to delete.

data/lib/rails_pulse/cli/agent_files/agents.md

@@ -0,0 +1,89 @@
+# Rails Pulse — Agent Integration
+
+Rails Pulse gives AI coding agents read access to a Rails application's performance data: requests, SQL queries, background jobs, exceptions and deployments, all from the application's own database. Two interfaces, one token.
+
+## MCP server
+
+```
+rails-pulse mcp
+```
+
+The server needs the `mcp` gem, which Rails Pulse does not depend on: add `gem "mcp", "~> 1.0"` to the application's Gemfile (a development group is enough), or `gem install mcp` when running `rails-pulse` outside Bundler.
+
+**Claude Code** (`~/.claude.json`):
+```json
+{
+  "mcpServers": {
+    "rails-pulse": {
+      "command": "rails-pulse",
+      "args": ["mcp"],
+      "env": {
+        "RAILS_PULSE_URL": "https://myapp.com",
+        "RAILS_PULSE_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "rails-pulse": { "command": "rails-pulse", "args": ["mcp"] }
+  }
+}
+```
+
+### Tools
+
+All tools are read-only. Each returns a `summary` and `next_steps`.
+
+| Tool | Purpose |
+|------|---------|
+| `rails_pulse_routes` | Discover endpoints with request volume, latency and errors |
+| `rails_pulse_slow_requests` | Slowest endpoints for a period |
+| `rails_pulse_coverage` | What has been recorded, how recently, and any collection gaps |
+| `rails_pulse_errors` | Recent errors grouped by endpoint |
+| `rails_pulse_exceptions` | Exception groups with status, count, location and latest message |
+| `rails_pulse_exception` | One group's recent occurrences with backtraces, request and params |
+| `rails_pulse_endpoint` | Deep performance profile of one endpoint |
+| `rails_pulse_queries` | Most expensive SQL queries with N+1 detection |
+| `rails_pulse_jobs` | Background job health and recent failures |
+| `rails_pulse_deployments` | Recent deployments with timing, metadata and a before/after comparison |
+| `rails_pulse_insights` | What needs attention over one hour, day, week or month, and threshold suggestions |
+
+Every tool that takes a `period` also takes `since` and `until` as ISO 8601 timestamps, read as UTC when no zone is given, and echoes the bounds it measured back as `window`. `period` itself is only `last_hour`, `last_24_hours` or `last_7_days` (plus `all` on `rails_pulse_exceptions`); any other window is `since`/`until`. `rails_pulse_insights` instead reads one whole summary period (`period`: `hour`, `day`, `week` or `month`, and `at` for a time inside it), so its P95s are exact. Use them to compare two fixed windows — the 24 hours before a release against the 24 hours after — rather than a relative period that moves between calls.
+
+## CLI
+
+The `rails-pulse` CLI works without MCP. Append `--json` for structured output.
+
+| Command | Description |
+|---------|-------------|
+| `rails-pulse routes list` | Tracked routes (`--since` adds request stats) |
+| `rails-pulse requests list` | Recorded requests with status and time filters |
+| `rails-pulse queries list` | SQL queries (`--since` adds timing stats) |
+| `rails-pulse jobs list` | Background jobs: lifetime stats, or one window's with `--since` / `--until` |
+| `rails-pulse job_runs list` | Individual job runs with errors |
+| `rails-pulse exceptions list` | Exception groups with status and occurrence counts |
+| `rails-pulse exceptions show ID` | One group with backtraces and recent occurrences |
+| `rails-pulse deployments list` | Recorded deployments, most recent first, with each one's comparison |
+| `rails-pulse coverage show` | What has been recorded, how recently, and any collection gaps |
+| `rails-pulse insights show` | What needs attention over one period, and threshold suggestions |
+
+Common flags on every list command: `--limit N` (1 to 500, default 25), `--offset N`, `--json`, `--since TIME` / `--until TIME` (ISO 8601; no zone means UTC).
+
+## Authentication
+
+Set `RAILS_PULSE_URL` and `RAILS_PULSE_TOKEN` (the application's `config.api_token`), or run `rails-pulse configure` to write `~/.rails-pulse`. That token is read-only; recording a deployment needs `config.deployment_token`, which these tools do not carry.
+
+## Investigation pattern
+
+1. Pin the time window to a deployment (`rails_pulse_deployments`); its `comparison` says whether response time or error rate got worse in the hour after it
+2. Identify slow or failing endpoints (`rails_pulse_insights` for the last day or week, `rails_pulse_slow_requests` for any window); resolve names with `rails_pulse_routes`
+3. Profile the suspect endpoint (`rails_pulse_endpoint`)
+4. Check errors (`rails_pulse_errors`)
+5. Inspect SQL and jobs (`rails_pulse_queries`, `rails_pulse_jobs`)
+6. Correlate with source code: pass the endpoint's `route_id` to `rails_pulse_queries` for the SQL inside it and the file and line each query came from
+7. Fix, deploy, and re-check the same endpoint

data/lib/rails_pulse/cli/agent_files/claude_skill.md

@@ -0,0 +1,182 @@
+---
+name: rails-pulse
+description: Investigate Rails application performance with Rails Pulse. Use when asked about slow endpoints, regressions after a deploy, expensive or N+1 SQL, error rates, failing background jobs, or whether a performance fix worked. Prefers the rails_pulse_* MCP tools; falls back to the rails-pulse CLI.
+---
+
+# Rails Pulse
+
+Rails Pulse records every request, SQL query, background job and exception of a Rails application in the application's own database. This skill gives you read access to that data so you can find what is slow, why, and whether a change fixed it. Nothing here can modify the application.
+
+## When to use it
+
+- Investigating a performance complaint or a slow endpoint
+- Diagnosing a regression after a deployment
+- Finding expensive or N+1 SQL queries
+- Investigating an increased error rate
+- Analysing background job failures or slowness
+- Validating whether a performance fix worked
+
+## Interfaces
+
+### MCP tools (preferred when available)
+
+All tools are read-only. Each returns a `summary` and `next_steps`.
+
+| Tool | Purpose |
+|------|---------|
+| `rails_pulse_routes` | Discover endpoints: request volume, latency and errors per route |
+| `rails_pulse_slow_requests` | The slowest endpoints for a period |
+| `rails_pulse_coverage` | What has been recorded, how recently, and any collection gaps |
+| `rails_pulse_errors` | Recent 4xx/5xx responses grouped by endpoint |
+| `rails_pulse_exceptions` | Exception groups with status, occurrence count, location and latest message |
+| `rails_pulse_exception` | One group's recent occurrences with full backtraces, request, params and deploy SHA |
+| `rails_pulse_endpoint` | Deep profile of one endpoint |
+| `rails_pulse_queries` | Most expensive SQL queries, with N+1 detection |
+| `rails_pulse_jobs` | Background job health and recent failures with error classes |
+| `rails_pulse_deployments` | Recent deployments with timing, metadata, and whether each one degraded response time or error rate |
+| `rails_pulse_insights` | What needs attention over one hour, day, week or month, and whether the thresholds fit it |
+
+### CLI
+
+The `rails-pulse` executable ships with the gem. Add `--json` for structured output.
+
+| Command | Purpose |
+|---------|---------|
+| `rails-pulse routes list --json` | Tracked routes (add `--since` for stats) |
+| `rails-pulse requests list --json` | Recorded requests with status and time filters |
+| `rails-pulse queries list --json` | SQL queries (add `--since` for timing stats) |
+| `rails-pulse jobs list --json` | Background jobs: lifetime stats, or one window's with `--since` / `--until` |
+| `rails-pulse job_runs list --json` | Individual job runs with error class and message |
+| `rails-pulse exceptions list --json` | Exception groups with status, count, location and message |
+| `rails-pulse exceptions show ID --json` | One group with backtraces, request, params and deploy SHA |
+| `rails-pulse deployments list --json` | Recorded deployments, most recent first, each with its before/after comparison |
+| `rails-pulse coverage show --json` | What has been recorded, how recently, and any collection gaps |
+| `rails-pulse insights show --period week --json` | What needs attention over one period, and suggested threshold changes |
+
+## Investigation workflow
+
+### 1. Establish the time period
+
+Check recent deployments first; a regression usually lines up with one.
+
+```
+rails_pulse_deployments(period: "last_7_days")
+rails-pulse deployments list --json
+```
+
+Each deployment carries a `comparison` of the hour before the deploy started against the hour
+after it finished. `degraded` means average or p95 response time got more than 1.5x and at
+least 50ms worse, or the error rate more than 1.25x and at least a percentage point worse; the
+`metrics` say which. `insufficient_data` means fewer than 10 requests in either hour, so it is
+not an all-clear; `pending` means the hour after has not been summarized yet; `unavailable`
+means it never will be because SummaryJob is not running. Use the `before` and `after` bounds
+as `since`/`until` for the tools below to see which endpoints changed.
+
+### 2. Identify affected endpoints
+
+For "what should I look at", start with the needs-attention list for the last complete day or
+week; each item carries the route, query or job `id` to drill into.
+
+```
+rails_pulse_insights(period: "day")
+rails-pulse insights show --period week --json
+```
+
+```
+rails_pulse_slow_requests(period: "last_24_hours", limit: 10)
+rails_pulse_routes(search: "checkout", period: "last_7_days")
+rails-pulse requests list --limit 50 --json
+```
+
+### 3. Profile the suspect endpoint
+
+```
+rails_pulse_endpoint(endpoint: "CheckoutController#create", period: "last_7_days")
+rails-pulse requests list --since 2026-06-01T00:00:00Z --json
+```
+
+### 4. Check errors
+
+```
+rails_pulse_errors(period: "last_24_hours", status: "5xx")
+rails-pulse requests list --status 5xx --since 2026-06-01T00:00:00Z --json
+```
+
+### 5. Inspect SQL and background jobs
+
+```
+rails_pulse_queries(period: "last_24_hours", sort: "total_duration")
+rails_pulse_queries(n_plus_one_only: true)
+rails_pulse_jobs(period: "last_24_hours")
+rails-pulse queries list --since 2026-06-01T00:00:00Z --json
+rails-pulse job_runs list --status failed --json
+```
+
+### 6. Correlate with source code
+
+Pass the endpoint's `route_id` to `rails_pulse_queries` to see only the SQL that ran inside it,
+with `source_locations` naming the file and line each query was issued from.
+
+```
+rails_pulse_queries(route: 42, period: "last_24_hours")
+```
+
+Start at those locations rather than searching for the SQL. Look for N+1 queries, missing
+indexes, expensive work in the request path, unnecessary serialization and missing caching.
+
+### 7. Fix, then validate
+
+After the fix is deployed, re-check the same endpoint over the period since the deploy.
+
+```
+rails_pulse_deployments(period: "last_24_hours")
+rails_pulse_endpoint(endpoint: "CheckoutController#create", period: "last_hour")
+```
+
+To show a change rather than a snapshot, measure the same endpoint over two fixed windows
+either side of the release. Every windowed tool takes `since` and `until` as ISO 8601
+timestamps, read as UTC when no zone is given, and echoes the bounds it used back as `window`.
+
+```
+rails_pulse_endpoint(endpoint: "CheckoutController#create", since: "2026-09-24T12:00:00Z", until: "2026-09-25T12:00:00Z")
+rails_pulse_endpoint(endpoint: "CheckoutController#create", since: "2026-09-25T12:00:00Z", until: "2026-09-26T12:00:00Z")
+```
+
+Use the deploy time as the boundary, and exclude the minutes around it when a rolling deploy
+makes them a mix of both versions.
+
+## Guidelines
+
+- **SQL is not always the cause.** External API calls, serialization, view rendering and application logic slow requests too.
+- **Use more than one tool.** Cross-reference latency with error rates, SQL timing and job performance before concluding.
+- **Orient once before investigating.** `rails_pulse_coverage` names the application, environment and version you are querying. Call it first, so findings are attributed to the installation that actually produced them.
+- **Confirm the data exists before reporting an all-clear.** An empty result means nothing was recorded, which only means nothing happened when collection was healthy over that window. Call `rails_pulse_coverage` before concluding a period was clean, and say so when it flags a gap, stale summaries or a kind that is not tracked.
+- **Check the error rate.** A fast endpoint with a high error rate may be failing early rather than performing well.
+- **Read percentiles, not just averages.** A low average with a high p95 or p99 means intermittent trouble.
+- **Weigh request volume.** A slow endpoint nobody calls may not be worth the work.
+- **Job figures cover the window.** `rails_pulse_jobs` reads them from summaries plus the runs not yet summarized. p95 and p99 are given only when one summary period holds the whole window; otherwise they are null and `note` says why, so compare averages and failure rates instead.
+- **Threshold suggestions are a starting point.** `rails_pulse_insights` suggests a `config_snippet` from one period's data. Check the period was typical (not a deploy day or an incident) before proposing the change, and say which period it came from.
+- **Check what the percentiles covered.** `rails_pulse_endpoint` computes them over the most recent requests it sampled, not the whole window. When `sampled_requests` is below `request_count` it says so in `latency.computed_over`; narrow the window until the two match before comparing percentiles across windows.
+
+## Authentication
+
+The CLI and MCP server read credentials from environment variables or `~/.rails-pulse`. The token is `config.api_token` in the application's Rails Pulse initializer. It is read-only: recording a deployment needs `config.deployment_token`, which these tools do not carry.
+
+```
+RAILS_PULSE_URL=https://myapp.com
+RAILS_PULSE_TOKEN=my-secret-token
+RAILS_PULSE_MOUNT_PATH=/rails_pulse   # optional, default /rails_pulse
+```
+
+```yaml
+# ~/.rails-pulse
+url: https://myapp.com
+token: my-secret-token
+mount_path: /rails_pulse
+```
+
+Interactive setup: `rails-pulse configure`.
+
+## CLI reference
+
+List commands accept `--limit N` (1 to 500, default 25), `--offset N` and `--json`. Every list command also accepts `--since TIME` and `--until TIME` as ISO 8601; a time with no zone is read as UTC. JSON output is `{ "data": [...], "meta": { "total", "limit", "offset" } }`; page with `--offset`.

data/lib/rails_pulse/cli/base_command.rb

@@ -0,0 +1,37 @@
+require "thor"
+require_relative "config"
+require_relative "client"
+
+module RailsPulse
+  module CLI
+    class BaseCommand < Thor
+      # A usage error (unknown command, missing argument, bad flag) exits 1,
+      # so a script or CI step running the CLI can tell it failed.
+      def self.exit_on_failure?
+        true
+      end
+
+      # A mistyped flag is an error rather than silently ignored, so
+      # `--limt 5` does not quietly return the default page.
+      check_unknown_options!
+
+      no_commands do
+        def with_error_handling
+          yield
+        rescue RailsPulse::CLI::Config::ConfigError => e
+          say "Error: #{e.message}.", :red
+          exit 1
+        rescue RailsPulse::CLI::Client::ApiError => e
+          say "API error: #{e.message}", :red
+          exit 1
+        end
+      end
+
+      private
+
+      def client
+        @client ||= Client.new
+      end
+    end
+  end
+end