rails_pulse 0.4.2 → 0.5.0.pre.2

data/lib/rails_pulse/configuration.rb

@@ -1,8 +1,81 @@
 module RailsPulse
   class Configuration
+    # Settings for sending summaries to Rails Pulse Cloud, read as
+    # `config.cloud.api_key` and so on. Sending is off unless both api_key
+    # and application are set.
+    class CloudSettings
+      DEFAULT_URL = "https://ingest.railspulse.com".freeze
+      # The prefix every Cloud key carries, so a leaked one is recognisable
+      # and api_token cannot be pasted here by mistake.
+      API_KEY_PREFIX = "rpc_".freeze
+      APPLICATION_FORMAT = /\A[a-z0-9][a-z0-9-]{0,62}\z/
+      MAX_ENVIRONMENT_LENGTH = 64
+      MAX_HOST_LABEL_LENGTH = 255
+
+      attr_accessor :api_key, :url, :application, :environment, :host_label
+
+      def initialize
+        @api_key = nil
+        @url = DEFAULT_URL
+        @application = nil
+        @environment = Rails.env.to_s
+        @host_label = ENV["RAILS_PULSE_HOST_LABEL"].presence
+      end
+
+      def enabled?
+        api_key.present? && application.present?
+      end
+
+      def to_h
+        { api_key: api_key, url: url, application: application, environment: environment, host_label: host_label }
+      end
+
+      def ==(other)
+        other.is_a?(CloudSettings) && to_h == other.to_h
+      end
+
+      # The key is left out so it does not end up in a log or console.
+      def inspect
+        "#<#{self.class.name} #{to_h.merge(api_key: api_key.present? ? "[FILTERED]" : nil).inspect}>"
+      end
+
+      def validate!
+        if !api_key.nil? && !(api_key.is_a?(String) && api_key.start_with?(API_KEY_PREFIX) && api_key.length > API_KEY_PREFIX.length)
+          raise ArgumentError, "cloud.api_key must be a Rails Pulse Cloud key starting with #{API_KEY_PREFIX}, or nil"
+        end
+
+        unless http_url?(url)
+          raise ArgumentError, "cloud.url must be an http or https URL, got #{url.inspect}"
+        end
+
+        if !application.nil? && !(application.is_a?(String) && application.match?(APPLICATION_FORMAT))
+          raise ArgumentError, "cloud.application must be the Application's slug in Rails Pulse Cloud " \
+                               "(lowercase letters, digits and dashes), got #{application.inspect}"
+        end
+
+        unless environment.is_a?(String) && environment.present? && environment.length <= MAX_ENVIRONMENT_LENGTH
+          raise ArgumentError, "cloud.environment must be a name of 1 to #{MAX_ENVIRONMENT_LENGTH} characters, got #{environment.inspect}"
+        end
+
+        if !host_label.nil? && !(host_label.is_a?(String) && host_label.present? && host_label.length <= MAX_HOST_LABEL_LENGTH)
+          raise ArgumentError, "cloud.host_label must be a name of 1 to #{MAX_HOST_LABEL_LENGTH} characters, or nil"
+        end
+      end
+
+      private
+
+      def http_url?(value)
+        uri = URI.parse(value.to_s)
+        uri.is_a?(URI::HTTP) && uri.host.present?
+      rescue URI::InvalidURIError
+        false
+      end
+    end
+
     attr_writer   :ignored_routes
     attr_accessor :enabled,
-                  :deployment_api_token,
+                  :api_token,
+                  :deployment_token,
                   :ignored_requests,
                   :ignored_queries,
                   :ignored_jobs,
@@ -16,6 +89,8 @@ module RailsPulse
                   :custom_asset_patterns,
                   :mount_path,
                   :full_retention_period,
+                  :event_retention_period,
+                  :event_retention_exempt_kinds,
                   :archiving_enabled,
                   :connects_to,
                   :authentication_enabled,
@@ -39,6 +114,15 @@ module RailsPulse
                   :comparison_window,
                   :hourly_summary_retention
 
