rails-profiler 0.42.0 → 0.43.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56b64fc5b7eafdb748a1dc236605573317b7eb018192f3f784473dee1452954d
-  data.tar.gz: a347f0f26ca063176c85d7ce3671c30a85bfc9fc642f2f95d46332dd8dafcf4c
+  metadata.gz: f56117e3f0074f2373965bdcd9424ba51d53ccb58fc150826ef4e76c8f387b69
+  data.tar.gz: 4003700e30187467f5642d7731f75253655b53eee39d4435a617b41f3b7b0bfa
 SHA512:
-  metadata.gz: da5993a01741578d15b8f6d71c46a2e093991ede0526cb622950ca01d905224971a9241c39eb50d5f1adf904ff39217f1d68c81fd9982405167912f75a5f20b2
-  data.tar.gz: 57f912fefa7c794641f42362384bb207acfd06e617ae031c3fcea27f8e9e6b632f0f10f7a97310a4c57e9a5648c382e2a47aac750850e279eb3c8c2897ff65b4
+  metadata.gz: a8bdb227c96e7ccf65bf6415965dee2b10348dfc8a056d7ddc1b77bbe1e0aa81d56b84fbb10e8656991cee6a6de07d27dac20b63d2b2797abc432a0de276fb8c
+  data.tar.gz: 4f372a6f1ce65c7735233f0c629dfbbce3fea31023dfb3ca7f4d9172d75c912fe597b8d3c3390acbe5b28c911107c3400397c5a1507b9ab2d17c1ae52f3d653c

data/CHANGELOG.md

@@ -19,6 +19,24 @@ every commit of every tag interval is accounted for one way or the other.
 
 ## [Unreleased]
 
+## [0.43.0] - 2026-10-20
+
+<!-- stamped -->
+
+### Added
+
+- **Alerts:** The new `config.alerts_enabled` (default `false`) turns on threshold alerts. Each profile
+  saved that crosses `slow_query_threshold`, `max_queries_warning` or
+  `allocated_objects_warning_threshold`, or that repeats a normalized SQL statement (an N+1), is handed to
+  the `config.on_detection` block and, when `config.alert_webhook_url` is set, POSTed there as generic JSON
+  (see `docs/configuration.md` for the payload). The checks run on one worker thread with a bounded queue (a full queue drops and logs the check), never delay the
+  request, and their failures are logged. A profile saved again is not alerted again for a type already delivered,
+  and the `path` of a console profile is `null` in the payload. `config.alert_webhook_url=` raises `ArgumentError`
+  for a URL that is not http(s) with a host, or that carries credentials. An alert carries the normalized SQL and a fingerprint, never a body
+  or a parameter; SQL literals (quoted strings with a backslash or a doubled quote, double quoted text,
+  comments, dollar-quoted bodies) are removed from the statement, and a statement whose literals cannot be
+  read with certainty is cut before the first one.
+
 ## [0.42.0] - 2026-10-20
 
 <!-- stamped -->

