rails_pulse 0.3.3 → 0.4.0.pre.2

data/app/services/rails_pulse/exception_message_sanitizer.rb

@@ -0,0 +1,152 @@
+module RailsPulse
+  # Strips PII from exception messages before they are persisted or exported.
+  #
+  # Extracted from ExceptionCaptureService so the same filtering applies to
+  # occurrence rows, job-run failure messages, and anything that ships a
+  # message off the machine (see RailsPulse::Exceptions::RawData).
+  #
+  # Three layers, applied in order:
+  #
+  # 1. Adapter-specific cleanup for ActiveRecord::StatementInvalid — the
+  #    driver error is kept, the offending statement and any literal values
+  #    the database echoes back (PG `DETAIL: Key (col)=(val)`, MySQL
+  #    `Duplicate entry 'val'`) are redacted.
+  # 2. `key=value` / `key: value` / `"key":"value"` pairs anywhere in the
+  #    text whose key matches the host's `config.filter_parameters` — the
+  #    same rules Rails applies to logged params, so `password=hunter2` and
+  #    `token: abc` are masked without any extra configuration.
+  # 3. An optional host hook, `config.exception_message_filter`, for anything
+  #    the generic rules cannot know about.
+  class ExceptionMessageSanitizer
+    MAX_LENGTH = 500
+    FILTERED = "[FILTERED]".freeze
+
+    # Matches `key=value`, `key: value`, `'key' => value` and JSON-style
+    # `"key":"value"` fragments in free text. A bare `:` only counts as a
+    # separator after a quoted key or when followed by whitespace, so URL
+    # schemes (`https://…`) and clock times (`12:30`) are not read as pairs.
+    # The value is a quoted string (with escapes) or a run of characters up
+    # to the next delimiter — including `&` and `?`, so query strings split
+    # per key. An unquoted value may not end right before another `=` or `:`
+    # (atomic, so `Error: token: x` is not read as `Error` = `token`), but
+    # may contain `://` so URLs survive as one value.
+    KEY_VALUE_PAIR = /
+      (?<lead>["'])?
+      (?<key>[A-Za-z_][\w.\-\[\]]*)
+      (?(<lead>)\k<lead>)
+      (?<sep>\s*=>\s*|\s*=\s*|\s*:\s+|(?(<lead>):|(?!)))
+      (?<value>
+        "(?:[^"\\]|\\.)*"
+        | '(?:[^'\\]|\\.)*'
+        | (?>(?:[^\s,;)\]}&\#?=:]|:(?=\/\/))+)(?![=:]|\s*=>)
+      )
+    /x
+
+    class << self
+      def call(message, statement_invalid: false, exception: nil)
+        new(message, statement_invalid: statement_invalid, exception: exception).call
+      end
+
+      def for_exception(exception)
+        call(exception.message.to_s, statement_invalid: statement_invalid?(exception), exception: exception)
+      end
+
+      private
+
+      # ActiveRecord may not be loaded in every host context this runs in.
+      def statement_invalid?(exception)
+        defined?(ActiveRecord::StatementInvalid) && exception.is_a?(ActiveRecord::StatementInvalid)
+      end
+    end
+
+    def initialize(message, statement_invalid: false, exception: nil)
+      @message = message.to_s
+      @statement_invalid = statement_invalid
+      @exception = exception
+    end
+
+    def call
+      message = @message
+      message = redact_statement_invalid(message) if @statement_invalid
+      message = filter_key_value_pairs(message)
+      message = apply_custom_filter(message)
+      message.truncate(MAX_LENGTH)
+    end
+
+    private
+
+    def redact_statement_invalid(message)
+      # Strip the appended SQL statement, which embeds the offending query
+      # including literal PII values.
+      message = message.split("\n").first.to_s
+      message = message.sub(/\s*:\s*(?:INSERT|UPDATE|DELETE|SELECT)\b.*/i, "")
+      # PostgreSQL: DETAIL: Key (email)=(alice@example.com) already exists.
+      message = message.gsub(/DETAIL:\s*Key\s*\([^)]*\)=\([^)]*\)/, "DETAIL: Key (…)=(…)")
+      # MySQL puts the offending value on the first line, ahead of the SQL:
+      # Duplicate entry 'alice@example.com' for key 'index_users_on_email'
+      message.gsub(/Duplicate entry '(?:[^'\\]|\\.)*'/i, "Duplicate entry '#{FILTERED}'")
+    end
+
+    # Rails' ParameterFilter only masks by key, so on its own it does nothing
+    # for a message like "login failed password=hunter2". Scan the text for
+    # key/value fragments and ask the filter about each key individually —
+    # this reuses the host's exact matching rules (substring, regexp, and
+    # proc filters alike).
+    def filter_key_value_pairs(message)
+      filter = parameter_filter
+      return message unless filter
+
+      # A host that filters a key literally named "message" wants the whole
+      # thing gone; honour that before looking inside it.
+      whole = filter.filter_param("message", message)
+      return whole unless whole.equal?(message)
+
+      message.gsub(KEY_VALUE_PAIR) do
+        match = Regexp.last_match
+        key   = match[:key]
+        value = match[:value]
+
+        if filter.filter(key => value)[key] == value
+          match[0]
+        else
+          lead = match[:lead].to_s
+          "#{lead}#{key}#{lead}#{match[:sep]}#{FILTERED}"
+        end
+      end
+    end
+
+    def apply_custom_filter(message)
+      hook = custom_filter
+      return message unless hook
+
+      result = hook.arity == 1 ? hook.call(message) : hook.call(message, @exception)
+      result.to_s
+    rescue => e
+      # The hook exists to remove sensitive data; if it blows up, storing the
+      # unfiltered message would defeat its purpose. Fail closed.
+      RailsPulse.logger.warn("[RailsPulse] exception_message_filter raised #{e.class}: #{e.message}; message redacted")
+      FILTERED
+    end
+
+    def parameter_filter
+      patterns = filter_parameters
+      return nil if patterns.blank?
+      return nil unless defined?(ActiveSupport::ParameterFilter)
+
+      ActiveSupport::ParameterFilter.new(patterns)
+    end
+
+    def filter_parameters
+      Rails.application.config.filter_parameters
+    rescue
+      []
+    end
+
+    def custom_filter
+      hook = RailsPulse.configuration&.exception_message_filter
+      hook if hook.respond_to?(:call)
+    rescue
+      nil
+    end
+  end
+end