+    # Two credentials, so a token handed to a coding agent cannot write.
+    # api_token reads the JSON API; deployment_token records deployment
+    # markers. Setting both to the same value restores single-token behaviour.
+    #
+    # deployment_api_token is the pre-0.5 name for the deployment credential
+    # and still writes deployments, which is all it ever authorized.
+    alias_method :deployment_api_token, :deployment_token
+    alias_method :deployment_api_token=, :deployment_token=
+
     # Override the attr_accessor setter to track explicit assignment.
     # The default (enabled in production) should not trigger a warning
     # when no authentication_method is configured — only an explicit
@@ -49,6 +133,8 @@ module RailsPulse
     end
 
     # Read-only access to thresholds (use setters for validation)
+    attr_reader :cloud
+
     attr_reader :route_thresholds,
                 :request_thresholds,
                 :query_thresholds,
@@ -59,6 +145,7 @@ module RailsPulse
 
     def initialize
       @enabled = true
+      @cloud = CloudSettings.new
       @route_thresholds = { slow: 500, very_slow: 1500, critical: 3000 }
       @request_thresholds = { slow: 700, very_slow: 2000, critical: 4000 }
       @query_thresholds = { slow: 100, very_slow: 500, critical: 1000 }
@@ -88,6 +175,8 @@ module RailsPulse
       @custom_asset_patterns = []
       @mount_path = nil
       @full_retention_period = 30.days