data/lib/profiler/alerts/sql_redaction.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Profiler
+  module Alerts
+    # Removes from a SQL statement what the shared N1Patterns.normalize_sql lets through: strings
+    # with a backslash escape or a doubled quote, double quoted text, comments and dollar-quoted
+    # bodies. Used for alerts only; the shared normalization is left as it is.
+    #
+    # The statement is read twice, with backslash escapes (MySQL) and without (standard SQL). When
+    # the two readings disagree, or a quote or a comment opener is left, the statement is cut at
+    # the first one: a value is dropped rather than guessed. A literal in a vendor syntax not
+    # listed here can still remain, hence also the cut at SQL_LIMIT in Alerts.
+    module SqlRedaction
+      STRINGS_WITH_BACKSLASH = /'(?:[^'\\]|\\.|'')*'|"(?:[^"\\]|\\.|"")*"/m
+      STRINGS_STANDARD = /'(?:[^']|'')*'|"(?:[^"]|"")*"/m
+      DOLLAR_QUOTED = /\$(?<tag>[A-Za-z_]\w*|)\$.*?\$\k<tag>\$/m
+      COMMENTS = %r{/\*.*?\*/|--[^\n]*|(?<=\s|\A)\#[^\n]*}m
+      # Tried left to right, so a quote in a comment, or a comment in a quote, is not read as the other.
+      READINGS = [STRINGS_WITH_BACKSLASH, STRINGS_STANDARD].map do |strings|
+        Regexp.union(strings, DOLLAR_QUOTED, COMMENTS)
+      end.freeze
+      # What is left of a literal or a comment when a form was not read to its end.
+      OPENER = %r{['"]|/\*|--|\$(?:[A-Za-z_]\w*)?\$|(?<=\s|\A)#}
+
+      # The statement is cut here before it is read. The dollar-quote pattern scans to the end for
+      # each opener, which is quadratic on a long statement full of $ with no closing tag; this
+      # bounds it. Alerts only send SQL_LIMIT characters of the normalized statement anyway.
+      MAX_LENGTH = 5_000
+
+      module_function
+
+      def redact(sql)
+        sql = sql[0, MAX_LENGTH] if sql.length > MAX_LENGTH
+        readings = READINGS.map { |pattern| sql.gsub(pattern) { |m| m.start_with?("'", '"') ? "?" : " " } }
+        return sql[0, sql.index(OPENER) || sql.length] if readings.uniq.size > 1 || readings.first.match?(OPENER)
+
+        readings.first
+      end
+    end
+  end
+end

data/lib/profiler/alerts/webhook.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Profiler
+  module Alerts
+    # POSTs an alert as JSON. Called from the detached thread of Alerts.check, which holds nothing
+    # of the request, so its own HTTP call is not recorded into a profile and it never delays the
+    # request. Errors are logged, never raised.
+    module Webhook
+      module_function
+
+      # The URL as a String, nil when none is given. Raises ArgumentError for a URL that cannot be
+      # called: not http(s), no host, or credentials in it (never sent, so refused).
+      def validate!(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        uri = URI.parse(value.to_s.strip)
+        unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+          raise ArgumentError, "config.alert_webhook_url: #{value.to_s.inspect} must be an http(s) URL with a host"
+        end
+        if uri.userinfo
+          raise ArgumentError, "config.alert_webhook_url: credentials in the URL are not sent; " \
+                               "put the secret in the path or a query parameter of the receiver"
+        end
+        uri.to_s
+      rescue URI::InvalidURIError
+        raise ArgumentError, "config.alert_webhook_url: #{value.to_s.inspect} is not a valid URL"
+      end
+
+      def post(alert, url, timeout)
+        return if url.nil? || url.to_s.empty?
+
+        send_request(url, alert, timeout)
+      end
+
+      def send_request(url, alert, timeout)
+        response = http_for(URI.parse(url.to_s), timeout).request(request_for(url, alert))
+        return if response.is_a?(Net::HTTPSuccess)
+
+        Profiler.log_error("Alerts: webhook answered #{response.code} for #{alert[:type]}")
+      rescue StandardError => e
+        Profiler.log_error("Alerts: webhook failed for #{alert[:type]}", e)
+      end
+
+      def http_for(uri, timeout)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = http.read_timeout = http.write_timeout = timeout
+        http
+      end
+
+      def request_for(url, alert)
+        request = Net::HTTP::Post.new(URI.parse(url.to_s).request_uri, "Content-Type" => "application/json")
+        request.body = JSON.generate(alert)
+        request
+      end
+    end
+  end
+end

data/lib/profiler/alerts/worker.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Profiler
+  module Alerts
+    # One thread, one bounded queue. Every check (the detections, the hook, the webhook) runs here,
+    # one after the other, so a slow or unreachable webhook never piles up threads: when the queue
+    # is full the job is dropped and logged. The thread is started on first use, with
+    # RequestContext.detached so it holds nothing of the request that started it, and started
+    # again when it is gone (a fork does not carry threads over).
+    class Worker
+      CAPACITY = 100
+
+      def initialize(capacity: CAPACITY)
+        @queue = SizedQueue.new(capacity)
+        @lock = Mutex.new
+        @idle = ConditionVariable.new
+        @pending = 0
+        @thread = nil
+        @pid = Process.pid
+      end
+
+      # True when queued, false when the queue is full.
+      def push(&job)
+        ensure_thread
+        @lock.synchronize { @pending += 1 }
+        @queue.push(job, true)
+        true
+      rescue ThreadError
+        @lock.synchronize { @pending -= 1 }
+        false
+      end
+
+      # Waits until every job queued so far is done. For tests and for shutdown.
+      def drain(timeout = 10)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        @lock.synchronize do
+          while @pending.positive?
+            left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            return false unless left.positive?
+
+            @idle.wait(@lock, left)
+          end
+        end
+        true
+      end
+
+      private
+
+      def ensure_thread
+        @lock.synchronize do
+          reset_after_fork
+          return if @thread&.alive?
+
+          @thread = Instrumentation::RequestContext.detached { Thread.new { work } }
+        end
+      end
+
+      def reset_after_fork
+        return if @pid == Process.pid
+
+        @pid = Process.pid
+        @queue = SizedQueue.new(@queue.max)
+        @pending = 0
+        @thread = nil
+      end
+
+      def work
+        loop do
+          job = @queue.pop
+          begin
+            job.call
+          rescue StandardError => e
+            Profiler.log_error("Alerts: a check failed", e)
+          ensure
+            @lock.synchronize do
+              @pending -= 1
+              @idle.broadcast if @pending <= 0
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/profiler/alerts.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "net/http"
+require "uri"
+require "digest"
+require_relative "alerts/webhook"
+require_relative "alerts/sql_redaction"
+require_relative "alerts/worker"
+# Alerts.normalize_sql wraps N1Patterns.normalize_sql. That file is otherwise only loaded by the MCP
+# server, which an application without MCP never starts, so it is required here, not on first use.
+require_relative "mcp/resources/n1_patterns"
+require_relative "instrumentation/request_context"
+require_relative "collectors/scoped_notifications"
+
+module Profiler
+  # Threshold alerts. When config.alerts_enabled is true, every profile saved is compared with the
+  # thresholds the profiler already has (slow_query_threshold, max_queries_warning,
+  # allocated_objects_warning_threshold) and checked for an N+1. Each detection is handed to
+  # config.on_detection and, when config.alert_webhook_url is set, POSTed there as JSON.
+  #
+  # An alert carries no raw data: no body, no parameters, no header, only the SQL statement with
+  # its literals replaced with ? (see SqlRedaction) and a fingerprint of it.
+  #
+  # Nothing here may slow or break the request: the whole check (the detections, which walk the
+  # queries of the profile, then the hook and the webhook) runs on the one worker thread of
+  # Alerts::Worker, fed through a bounded queue (a full queue drops the check and logs it), so
+  # `check` returns at once and a slow webhook never piles up threads.
+  # Each family of alert is detected in its own rescue, so an error on one never hides the others.
+  #
+  # One alert per type and per profile: a profile saved again (a late outbound HTTP call) is not
+  # alerted again for a type already delivered. The path of a console profile is the expression
+  # typed, which may hold a secret passed as a literal, so it is left out of the payload.
+  module Alerts
+    TYPES = %w[slow_query too_many_queries excessive_allocations n_plus_one].freeze
+    SQL_LIMIT = 200
+    N_PLUS_ONE_LIMIT = 10
+    DELIVERED_LIMIT = 2000
+    DELIVERED_LOCK = Mutex.new
+    DELIVERED = {}
+    WORKER = Worker.new
+
+    module_function
+
+    # Queues the check for the worker thread. True when queued, nil when alerts are off or the
+    # queue is full. The profile is saved and no longer written to by then.
+    def check(profile)
+      config = Profiler.configuration
+      return unless config.alerts_enabled
+      return true if WORKER.push { run(profile, config) }
+
+      Profiler.log_error("Alerts: queue full, check of profile #{profile&.token} dropped")
+      nil
+    rescue StandardError => e
+      Profiler.log_error("Alerts: could not start the check of profile #{profile&.token}", e)
+      nil
+    end
+
+    def run(profile, config)
+      Collectors::ScopedNotifications.forget_inherited_scope
+      detections(profile, config).each { |alert| deliver(alert, config) if first_delivery?(alert) }
+    rescue StandardError => e
+      Profiler.log_error("Alerts: could not check profile #{profile&.token}", e)
+    end
+
+    # True once per profile token and alert type. The store is bounded, oldest token out first.
+    def first_delivery?(alert)
+      DELIVERED_LOCK.synchronize do
+        types = (DELIVERED[alert[:profile_token]] ||= [])
+        next false if types.include?(alert[:type])
+
+        types << alert[:type]
+        DELIVERED.shift while DELIVERED.size > DELIVERED_LIMIT
+        true
+      end
+    end
+
+    # Waits for the queued checks to finish (tests, shutdown).
+    def drain(timeout = 10)
+      WORKER.drain(timeout)
+    end
+
+    # Every family in its own rescue: an error on one is logged and the others still go out.
+    def detections(profile, config)
+      base = base_payload(profile)
+      queries = queries_of(profile)
+      { slow_query: -> { slow_query_alerts(base, queries, config) },
+        too_many_queries: -> { too_many_queries_alerts(base, queries, config) },
+        excessive_allocations: -> { allocation_alerts(base, profile, config) },
+        n_plus_one: -> { n_plus_one_alerts(base, queries) } }
+        .flat_map { |family, detect| safely(family, profile, &detect) }
+    rescue StandardError => e
+      Profiler.log_error("Alerts: could not read profile #{profile&.token}", e)
+      []
+    end
+
+    def safely(family, profile)
+      yield
+    rescue StandardError => e
+      Profiler.log_error("Alerts: could not detect #{family} for profile #{profile&.token}", e)
+      []
+    end
+
+    def base_payload(profile)
+      request = profile.collector_data("request")
+      {
+        profile_token: profile.token,
+        method: profile.method,
+        path: profile.profile_type == "console" ? nil : profile.path,
+        controller_action: request.is_a?(Hash) ? read(request, :controller_action) : nil,
+        status: profile.status,
+        detected_at: Time.now.utc.iso8601
+      }
+    end
+
+    # A collector's value whatever the keys' type: symbols as the collector built it (the profile
+    # Alerts.check receives), strings once the profile is stored and read back. Same principle as
+    # Otel::TraceExporter.list.
+    def read(hash, key)
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+
+    def queries_of(profile)
+      data = profile.collector_data("database")
+      list = data.is_a?(Hash) ? read(data, :queries) : nil
+      return [] unless list.is_a?(Array)
+
+      list.filter_map do |q|
+        next unless q.is_a?(Hash) && read(q, :sql).is_a?(String)
+
+        { sql: read(q, :sql), duration: read(q, :duration) }
+      end
+    end
+
+    def slow_query_alerts(base, queries, config)
+      threshold = config.slow_query_threshold
+      return [] unless threshold
+
+      slow = queries.select { |q| q[:duration].to_f > threshold }
+      return [] if slow.empty?
+
+      slowest = slow.max_by { |q| q[:duration].to_f }
+      [base.merge(type: "slow_query", threshold: threshold, unit: "ms", value: slowest[:duration].to_f,
+                  count: slow.size, query: describe_normalized(normalize_sql(slowest[:sql])))]
+    end
+
+    def too_many_queries_alerts(base, queries, config)
+      threshold = config.max_queries_warning
+      return [] unless threshold && queries.size > threshold
+
+      [base.merge(type: "too_many_queries", threshold: threshold, unit: "queries", value: queries.size)]
+    end
+
+    def allocation_alerts(base, profile, config)
+      threshold = config.allocated_objects_warning_threshold
+      value = profile.allocated_objects
+      return [] unless threshold && value && value > threshold
+
+      [base.merge(type: "excessive_allocations", threshold: threshold, unit: "objects", value: value)]
+    end
+
+    def n_plus_one_alerts(base, queries)
+      groups = queries.group_by { |q| normalize_sql(q[:sql]) }
+      repeated = groups.select { |_, list| list.size > 1 }
+      return [] if repeated.empty?
+
+      [base.merge(type: "n_plus_one", threshold: 1, unit: "repeats", value: repeated.values.map(&:size).max,
+                  patterns: patterns_of(repeated))]
+    end
+
+    def patterns_of(repeated)
+      repeated.sort_by { |_, list| -list.size }.first(N_PLUS_ONE_LIMIT).map do |normalized, list|
+        describe_normalized(normalized).merge(count: list.size)
+      end
+    end
+
+    # The shared normalization (numbers, $1 and simple quoted strings) after SqlRedaction.redact.
+    def normalize_sql(sql)
+      MCP::Resources::N1Patterns.normalize_sql(SqlRedaction.redact(sql))
+    end
+
+    def describe_normalized(normalized)
+      { sql: normalized[0, SQL_LIMIT], fingerprint: Digest::SHA256.hexdigest(normalized)[0, 12] }
+    end
+
+    def deliver(alert, config)
+      call_hook(alert, config)
+      Webhook.post(alert, config.alert_webhook_url, config.alert_webhook_timeout)
+    end
+
+    def call_hook(alert, config)
+      hook = config.on_detection
+      hook&.call(alert)
+    rescue StandardError => e
+      Profiler.log_error("Alerts: config.on_detection raised for #{alert[:type]}", e)
+    end
+  end
+end

data/lib/profiler/configuration.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require_relative "local_request"
 require_relative "allocation_counter"
+require_relative "alerts/webhook"
 
 module Profiler
   # Header the profiler's own clients send on every request. A page on another origin cannot
@@ -40,9 +41,12 @@ module Profiler
     # URL schemes the source links can use. Anything else is never turned into a link.
     EDITOR_URL_SCHEMES = %w[vscode idea cursor].freeze
 
+    attr_reader :alert_webhook_url
+
     attr_accessor :storage_options, :collectors,
                   :slow_query_threshold, :max_queries_warning, :sql_backtrace,
                   :track_memory, :allocated_objects_warning_threshold,
+                  :alerts_enabled, :alert_webhook_timeout,
                   :mcp_enabled, :mcp_transport, :mcp_port, :mcp_read_only,
                   :authorization_mode, :extension_cors_enabled,
                   :cors_allowed_origins, :api_forgery_protection, :frame_ancestors,
@@ -84,6 +88,11 @@ module Profiler
       # versions did, about 0.1 ms each), :none never.
       @sql_backtrace = :first_and_slow
       @track_memory = true
+      # Threshold alerts (Profiler::Alerts): off until enabled; the webhook stays off until a URL is set.
+      @alerts_enabled = false
+      @alert_webhook_url = nil
+      @alert_webhook_timeout = 3 # seconds, for the connection and for the answer
+      @on_detection = nil
       # Not compared with anything yet. The default is the former 100 MB memory threshold read
       # as the objects it stood for.
       @allocated_objects_warning_threshold = 100 * 1024 * 1024 / AllocationCounter::LEGACY_BYTES_PER_OBJECT
@@ -202,6 +211,13 @@ module Profiler
     # The editor the file:line links open: "vscode", "idea" or "cursor" (String or Symbol). A
     # value outside that list is kept as given, but #editor_link_scheme answers nil for it, so
     # that no link is built.
+    # Nil or empty turns the webhook off. Otherwise an absolute http(s) URL with a host, and no
+    # user or password in it: the webhook sends none, so a URL carrying them is refused rather than
+    # silently called without them.
+    def alert_webhook_url=(value)
+      @alert_webhook_url = Alerts::Webhook.validate!(value)
+    end
+
     def editor_url_scheme=(value)
       @editor_url_scheme = value.nil? ? nil : value.to_s
     end
@@ -348,6 +364,13 @@ module Profiler
       @name || (defined?(Rails) ? Rails.application.class.module_parent_name.underscore : "profiler")
     end
 
+    # Block called with the alert (a Hash, see Profiler::Alerts) each time a profile crosses a
+    # threshold or shows an N+1. Only runs when config.alerts_enabled is true.
+    def on_detection(&block)
+      @on_detection = block if block
+      @on_detection
+    end
+
     def authorize_with(&block)
       @authorize_block = block
     end

data/lib/profiler/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Profiler
-  VERSION = "0.42.0"
+  VERSION = "0.43.0"
 
   GEM_ROOT = File.expand_path("../..", __dir__)
 

data/lib/profiler.rb

@@ -54,6 +54,7 @@ module Profiler
       return false if target.is_a?(Storage::Unavailable)
 
       target.save(profile.token, profile)
+      Alerts.check(profile)
       true
     rescue StandardError => e
       log_error("#{from}: could not save profile #{profile.token}", e)
@@ -274,6 +275,7 @@ require_relative "profiler/storage/token"
 require_relative "profiler/storage/private_files"
 require_relative "profiler/storage/unavailable"
 require_relative "profiler/assets"
+require_relative "profiler/alerts"
 require_relative "profiler/ajax_data"
 require_relative "profiler/peers"
 require_relative "profiler/peers/peer_proxy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-profiler
 version: !ruby/object:Gem::Version
-  version: 0.42.0
+  version: 0.43.0
 platform: ruby
 authors:
 - Sébastien Duplessy
@@ -150,6 +150,10 @@ files:
 - exe/profiler-mcp
 - lib/profiler.rb
 - lib/profiler/ajax_data.rb
+- lib/profiler/alerts.rb
+- lib/profiler/alerts/sql_redaction.rb
+- lib/profiler/alerts/webhook.rb
+- lib/profiler/alerts/worker.rb
 - lib/profiler/allocation_counter.rb
 - lib/profiler/assets.rb
 - lib/profiler/body_content.rb