data/app/services/rails_pulse/operations/change_point.rb

@@ -0,0 +1,144 @@
+module RailsPulse
+  module Operations
+    # Estimates when a metric changed, by finding the split in a time series that
+    # best separates it into a "before" and an "after".
+    #
+    # The method is a single-pass step search: try every split with enough
+    # periods on each side, and keep the one that maximises the gap between the
+    # traffic-weighted mean before it and after it. That is deliberately simpler
+    # than a statistical change-point model. It is explainable — the UI can show
+    # a user the two means it compared — and it does not need a distributional
+    # assumption to defend.
+    #
+    # Precision is bounded by what summaries still exist. Hourly summaries are
+    # pruned at `hourly_summary_retention` (2 days by default), so a change point
+    # can only be pinned to the hour inside that window. Beyond it the answer is
+    # a day, and `granularity` says which the caller got — never silently one
+    # pretending to be the other.
+    class ChangePoint
+      MIN_PERIODS_PER_SIDE = 2
+
+      Result = Struct.new(
+        :at, :granularity, :before_value, :after_value, :before_count, :after_count,
+        keyword_init: true
+      ) do
+        def ratio
+          return nil if before_value.nil? || before_value.zero?
+
+          after_value / before_value
+        end
+
+        def delta
+          return nil if before_value.nil? || after_value.nil?
+
+          after_value - before_value
+        end
+
+        # True when the estimate sits inside the retained hourly window, so `at`
+        # is accurate to the hour rather than the day.
+        def hourly?
+          granularity == "hour"
+        end
+
+        def to_h
+          {
+            at:           at,
+            granularity:  granularity,
+            before_value: before_value,
+            after_value:  after_value,
+            before_count: before_count,
+            after_count:  after_count,
+            ratio:        ratio,
+            delta:        delta
+          }
+        end
+      end
+
+      # @param subject [Route, Query, Job, :requests]
+      # @param metric [Symbol] :p50, :p95, :p99, :avg or :error_rate
+      # @param range [Range<Time>] the window to search within
+      # @return [Result, nil] nil when there is not enough of a series to split
+      def self.call(subject, metric: :p95, range: nil)
+        range ||= default_range
+        new(subject, metric: metric, range: range).call
+      end
+
+      def self.default_range
+        (RailsPulse.configuration.baseline_window.ago..Time.current)
+      end
+
+      def initialize(subject, metric:, range:)
+        @subject = Subject.wrap(subject)
+        @metric  = Metric.validate!(metric)
+        @range   = range
+      end
+
+      def call
+        series = best_available_series
+        return nil if series.nil? || series.size < MIN_PERIODS_PER_SIDE * 2
+
+        split = best_split(series)
+        return nil if split.nil?
+
+        before = series.points[0...split]
+        after  = series.points[split..]
+
+        Result.new(
+          at:           after.first.period_start,
+          granularity:  series.period_type,
+          before_value: Metric.combine(before.map { |p| [ p.value, p.count ] }),
+          after_value:  Metric.combine(after.map { |p| [ p.value, p.count ] }),
+          before_count: before.sum(&:count),
+          after_count:  after.sum(&:count)
+        )
+      end
+
+      private
+
+      attr_reader :subject, :metric, :range
+
+      # Prefer hourly precision, but only where hourly summaries are actually
+      # retained. Asking for hours outside that window returns a truncated series
+      # that would place the change point at the edge of retention rather than
+      # where it happened — worse than honestly answering in days.
+      def best_available_series
+        hourly = hourly_series
+        return hourly if hourly && hourly.size >= MIN_PERIODS_PER_SIDE * 2
+
+        daily = Series.load(subject, metric: metric, range: range, period_type: "day")
+        daily.empty? ? hourly : daily
+      end
+
+      def hourly_series
+        retention_start = RailsPulse.configuration.hourly_summary_retention.ago
+        return nil if range.end && range.end < retention_start
+
+        hourly_range = ([ range.begin, retention_start ].compact.max)..range.end
+        series = Series.load(subject, metric: metric, range: hourly_range, period_type: "hour")
+        series.empty? ? nil : series
+      end
+
+      # Returns the index the "after" side starts at, or nil if no split has
+      # enough periods on both sides.
+      def best_split(series)
+        points = series.points
+        best_index = nil
+        best_gap   = 0.0
+
+        (MIN_PERIODS_PER_SIDE..(points.size - MIN_PERIODS_PER_SIDE)).each do |index|
+          before = Metric.combine(points[0...index].map { |p| [ p.value, p.count ] })
+          after  = Metric.combine(points[index..].map  { |p| [ p.value, p.count ] })
+          next if before.nil? || after.nil?
+
+          gap = (after - before).abs
+          if gap > best_gap
+            best_gap   = gap
+            best_index = index
+          end
+        end
+
+        best_index
+      end
+    end
+  end
+end

