rails_pulse 0.4.2 → 0.5.0.pre.2

data/app/services/rails_pulse/config_recommendations.rb

@@ -0,0 +1,132 @@
+module RailsPulse
+  # Suggests retuning route_thresholds and query_thresholds when one summary
+  # period shows them to be out of step with the application: a slow
+  # threshold most of the slowest routes or queries exceed only adds noise,
+  # and a critical threshold nothing came within half of will never fire.
+  #
+  # Reads the period's ten slowest routes (by P95) and ten most expensive
+  # queries (by total time). The query critical check also reads the
+  # period's highest query P95, because a rarely run slow query is not among
+  # the most expensive yet is exactly what a critical threshold must catch.
+  # Each recommendation carries a config_snippet that keeps the threshold
+  # keys it does not change.
+  #
+  # A recommendation is only emitted when its suggestion actually moves the
+  # threshold the way the text says and keeps slow < very_slow < critical in
+  # order: a "lower your critical threshold" snippet that repeats or raises
+  # the current value, or merges the very_slow and critical bands, would be
+  # worse than silence.
+  class ConfigRecommendations
+    SAMPLE_SIZE = 10
+
+    def self.for_period(period_type:, period_start:)
+      period = RailsPulse::Summary.where(period_type: period_type, period_start: period_start)
+
+      route_rows = period.for_routes.order(p95_duration: :desc).limit(SAMPLE_SIZE).map do |summary|
+        { route_id: summary.summarizable_id, p95_duration: summary.p95_duration&.round(0) }
+      end
+      query_rows = period.for_queries.order(Arel.sql("rails_pulse_summaries.count * rails_pulse_summaries.avg_duration DESC")).limit(SAMPLE_SIZE).map do |summary|
+        { query_id: summary.summarizable_id, p95_duration: summary.p95_duration&.round(0) }
+      end
+
+      query_max_p95 = period.for_queries.maximum(:p95_duration)&.round(0)
+
+      new(route_rows: route_rows, query_rows: query_rows, query_max_p95: query_max_p95)
+    end
+
+    # query_max_p95 is the period's highest query P95; without it the
+    # highest among query_rows stands in.
+    def initialize(route_rows:, query_rows:, query_max_p95: nil)
+      @route_rows       = route_rows
+      @query_rows       = query_rows
+      @query_max_p95    = query_max_p95
+      @route_thresholds = RailsPulse.configuration.route_thresholds
+      @query_thresholds = RailsPulse.configuration.query_thresholds
+    end
+
+    def to_recommendations
+      route_recommendations + query_recommendations
+    end
+
+    private
+
+    def route_recommendations
+      return [] if @route_rows.size < 3
+
+      slow     = @route_thresholds[:slow].to_i
+      critical = @route_thresholds[:critical].to_i
+      p95s     = @route_rows.map { |r| r[:p95_duration].to_i }
+      above_slow = p95s.count { |p| p >= slow }
+      max_p95    = p95s.max.to_i
+      recs       = []
+
+      suggested = ceil_to(slow * 1.5, 50)
+      if above_slow >= 3 && above_slow.to_f / @route_rows.size >= 0.4 && suggested < @route_thresholds[:very_slow].to_i
+        recs << {
+          title:          "Route slow threshold may be too low",
+          detail:         "#{above_slow} of #{@route_rows.size} sampled routes exceeded the #{slow}ms slow " \
+                          "threshold this period, which may generate more noise than signal in " \
+                          "the Needs Attention section.",
+          config_snippet: snippet("route_thresholds", @route_thresholds, slow: suggested)
+        }
+      end
+
+      suggested = [ ceil_to(max_p95 * 2.0, 500), slow * 3, @route_thresholds[:very_slow].to_i + 500 ].max
+      if max_p95 > 0 && max_p95 < critical / 2 && suggested < critical
+        recs << {
+          title:          "Route critical threshold may be too permissive",
+          detail:         "No route came close to the #{critical}ms critical threshold this period " \
+                          "(highest P95: #{max_p95}ms). Lowering it helps surface real regressions " \
+                          "before they become user-visible.",
+          config_snippet: snippet("route_thresholds", @route_thresholds, critical: suggested)
+        }
+      end
+
+      recs
+    end
+
+    def query_recommendations
+      return [] if @query_rows.size < 3
+
+      slow     = @query_thresholds[:slow].to_i
+      critical = @query_thresholds[:critical].to_i
+      p95s     = @query_rows.map { |r| r[:p95_duration].to_i }
+      above_slow = p95s.count { |p| p >= slow }
+      max_p95    = (@query_max_p95 || p95s.max).to_i
+      recs       = []
+
+      suggested = ceil_to(slow * 1.5, 10)
+      if above_slow >= 3 && above_slow.to_f / @query_rows.size >= 0.4 && suggested < @query_thresholds[:very_slow].to_i
+        recs << {
+          title:          "Query slow threshold may be too low",
+          detail:         "#{above_slow} of #{@query_rows.size} sampled queries exceeded the #{slow}ms slow " \
+                          "threshold this period.",
+          config_snippet: snippet("query_thresholds", @query_thresholds, slow: suggested)
+        }
+      end
+
+      suggested = [ ceil_to(max_p95 * 2.0, 100), slow * 3, @query_thresholds[:very_slow].to_i + 100 ].max
+      if max_p95 > 0 && max_p95 < critical / 2 && suggested < critical
+        recs << {
+          title:          "Query critical threshold may be too permissive",
+          detail:         "No query came close to the #{critical}ms critical threshold this period " \
+                          "(highest P95: #{max_p95}ms).",
+          config_snippet: snippet("query_thresholds", @query_thresholds, critical: suggested)
+        }
+      end
+
+      recs
+    end
+
+    # The whole hash, so pasting the line does not drop very_slow.
+    def snippet(setting, current, **changes)
+      pairs = current.merge(changes).map { |key, value| "#{key}: #{value}" }
+      "config.#{setting} = { #{pairs.join(', ')} }"
+    end
+
+    # Round value up to the nearest multiple of step.
+    def ceil_to(value, step)
+      (value.to_f / step).ceil * step
+    end
+  end
+end