+      @event_retention_period = 90.days
+      @event_retention_exempt_kinds = []
       @archiving_enabled = true
       @max_table_records = {
         rails_pulse_operations: 100_000,
@@ -154,7 +243,7 @@ module RailsPulse
       # pruned aggressively because the 1-day UI view is all that reads them, so
       # raising this is the knob that buys hour-accurate change points further
       # back, at the cost of summary-table growth.
-      @hourly_summary_retention = 2.days
+      @hourly_summary_retention = 7.days
 
       # Deterministic regression rules. A change must clear both the ratio and
       # the absolute floor: without the floor, 2ms to 4ms reports as a 100%
@@ -233,6 +322,7 @@ module RailsPulse
       validate_query_service_level_objectives_settings!
       validate_comparison_settings!
       validate_schema_check_settings!
+      @cloud.validate!
     end
 
     private
@@ -262,6 +352,14 @@ module RailsPulse
         raise ArgumentError, "full_retention_period must be a time duration (e.g., 2.weeks), got #{@full_retention_period}"
       end
 
+      unless @event_retention_period.is_a?(ActiveSupport::Duration)
+        raise ArgumentError, "event_retention_period must be a time duration (e.g., 90.days), got #{@event_retention_period.inspect}"
+      end
+
+      unless @event_retention_exempt_kinds.is_a?(Array) && @event_retention_exempt_kinds.all?(String)
+        raise ArgumentError, "event_retention_exempt_kinds must be an array of strings, got #{@event_retention_exempt_kinds.inspect}"
+      end
+
       @max_table_records.each do |table, count|
         unless count.is_a?(Integer) && count > 0
           raise ArgumentError, "max_table_records[#{table}] must be a positive integer, got #{count}"

data/lib/rails_pulse/current.rb

@@ -0,0 +1,11 @@
+module RailsPulse
+  # Per-request/per-job state threaded from collection (middleware, job
+  # wrapper, subscribers) through to the writer. Thread-local; Rails' executor
+  # resets it automatically around requests and jobs, but RequestCollector and
+  # JobRunCollector also reset it explicitly so behaviour does not depend on
+  # the executor being present (rack-only apps, `perform_now` in a console).
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :rails_pulse_request_id, :rails_pulse_job_run_id, :rails_pulse_operations,
+              :skip_recording_rails_pulse_activity, :rails_pulse_captured_exception
+  end
+end

data/lib/rails_pulse/engine.rb

@@ -7,7 +7,8 @@ require "rails_pulse/subscribers/operation_subscriber"
 require "rails_pulse/subscribers/exception_subscriber"
 require "rails_pulse/job_run_collector"
 require "rails_pulse/active_job_extensions"
-require "request_store"
+require "rails_pulse/current"
+require "rails_pulse/scoped_inflector"
 require "rack/static"
 require "ransack"
 
@@ -38,15 +39,23 @@ module RailsPulse
     # would expect sql_query_normalizer.rb to define SQLQueryNormalizer and
     # fail to eager load in production. Pin the names of the files whose
     # basenames contain a common acronym so the gem's constants do not depend
-    # on the host's inflections.
+    # on the host's inflections. Applied only to files under this engine's
+    # root (see ScopedInflector), so a host's own app/controllers/api/ keeps
+    # whatever its inflections say.
     ACRONYM_SAFE_INFLECTIONS = {
+      "api" => "Api",
       "sql_query_normalizer" => "SqlQueryNormalizer",
       "csp_helper" => "CspHelper",
       "csp_test_controller" => "CspTestController"
     }.freeze
 
     initializer "rails_pulse.inflections", before: :set_autoload_paths do
-      Rails.autoloaders.main.inflector.inflect(ACRONYM_SAFE_INFLECTIONS) if Rails.respond_to?(:autoloaders)
+      if Rails.respond_to?(:autoloaders)
+        loader = Rails.autoloaders.main
+        loader.inflector = RailsPulse::ScopedInflector.new(
+          loader.inflector, root: RailsPulse::Engine.root.join("app"), overrides: ACRONYM_SAFE_INFLECTIONS
+        )
+      end
     end
 
     # Load Rake tasks

data/lib/rails_pulse/installers/config_updater.rb

@@ -5,7 +5,9 @@ module RailsPulse
     # the review: keep or discard hunks. Values that differ between a new
     # install and an upgrade (today: track_exceptions) use the gem default.
     class ConfigUpdater
-      ASSIGNMENT = /\A\s*(#\s*)?config\.(\w+)\s*=/.freeze
+      # Nested settings (`config.cloud.api_key`) are keyed by their full
+      # dotted name.
+      ASSIGNMENT = /\A\s*(#\s*)?config\.(\w+(?:\.\w+)*)\s*=/.freeze
       HASH_ENTRY = /\A\s*([a-z_][a-z0-9_]*):/.freeze
 
       UPGRADE_VALUE_OVERRIDES = {
@@ -128,8 +130,13 @@ module RailsPulse
         code.count("{") - code.count("}") + code.count("[") - code.count("]")
       end
 
+      # Every key the content names, and each prefix of a dotted one, so
+      # `config.cloud.api_key` mentions both `cloud.api_key` and `cloud`.
       def mentioned_keys(content)
-        content.scan(/config\.(\w+)/).flatten.uniq
+        content.scan(/config\.(\w+(?:\.\w+)*)/).flatten.flat_map do |key|
+          parts = key.split(".")
+          (1..parts.size).map { |length| parts.first(length).join(".") }
+        end.uniq
       end
 
       def missing_hash_entries(host, missing_keys)

data/lib/rails_pulse/job_run_collector.rb

@@ -7,9 +7,9 @@ module RailsPulse
         return yield unless tracking_enabled?
         return yield if ignore_job?(active_job)
 
-        previous_request_id = RequestStore.store[:rails_pulse_request_id]
-        previous_operations = RequestStore.store[:rails_pulse_operations]
-        previous_job_run_id = RequestStore.store[:rails_pulse_job_run_id]
+        previous_request_id = RailsPulse::Current.rails_pulse_request_id
+        previous_operations = RailsPulse::Current.rails_pulse_operations
+        previous_job_run_id = RailsPulse::Current.rails_pulse_job_run_id
 
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         occurred_at = Time.current
@@ -28,9 +28,9 @@ module RailsPulse
           job_run = nil
         end
 
-        RequestStore.store[:rails_pulse_request_id] = nil
-        RequestStore.store[:rails_pulse_job_run_id] = job_run&.id
-        RequestStore.store[:rails_pulse_operations] = []
+        RailsPulse::Current.rails_pulse_request_id = nil
+        RailsPulse::Current.rails_pulse_job_run_id = job_run&.id
+        RailsPulse::Current.rails_pulse_operations = []
 
         yield
 
@@ -65,7 +65,7 @@ module RailsPulse
           # checks skip_recording_rails_pulse_activity and would bail out.
           # The service's own SQL is already filtered by the rails_pulse_ prefix.
           RailsPulse::ExceptionCaptureService.capture(error, environment: Rails.env.to_s)
-          RequestStore.store[:rails_pulse_captured_exception] = error
+          RailsPulse::Current.rails_pulse_captured_exception = error
         rescue => e
           RailsPulse.logger.error "Failed to record job failure: #{e.class} - #{e.message}"
         end
@@ -76,9 +76,9 @@ module RailsPulse
         rescue => e
           RailsPulse.logger.error "Failed to persist job operations: #{e.class} - #{e.message}"
         ensure
-          RequestStore.store[:rails_pulse_job_run_id] = previous_job_run_id
-          RequestStore.store[:rails_pulse_operations] = previous_operations
-          RequestStore.store[:rails_pulse_request_id] = previous_request_id
+          RailsPulse::Current.rails_pulse_job_run_id = previous_job_run_id
+          RailsPulse::Current.rails_pulse_operations = previous_operations
+          RailsPulse::Current.rails_pulse_request_id = previous_request_id
         end
       end
 
@@ -155,14 +155,14 @@ module RailsPulse
       def save_operations(job_run)
         return unless job_run
 
-        ops = RequestStore.store[:rails_pulse_operations] || []
+        ops = RailsPulse::Current.rails_pulse_operations || []
         with_recording_suppressed do
           RailsPulse::Operation.persist_bulk(ops, job_run_id: job_run.id, request_id: nil)
         end
       rescue => e
         RailsPulse.logger.error "Failed to save job operations: #{e.class} - #{e.message}"
       ensure
-        RequestStore.store[:rails_pulse_operations] = nil
+        RailsPulse::Current.rails_pulse_operations = nil
       end
 
       def detect_adapter
@@ -198,11 +198,11 @@ module RailsPulse
       end
 
       def with_recording_suppressed
-        previous = RequestStore.store[:skip_recording_rails_pulse_activity]
-        RequestStore.store[:skip_recording_rails_pulse_activity] = true
+        previous = RailsPulse::Current.skip_recording_rails_pulse_activity
+        RailsPulse::Current.skip_recording_rails_pulse_activity = true
         yield
       ensure
-        RequestStore.store[:skip_recording_rails_pulse_activity] = previous
+        RailsPulse::Current.skip_recording_rails_pulse_activity = previous
       end
     end
   end

data/lib/rails_pulse/mcp/server.rb

@@ -0,0 +1,78 @@
+module RailsPulse
+  module Mcp
+    class Server
+      # The `mcp` gem is not a dependency of rails_pulse; the host adds it
+      # when it wants the MCP server.
+      class MissingDependencyError < StandardError; end
+
+      MISSING_DEPENDENCY_MESSAGE = "the `mcp` gem is not installed. Add `gem \"mcp\", \"~> 1.0\"` to the " \
+                                   "application's Gemfile (a development group is enough) and run bundle install, " \
+                                   "or `gem install mcp` when running rails-pulse outside Bundler.".freeze
+    end
+  end
+end
+
+begin
+  require "mcp"
+rescue LoadError
+  raise RailsPulse::Mcp::Server::MissingDependencyError, RailsPulse::Mcp::Server::MISSING_DEPENDENCY_MESSAGE
+end
+
+require "rails_pulse/version"
+require_relative "../cli/config"
+require_relative "../cli/client"
+require_relative "tools/helpers"
+require_relative "tools/slow_requests"
+require_relative "tools/errors"
+require_relative "tools/endpoint"
+require_relative "tools/queries"
+require_relative "tools/jobs"
+require_relative "tools/exceptions"
+require_relative "tools/exception_detail"
+require_relative "tools/routes"
+require_relative "tools/deployments"
+require_relative "tools/coverage"
+require_relative "tools/insights"
+
+module RailsPulse
+  module Mcp
+    # Read-only MCP server over stdio. Every tool goes through the JSON API
+    # with the same token as the CLI; nothing here touches the database or
+    # the application directly.
+    class Server
+      def self.start!
+        server = build_server
+        transport = ::MCP::Server::Transports::StdioTransport.new(server)
+        transport.open
+      end
+
+      def self.build_server(client: nil)
+        config = CLI::Config.load
+        client ||= CLI::Client.new(config)
+
+        ::MCP::Server.new(
+          name: "rails_pulse",
+          version: RailsPulse::VERSION,
+          tools: tools,
+          server_context: { client: client }
+        )
+      end
+
+      def self.tools
+        [
+          Tools::Routes,
+          Tools::SlowRequests,
+          Tools::Errors,
+          Tools::Endpoint,
+          Tools::Queries,
+          Tools::Jobs,
+          Tools::Exceptions,
+          Tools::ExceptionDetail,
+          Tools::Deployments,
+          Tools::Coverage,
+          Tools::Insights
+        ]
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/coverage.rb

@@ -0,0 +1,96 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      class Coverage < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_coverage"
+        description "Orientation for this installation: which application and environment it is, what has " \
+                    "been recorded and how recently, what retention keeps, and whether any requests were " \
+                    "dropped. Call this first in a session, and before reporting that nothing went wrong, " \
+                    "to tell 'no failures recorded' apart from 'no data captured'."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(properties: {})
+
+        def self.call(server_context:, **_options)
+          respond(server_context) do |client|
+            data = client.get("/coverage", {})
+            capabilities = client.get("/capabilities", {})
+
+            {
+              as_of: data["as_of"],
+              installation: installation(capabilities),
+              telemetry: data["telemetry"],
+              summaries: data["summaries"],
+              retention: data["retention"],
+              collection: data["collection"],
+              summary: build_summary(data),
+              next_steps: build_next_steps(data)
+            }
+          end
+        end
+
+        # Which application and environment answered, so results gathered
+        # against staging are not read as production.
+        private_class_method def self.installation(capabilities)
+          {
+            application: capabilities["application"],
+            environment: capabilities["environment"],
+            rails_pulse_version: capabilities["rails_pulse_version"]
+          }
+        end
+
+        private_class_method def self.build_summary(data)
+          requests = data.dig("telemetry", "requests") || {}
+          parts = []
+
+          parts << if requests["tracked"] == false
+            "Requests are not being recorded."
+          elsif requests["newest"]
+            "Requests recorded #{requests['oldest']} to #{requests['newest']} (#{requests['count']} rows)."
+          else
+            "No requests have been recorded."
+          end
+
+          collection = data["collection"] || {}
+          parts << "Collection gap suspected." if collection["gap_suspected"]
+          parts << "Summaries are behind." if data.dig("summaries", "stale")
+          parts.join(" ")
+        end
+
+        # An agent that reads "no errors" without these caveats will report an
+        # all-clear the data does not support.
+        private_class_method def self.build_next_steps(data)
+          steps = []
+          collection = data["collection"] || {}
+          summaries = data["summaries"] || {}
+
+          steps << collection["note"] if collection["note"]
+          steps << summaries["note"] if summaries["note"]
+
+          if (oldest = data.dig("telemetry", "requests", "oldest"))
+            steps << "Questions about anything before #{oldest} cannot be answered from raw requests; " \
+                     "retention has removed them. Summaries may still cover the window."
+          end
+
+          (data["telemetry"] || {}).each do |kind, info|
+            next unless info.is_a?(Hash) && info["tracked"] == false
+
+            label = kind.tr("_", " ").capitalize
+            steps << "#{label} are not being recorded (#{info['reason']}), so an empty #{kind.tr('_', ' ')} result " \
+                     "says nothing about whether any occurred."
+          end
+
+          steps << "Treat an empty result from another tool as 'not recorded' rather than 'did not happen' whenever a caveat above applies."
+          steps
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/deployments.rb

@@ -0,0 +1,117 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      class Deployments < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_deployments"
+        description "Recent deployments with revision, start and finish time, metadata, and whether each one made " \
+                    "the application slower or more error-prone. Each deployment's `comparison` sets the hour " \
+                    "before it started against the hour after it finished: `degraded` when average or p95 " \
+                    "response time is more than 1.5x and at least 50ms worse, or the error rate more than 1.25x " \
+                    "and at least a percentage point worse, `insufficient_data` under 10 requests in either hour, " \
+                    "`pending` until the hour after has been summarized, `unavailable` when it never will be " \
+                    "because SummaryJob is not running. Use it to pin an investigation to a release."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            **Helpers.window_properties("last_7_days"),
+            limit: {
+              type: "integer",
+              description: "Maximum number of deployments (1-100)",
+              default: 10
+            },
+            revision: {
+              type: "string",
+              description: "A full revision or the start of one, e.g. 'a1b2c3d'. Searched inside the window, " \
+                           "so widen period or pass since for an older deployment."
+            }
+          }
+        )
+
+        def self.call(period: "last_7_days", limit: 10, revision: nil, server_context:, **options)
+          respond(server_context) do |client|
+            window = resolve_window(period: period, since: options[:since], until_time: options[:until])
+            limit = limit.to_i.clamp(1, 100)
+            params = window_params(window).merge(limit: limit)
+            params[:revision] = revision if revision
+            result = client.get("/deployments", params)
+            deployments = (result["data"] || []).map { |d| format_deployment(d) }
+
+            {
+              window: window,
+              total_deployments: result.dig("meta", "total") || deployments.size,
+              deployments: deployments,
+              summary: build_summary(deployments),
+              next_steps: build_next_steps(deployments)
+            }
+          end
+        end
+
+        private_class_method def self.format_deployment(deployment)
+          {
+            revision: deployment["revision"],
+            short_revision: deployment["short_revision"],
+            started_at: deployment["started_at"],
+            finished_at: deployment["finished_at"],
+            duration_seconds: deployment["duration_seconds"],
+            in_progress: deployment["in_progress"] == true,
+            metadata: deployment["metadata"],
+            comparison: deployment["comparison"]
+          }
+        end
+
+        private_class_method def self.build_summary(deployments)
+          return "No deployments recorded in this period." if deployments.empty?
+
+          latest = deployments.first
+          state = latest[:in_progress] ? " (in progress)" : ""
+          summary = "#{deployments.size} deployment(s). Latest: #{latest[:short_revision]} at #{latest[:started_at]}#{state}."
+
+          degraded = deployments.select { |d| outcome(d) == "degraded" }
+          return summary if degraded.empty?
+
+          "#{summary} Degraded: #{degraded.map { |d| "#{d[:short_revision]} (#{degraded_metrics(d).join(', ')})" }.join('; ')}."
+        end
+
+        private_class_method def self.build_next_steps(deployments)
+          if deployments.empty?
+            return [ "Record deployments via `rails_pulse:record_deployment` or POST /deployments so an investigation can be pinned to a release." ]
+          end
+
+          # The hour after a pending or unavailable deployment has not been
+          # summarized, so point at one that can be compared when there is one.
+          target = deployments.find { |d| outcome(d) == "degraded" } ||
+            deployments.find { |d| d[:comparison] && !%w[pending unavailable].include?(outcome(d)) } ||
+            deployments.first
+          before = target.dig(:comparison, "before")
+          after = target.dig(:comparison, "after")
+          unless before && after && !%w[pending unavailable].include?(outcome(target))
+            return [ "Call rails_pulse_slow_requests and rails_pulse_errors with since: \"#{target[:started_at]}\" " \
+                     "and compare against the same length of time before it." ]
+          end
+
+          [
+            "To see what #{target[:short_revision]} changed, call rails_pulse_slow_requests and rails_pulse_errors " \
+            "with since: \"#{after['from']}\", until: \"#{after['to']}\", then with since: \"#{before['from']}\", " \
+            "until: \"#{before['to']}\", and compare the two."
+          ]
+        end
+
+        private_class_method def self.outcome(deployment)
+          deployment.dig(:comparison, "outcome")
+        end
+
+        private_class_method def self.degraded_metrics(deployment)
+          (deployment.dig(:comparison, "metrics") || []).select { |m| m["outcome"] == "degraded" }.map { |m| m["metric"] }
+        end
+      end
+    end
+  end
+end