data/app/services/rails_pulse/operations/compare.rb

@@ -0,0 +1,92 @@
+module RailsPulse
+  module Operations
+    # Measures a subject's recent behaviour against its own history.
+    #
+    # This is the entry point for "what changed?", the question the dashboard's
+    # threshold rules cannot answer. It reads only from summaries, which cleanup
+    # retains at day granularity indefinitely, so a comparison stays available
+    # long after the raw requests behind it have aged out.
+    class Compare
+      # @param subject [Route, Query, Job, :requests]
+      # @param metric [Symbol] :p50, :p95, :p99, :avg or :error_rate
+      # @param as_of [Time] treat this as "now"; the current window ends here
+      # @return [Comparison] always returned — ask it whether it is comparable
+      def self.call(subject, metric: :p95, as_of: Time.current)
+        new(subject, metric: metric, as_of: as_of).call
+      end
+
+      # Compares every subject of a kind in one pass, for callers that need to
+      # rank or filter across an application rather than inspect one route.
+      #
+      # @param scope [ActiveRecord::Relation, Class] Route, Query or Job
+      # @return [Array<Comparison>] only comparisons with usable data on both sides
+      def self.scan(scope, metric: :p95, as_of: Time.current)
+        scope.find_each.filter_map do |record|
+          comparison = call(record, metric: metric, as_of: as_of)
+          comparison if comparison.sufficient_data?
+        end
+      end
+
+      def initialize(subject, metric: :p95, as_of: Time.current)
+        @subject = Subject.wrap(subject)
+        @metric  = Metric.validate!(metric)
+        @as_of   = as_of
+      end
+
+      def call
+        current  = Series.load(subject, metric: metric, range: current_range,  period_type: period_type)
+        baseline = Series.load(subject, metric: metric, range: baseline_range, period_type: period_type)
+
+        Comparison.new(
+          subject:          subject,
+          metric:           metric,
+          period_type:      period_type,
+          baseline_value:   baseline.value,
+          baseline_count:   baseline.total_count,
+          baseline_periods: baseline.size,
+          current_value:    current.value,
+          current_count:    current.total_count
+        )
+      end
+
+      private
+
+      attr_reader :subject, :metric, :as_of
+
+      def period_type
+        "day"
+      end
+
+      def comparison_window
+        RailsPulse.configuration.comparison_window
+      end
+
+      def baseline_window
+        RailsPulse.configuration.baseline_window
+      end
+
+      # Windows are aligned to period boundaries rather than measured back from
+      # the wall clock. Day summaries are written by SummaryJob at midnight for
+      # the day that just ended, so an unaligned "now minus 24 hours" window
+      # straddles two day-periods and matches neither — at noon it would contain
+      # no day summary at all. Aligning means the current window is always the
+      # most recent *complete* day.
+      def current_end
+        RailsPulse::Summary.normalize_period_start(period_type, as_of)
+      end
+
+      # The recent slice under test: the last complete period(s).
+      def current_range
+        (current_end - comparison_window)...current_end
+      end
+
+      # History, ending where the current window begins. The two must not
+      # overlap: including the period under test in its own baseline damps
+      # exactly the change the comparison exists to detect.
+      def baseline_range
+        baseline_end = current_end - comparison_window
+        (baseline_end - baseline_window)...baseline_end
+      end
+    end
+  end
+end