data/app/services/rails_pulse/deployment_comparison.rb

@@ -0,0 +1,177 @@
+module RailsPulse
+  # Whether a deployment made the application slower or more error-prone,
+  # answered from the hourly overall request summaries either side of it.
+  #
+  # Every hour the deploy ran in is skipped: during a rolling deploy those
+  # hours hold traffic from both versions. "Before" is the hour ending at
+  # the start of the hour the deploy started in, "after" the hour following
+  # the hour it finished in (the start hour when no finish was recorded), so
+  # a deploy running 14:28-15:40 compares 13:00-14:00 with 16:00-17:00, and
+  # its answer is available once SummaryJob has summarized 16:00.
+  #
+  # Computed on request and never stored. A metric degraded when it is more
+  # than its multiplier worse after the deploy and worse by at least the
+  # regression_thresholds absolute floor; either window holding fewer than
+  # MINIMUM_REQUESTS requests makes the comparison insufficient_data.
+  class DeploymentComparison
+    METRICS = %i[avg_response_time p95_response_time error_rate].freeze
+
+    MULTIPLIERS = {
+      avg_response_time: 1.5,
+      p95_response_time: 1.5,
+      error_rate:        1.25
+    }.freeze
+
+    UNITS = {
+      avg_response_time: "ms",
+      p95_response_time: "ms",
+      error_rate:        "%"
+    }.freeze
+
+    MINIMUM_REQUESTS = 10
+
+    # SummaryJob runs hourly, so the after-hour's row should exist within
+    # this long of that hour ending; a row still missing after that will not
+    # appear on its own, and the comparison is reported unavailable rather
+    # than leaving a polling agent waiting on a job that is not running.
+    SUMMARY_GRACE = 2.hours
+
+    # One comparison per deployment, reading every hourly row they need in
+    # a single query so a page of deployments costs one statement.
+    #
+    # @return [Hash{Integer => Hash}] keyed by deployment id
+    def self.for(deployments)
+      deployments = deployments.to_a
+      return {} if deployments.empty?
+
+      hours = deployments.flat_map { |deployment| windows(deployment).values }
+      rows = RailsPulse::Summary.overall_requests
+        .where(period_type: "hour", period_start: hours.uniq)
+        .index_by(&:period_start)
+
+      deployments.to_h do |deployment|
+        [ deployment.id, new(deployment, rows: rows).call ]
+      end
+    end
+
+    # The start of the hour before a deployment and the hour after it. The
+    # after window follows the hour the deploy finished in, so a rolling
+    # deploy that ran past the top of the hour does not leak mixed-version
+    # traffic into the measurement.
+    def self.windows(deployment)
+      start_hour  = RailsPulse::Summary.normalize_period_start("hour", deployment.started_at.in_time_zone)
+      finish_hour = if deployment.finished_at
+        RailsPulse::Summary.normalize_period_start("hour", deployment.finished_at.in_time_zone)
+      else
+        start_hour
+      end
+      { before: start_hour - 1.hour, after: finish_hour + 1.hour }
+    end
+
+    def initialize(deployment, rows: nil, now: Time.current)
+      @deployment = deployment
+      @now = now
+      @windows = self.class.windows(deployment)
+      @rows = rows || RailsPulse::Summary.overall_requests
+        .where(period_type: "hour", period_start: @windows.values)
+        .index_by(&:period_start)
+    end
+
+    def call
+      before = @rows[@windows[:before]]
+      after = @rows[@windows[:after]]
+      metrics = METRICS.map { |metric| compare(metric, before, after) }
+
+      {
+        outcome: outcome(metrics, after),
+        before:  window(@windows[:before], before),
+        after:   window(@windows[:after], after),
+        metrics: metrics,
+        note:    note(before, after)
+      }.compact
+    end
+
+    private
+
+    def compare(metric, before, after)
+      result = { metric: metric, unit: UNITS[metric], multiplier: MULTIPLIERS[metric] }
+
+      unless sufficient?(before) && sufficient?(after)
+        return result.merge(outcome: "insufficient_data", before: nil, after: nil, ratio: nil)
+      end
+
+      before_value = value(metric, before)
+      after_value = value(metric, after)
+
+      result.merge(
+        outcome: degraded?(metric, before_value, after_value) ? "degraded" : "clean",
+        before:  before_value.round(2),
+        after:   after_value.round(2),
+        ratio:   before_value.zero? ? nil : (after_value / before_value).round(3)
+      )
+    end
+
+    # Both gates matter, as in Operations::Comparison#regression?: the ratio
+    # alone flags trivial noise (8ms to 13ms is 1.6x), and the floor alone
+    # flags slow endpoints that barely moved. Errors where there were none is
+    # degraded once past the floor, though it has no ratio.
+    def degraded?(metric, before_value, after_value)
+      return false unless after_value - before_value >= min_delta(metric)
+      return true if before_value.zero?
+
+      after_value / before_value > MULTIPLIERS[metric]
+    end
+
+    def min_delta(metric)
+      thresholds = RailsPulse.configuration.regression_thresholds
+      metric == :error_rate ? thresholds[:min_delta_rate].to_f : thresholds[:min_delta_ms].to_f
+    end
+
+    def value(metric, row)
+      case metric
+      when :avg_response_time then row.avg_duration.to_f
+      when :p95_response_time then row.p95_duration.to_f
+      when :error_rate        then row.error_count.to_f / row.count * 100
+      end
+    end
+
+    def sufficient?(row)
+      row.present? && row.count.to_i >= MINIMUM_REQUESTS
+    end
+
+    # A missing after-hour row is pending only while SummaryJob could still
+    # write it; past SUMMARY_GRACE it is unavailable, a distinct value so an
+    # agent polling for the comparison is not left waiting forever when the
+    # job is not running (note says which).
+    def outcome(metrics, after)
+      if after.nil? && !pruned?(@windows[:after])
+        return @now < @windows[:after] + 1.hour + SUMMARY_GRACE ? "pending" : "unavailable"
+      end
+      return "degraded" if metrics.any? { |m| m[:outcome] == "degraded" }
+      return "insufficient_data" if metrics.any? { |m| m[:outcome] == "insufficient_data" }
+
+      "clean"
+    end
+
+    def window(start, row)
+      { from: start, to: start + 1.hour, requests: row&.count.to_i }
+    end
+
+    def note(before, after)
+      if (after.nil? && pruned?(@windows[:after])) || (before.nil? && pruned?(@windows[:before]))
+        "Hourly summaries this far back have been pruned (config.hourly_summary_retention keeps " \
+          "#{(RailsPulse.configuration.hourly_summary_retention / 1.day).round(1)} days), so this deployment can no longer be compared."
+      elsif after.nil? && @windows[:after] + 1.hour > @now
+        "The hour after the deploy ends at #{(@windows[:after] + 1.hour).iso8601}; the comparison is available once SummaryJob has summarized it."
+      elsif after.nil?
+        "The hour after the deploy has not been summarized. Check that RailsPulse::SummaryJob is scheduled hourly."
+      elsif !sufficient?(before) || !sufficient?(after)
+        "Fewer than #{MINIMUM_REQUESTS} requests in the hour before or after the deploy, too few to compare."
+      end
+    end
+
+    def pruned?(hour_start)
+      hour_start < RailsPulse.configuration.hourly_summary_retention.ago
+    end
+  end
+end