data/app/services/rails_pulse/operations/comparison.rb

@@ -0,0 +1,126 @@
+module RailsPulse
+  module Operations
+    # The result of measuring a recent window against a historical baseline.
+    #
+    # This is a value object on purpose. It is the shape callers outside this
+    # namespace — dashboards today, findings and Pro tooling later — are expected
+    # to depend on, so it carries every number needed to explain the verdict
+    # rather than just the verdict.
+    class Comparison
+      attr_reader :subject, :metric, :baseline_value, :baseline_count, :baseline_periods,
+                  :current_value, :current_count, :period_type
+
+      def initialize(subject:, metric:, period_type:,
+                     baseline_value:, baseline_count:, baseline_periods:,
+                     current_value:, current_count:)
+        @subject          = subject
+        @metric           = metric
+        @period_type      = period_type
+        @baseline_value   = baseline_value
+        @baseline_count   = baseline_count
+        @baseline_periods = baseline_periods
+        @current_value    = current_value
+        @current_count    = current_count
+      end
+
+      # True when both sides produced a value. A comparison can be well-formed
+      # and still not be a regression; this only says the arithmetic is possible.
+      def comparable?
+        !baseline_value.nil? && !current_value.nil? && baseline_value.to_f > 0
+      end
+
+      def delta
+        return nil unless comparable?
+
+        current_value - baseline_value
+      end
+
+      def ratio
+        return nil unless comparable?
+
+        current_value / baseline_value
+      end
+
+      def percent_change
+        return nil unless comparable?
+
+        (ratio - 1) * 100
+      end
+
+      def direction
+        return :unknown unless comparable?
+        return :flat if delta.abs < Float::EPSILON
+
+        delta.positive? ? :up : :down
+      end
+
+      def unit
+        Metric.unit(metric)
+      end
+
+      # Enough traffic and enough history for the comparison to mean anything.
+      # Checked separately from `regression?` so a caller can tell "nothing
+      # happened" apart from "not enough data to say".
+      def sufficient_data?
+        return false unless comparable?
+
+        thresholds = RailsPulse.configuration.regression_thresholds
+
+        baseline_periods >= thresholds[:min_baseline_periods] &&
+          baseline_count  >= thresholds[:min_samples] &&
+          current_count   >= thresholds[:min_samples]
+      end
+
+      # A deterministic regression: the metric grew by at least the configured
+      # multiple AND by at least the absolute floor for its unit. Both gates
+      # matter — the ratio alone flags trivial millisecond noise on fast
+      # endpoints, and the floor alone flags slow endpoints that never changed.
+      def regression?
+        return false unless sufficient_data?
+        return false unless Metric.higher_is_worse?(metric)
+
+        thresholds = RailsPulse.configuration.regression_thresholds
+        floor      = metric == :error_rate ? thresholds[:min_delta_rate] : thresholds[:min_delta_ms]
+
+        ratio >= thresholds[:ratio] && delta >= floor
+      end
+
+      # One line a human can check the maths against. Findings and API output
+      # both render from this rather than each inventing their own phrasing.
+      def summary
+        return "not enough data to compare" unless comparable?
+
+        "#{metric.to_s.upcase} #{format_value(baseline_value)} → #{format_value(current_value)} " \
+          "(#{percent_change.positive? ? '+' : ''}#{percent_change.round(1)}%)"
+      end
+
+      def to_h
+        {
+          subject_type:     subject.type,
+          subject_id:       subject.id,
+          subject_label:    subject.label,
+          metric:           metric,
+          unit:             unit,
+          period_type:      period_type,
+          baseline_value:   baseline_value,
+          baseline_count:   baseline_count,
+          baseline_periods: baseline_periods,
+          current_value:    current_value,
+          current_count:    current_count,
+          delta:            delta,
+          ratio:            ratio,
+          percent_change:   percent_change,
+          direction:        direction,
+          sufficient_data:  sufficient_data?,
+          regression:       regression?
+        }
+      end
+
+      private
+
+      def format_value(value)
+        metric == :error_rate ? "#{value.round(2)}%" : "#{value.round(0).to_i}ms"
+      end
+    end
+  end
+end

data/app/services/rails_pulse/operations/metric.rb

@@ -0,0 +1,63 @@
+module RailsPulse
+  module Operations
+    # Maps the metric names the Operations API accepts onto the summary columns
+    # that back them, and knows how to aggregate each one across several summary
+    # rows.
+    #
+    # Duration metrics are traffic-weighted: a day with 10,000 requests should
+    # move a baseline further than a day with 12. Averaging the stored
+    # percentiles unweighted would let a quiet Sunday count as much as a busy
+    # Monday and make every baseline noisy.
+    module Metric
+      DURATION_COLUMNS = {
+        p50: "p50_duration",
+        p95: "p95_duration",
+        p99: "p99_duration",
+        avg: "avg_duration"
+      }.freeze
+
+      SUPPORTED = (DURATION_COLUMNS.keys + [ :error_rate ]).freeze
+
+      # Higher is worse for every metric currently supported, but stating it
+      # explicitly keeps the comparison code from assuming it forever.
+      def self.higher_is_worse?(_metric)
+        true
+      end
+
+      def self.validate!(metric)
+        return metric.to_sym if SUPPORTED.include?(metric.to_sym)
+
+        raise ArgumentError, "unsupported metric #{metric.inspect} — expected one of #{SUPPORTED.join(', ')}"
+      end
+
+      def self.unit(metric)
+        metric.to_sym == :error_rate ? "%" : "ms"
+      end
+
+      # SQL that reduces a set of summary rows to a single value for this metric.
+      # NULLIF guards the zero-count case rather than letting the database raise
+      # or return a division artifact.
+      def self.aggregate_sql(metric)
+        if metric.to_sym == :error_rate
+          "SUM(rails_pulse_summaries.error_count) * 100.0 / " \
+            "NULLIF(SUM(rails_pulse_summaries.count), 0)"
+        else
+          column = DURATION_COLUMNS.fetch(metric.to_sym)
+          "SUM(rails_pulse_summaries.#{column} * rails_pulse_summaries.count) / " \
+            "NULLIF(SUM(rails_pulse_summaries.count), 0)"
+        end
+      end
+
+      # Reduces an already-loaded set of [value, count] pairs the same way
+      # aggregate_sql would. Used by change-point detection, which needs the
+      # per-period series in memory anyway and should not round-trip per split.
+      def self.combine(pairs)
+        total_count = pairs.sum { |(_value, count)| count.to_i }
+        return nil if total_count.zero?
+
+        weighted = pairs.sum { |(value, count)| value.to_f * count.to_i }
+        weighted / total_count
+      end
+    end
+  end
+end