data/app/services/rails_pulse/exception_capture_service.rb

@@ -55,7 +55,7 @@ module RailsPulse
 
     def capture
       return unless RailsPulse.configuration.track_exceptions
-      return if RequestStore.store[:skip_recording_rails_pulse_activity]
+      return if RailsPulse::Current.skip_recording_rails_pulse_activity
 
       frames      = parse_backtrace(@exception.backtrace || [])
       location    = fingerprint_location(frames)

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

@@ -11,7 +11,7 @@ module RailsPulse
     # 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
+    # pruned at `hourly_summary_retention` (7 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.

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

@@ -3,7 +3,7 @@ module RailsPulse
     # 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
+    # namespace — dashboards today, findings and agent tooling later — are expected
     # to depend on, so it carries every number needed to explain the verdict
     # rather than just the verdict.
     class Comparison

data/app/services/rails_pulse/period_insights.rb

@@ -0,0 +1,131 @@
+module RailsPulse
+  # The routes, queries and jobs that need attention over one summary period
+  # (an hour, day, week or month), read from that period's own summary rows so
+  # every P95 is the period's real one rather than a blend of shorter periods.
+  # Classified by the same rules as the dashboard's Needs Attention panel and
+  # capped the same way: critical first, MAX_ITEMS in all.
+  #
+  # Served by GET api/v1/insights; items carry the record's id rather than a
+  # dashboard link.
+  class PeriodInsights
+    include RailsPulse::Dashboard::Concerns::AttentionClassification
+
+    MAX_ITEMS = 10
+
+    def initialize(period_type:, period_start:)
+      @period_type      = period_type
+      @period_start     = period_start
+      @route_thresholds = RailsPulse.configuration.route_thresholds
+      @query_thresholds = RailsPulse.configuration.query_thresholds
+      @job_thresholds   = RailsPulse.configuration.job_thresholds
+    end
+
+    def to_insights_data
+      items    = route_items + query_items + job_items
+      critical = items.select { |i| i[:severity] == :critical }.sort_by { |i| -i[:sort_score] }
+      warning  = items.select { |i| i[:severity] == :warning  }.sort_by { |i| -i[:sort_score] }
+      capped   = (critical + warning).first(MAX_ITEMS).map { |i| i.except(:sort_score) }
+
+      {
+        critical: capped.select { |i| i[:severity] == :critical },
+        warning:  capped.select { |i| i[:severity] == :warning },
+        total:    capped.size
+      }
+    end
+
+    private
+
+    # Classification can only keep a row past its slow threshold or carrying
+    # errors, so healthy rows are excluded in SQL rather than loading every
+    # summary row for the period just to drop almost all of them in Ruby.
+    def summaries(type, slow_threshold, with_errors: true)
+      scope = RailsPulse::Summary.where(summarizable_type: type, period_type: @period_type, period_start: @period_start)
+      return scope.where("rails_pulse_summaries.p95_duration >= ?", slow_threshold) unless with_errors
+
+      scope.where("rails_pulse_summaries.p95_duration >= ? OR rails_pulse_summaries.error_count > 0", slow_threshold)
+    end
+
+    def route_items
+      route_data = summaries("RailsPulse::Route", @route_thresholds[:slow])
+        .joins("INNER JOIN rails_pulse_routes ON rails_pulse_routes.id = rails_pulse_summaries.summarizable_id")
+        .select(
+          "rails_pulse_summaries.summarizable_id as route_id",
+          "rails_pulse_routes.path",
+          "rails_pulse_routes.http_methods as http_methods_raw",
+          "rails_pulse_summaries.p95_duration",
+          "rails_pulse_summaries.count",
+          "rails_pulse_summaries.error_count"
+        )
+
+      route_data.filter_map do |record|
+        p95        = record.p95_duration.to_f
+        total      = record.count.to_i
+        errors     = record.error_count.to_i
+        error_rate = total > 0 ? (errors * 100.0 / total).round(1) : 0.0
+
+        severity, reason, metric, metric_sub, sort_score = classify_route(p95, total, errors, error_rate, "this period")
+        next unless severity
+
+        item("route", record.route_id, "#{http_methods(record.http_methods_raw).join('|')} #{record.path}".strip,
+             severity, reason, metric, metric_sub, sort_score)
+      end
+    end
+
+    def query_items
+      query_data = summaries("RailsPulse::Query", @query_thresholds[:slow], with_errors: false)
+        .joins("INNER JOIN rails_pulse_queries ON rails_pulse_queries.id = rails_pulse_summaries.summarizable_id")
+        .select(
+          "rails_pulse_summaries.summarizable_id as query_id",
+          "rails_pulse_queries.normalized_sql",
+          "rails_pulse_summaries.p95_duration",
+          "rails_pulse_summaries.count"
+        )
+
+      query_data.filter_map do |record|
+        severity, reason, metric, metric_sub, sort_score = classify_query(record.p95_duration.to_f, record.count.to_i)
+        next unless severity
+
+        item("query", record.query_id, truncate_sql(record.normalized_sql), severity, reason, metric, metric_sub, sort_score)
+      end
+    end
+
+    def job_items
+      return [] unless RailsPulse.configuration.track_jobs
+
+      job_data = summaries("RailsPulse::Job", @job_thresholds[:slow])
+        .joins("INNER JOIN rails_pulse_jobs ON rails_pulse_jobs.id = rails_pulse_summaries.summarizable_id")
+        .select(
+          "rails_pulse_summaries.summarizable_id as job_id",
+          "rails_pulse_jobs.name as job_name",
+          "rails_pulse_jobs.queue_name",
+          "rails_pulse_summaries.p95_duration",
+          "rails_pulse_summaries.count",
+          "rails_pulse_summaries.error_count"
+        )
+
+      job_data.filter_map do |record|
+        runs         = record.count.to_i
+        failures     = record.error_count.to_i
+        failure_rate = runs > 0 ? (failures * 100.0 / runs).round(1) : 0.0
+
+        severity, reason, metric, metric_sub, sort_score = classify_job(
+          failure_rate, record.p95_duration.to_f, runs, failures, record.queue_name.presence || "default"
+        )
+        next unless severity
+
+        item("job", record.job_id, record.job_name, severity, reason, metric, metric_sub, sort_score)
+      end
+    end
+
+    def item(type, id, name, severity, reason, metric, metric_sub, sort_score)
+      { type: type, id: id, name: name, severity: severity, reason: reason,
+        metric: metric, metric_sub: metric_sub, sort_score: sort_score }
+    end
+
+    def http_methods(raw)
+      Array(JSON.parse(raw.to_s))
+    rescue JSON::ParserError
+      []
+    end
+  end
+end