data/app/services/rails_pulse/operations/series.rb

@@ -0,0 +1,84 @@
+module RailsPulse
+  module Operations
+    # Loads a subject's metric as an ordered time series of summary periods.
+    #
+    # Every operation in this namespace reads through here, so there is exactly
+    # one place that knows how summaries are queried. The row counts involved are
+    # small by construction — 30 day-periods for a month of baseline, 48
+    # hour-periods for the retained hourly window — so the reduction happens in
+    # Ruby rather than in SQL. That keeps one code path across SQLite, PostgreSQL
+    # and MySQL instead of three dialects of weighted average.
+    class Series
+      Point = Struct.new(:period_start, :period_end, :value, :count, keyword_init: true)
+
+      attr_reader :subject, :metric, :period_type, :points
+
+      def self.load(subject, metric:, range:, period_type: "day")
+        subject = Subject.wrap(subject)
+        metric  = Metric.validate!(metric)
+
+        rows = subject.summaries
+          .where(period_type: period_type)
+          .where(period_start: range)
+          .order(:period_start)
+          .pluck(:period_start, :period_end, :count, :p50_duration, :p95_duration, :p99_duration, :avg_duration, :error_count)
+
+        points = rows.filter_map do |period_start, period_end, count, p50, p95, p99, avg, error_count|
+          value = extract(metric, p50: p50, p95: p95, p99: p99, avg: avg, count: count, error_count: error_count)
+          next if value.nil?
+
+          Point.new(period_start: period_start, period_end: period_end, value: value.to_f, count: count.to_i)
+        end
+
+        new(subject: subject, metric: metric, period_type: period_type, points: points)
+      end
+
+      def self.extract(metric, p50:, p95:, p99:, avg:, count:, error_count:)
+        case metric
+        when :p50 then p50
+        when :p95 then p95
+        when :p99 then p99
+        when :avg then avg
+        when :error_rate
+          count.to_i.zero? ? nil : (error_count.to_i * 100.0 / count.to_i)
+        end
+      end
+      private_class_method :extract
+
+      def initialize(subject:, metric:, period_type:, points:)
+        @subject     = subject
+        @metric      = metric
+        @period_type = period_type
+        @points      = points
+      end
+
+      def empty?
+        points.empty?
+      end
+
+      def size
+        points.size
+      end
+
+      # Total observations behind the series — requests, executions or runs,
+      # depending on the subject. Used to decide whether a comparison has enough
+      # traffic to be worth reporting.
+      def total_count
+        @total_count ||= points.sum(&:count)
+      end
+
+      # The traffic-weighted value across every period in the series.
+      def value
+        @value ||= Metric.combine(points.map { |point| [ point.value, point.count ] })
+      end
+
+      def first_period_start
+        points.first&.period_start
+      end
+
+      def last_period_start
+        points.last&.period_start
+      end
+    end
+  end
+end