brainzlab 0.1.33 → 0.1.34

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9a9a15a426d4a6853086c9a36851e57bd14736c5d11dbeb70fb510fe5fc1c10
-  data.tar.gz: 19f26af342b3d9150eacb2615da08fa063cc671388f7b97a87b207cd210cf6fc
+  metadata.gz: c67c9e29d88bcc008c8ba0464b933b61f3a9bd255868f59af8b7e0daf31665dc
+  data.tar.gz: bbfe09e8406b488f995cf312b1b1838cd4f614dc1708316eda3c3b5cd1dcab08
 SHA512:
-  metadata.gz: b149c1fbf2c0f13fa34d0b2d2e6df634a1dc01f087f8174ba58fcc0bf05ea0301365721131e03441bf0af7e3b443d5a86acc5dfa141ba4fa9af2c24c610782a9
-  data.tar.gz: 737cd856a43c4c3555a566653692fd32d04798e464e24bad80d189610b82e81c0d0b2860cda232fae66063477b21687858c14e5178050a771af6745b9741d46f
+  metadata.gz: d83a33af5f933e84f1bec1327f564b79d2fe2dc8c94035beebbc1985d5e44130d88a442ca95bb2654f9a4bb3aed207e3514d083c2fb69d92a2faf0df38becc62
+  data.tar.gz: 93a945a9c8d6f3d91ef144fd005b2b0f1bcdad9a90c8f7cabdca7f2a4602b6678409cc2e17d2e06baf8e560301c0b9dafbb2339f6e56e353022098ed145e732a

data/README.md

@@ -198,6 +198,44 @@ config.pulse_excluded_paths = ['/health', '/ping', '/up', '/assets']
 config.pulse_sample_rate = 1.0          # 1.0 = 100%
 ```
 
+### Query plans (EXPLAIN)
+
+Off by default. When enabled, a query slower than the threshold gets an
+`EXPLAIN` run against your own database and the plan travels with the span, so
+Pulse can tell you *why* a query is slow instead of only that it is.
+
+```ruby
+config.pulse_explain_enabled = true   # default: false
+config.pulse_explain_threshold = 500  # ms; defaults to slow_query_threshold
+config.pulse_explain_timeout = 2      # seconds to wait for a plan
+```
+
+Or via environment: `BRAINZLAB_PULSE_EXPLAIN_ENABLED`,
+`BRAINZLAB_PULSE_EXPLAIN_THRESHOLD`, `BRAINZLAB_PULSE_EXPLAIN_TIMEOUT`.
+
+What it will and will not do:
+
+- **Read-only statements only.** A write is never explained.
+- **Plain `EXPLAIN`, never `EXPLAIN ANALYZE`** — the statement is planned, not run.
+- **One plan per distinct statement**, not one per occurrence.
+- **A timeout**, so a slow planner cannot stall a request.
+- **Failures are swallowed.** If the database refuses the `EXPLAIN`, the span is
+  recorded without a plan; instrumentation never breaks the app.
+
+It does issue one extra query per newly-seen slow statement, which is why you opt
+in rather than opt out.
+
+### Configuration validation
+
+`BrainzLab.configure` validates the configuration when your block finishes and
+raises `BrainzLab::ConfigurationError` listing everything that is wrong, rather
+than letting a typo turn into missing telemetry. The common one:
+
+```ruby
+config.pulse_sample_rate = 50   # raises — sample rates are fractions
+config.pulse_sample_rate = 0.5  # 50%
+```
+
 ### Distributed Tracing
 
 Pulse supports distributed tracing across services using W3C Trace Context and B3 propagation.

data/lib/brainzlab/configuration.rb

@@ -45,6 +45,9 @@ module BrainzLab
                   :pulse_sample_tier,
                   :pulse_always_keep_slow_ms,
                   :pulse_excluded_paths,
+                  :pulse_explain_enabled,
+                  :pulse_explain_threshold,
+                  :pulse_explain_timeout,
                   :flux_enabled,
                   :flux_url,
                   :flux_api_key,
@@ -401,6 +404,14 @@ module BrainzLab
       # default can't flood Recall. Slow-query duration is APM data (Pulse already
       # records it), so it defaults to a quiet level (:debug) and a higher threshold.
       @slow_query_threshold       = (ENV['BRAINZLAB_SLOW_QUERY_THRESHOLD'] || 500).to_i      # ms (was hardcoded 100)
+
+      # Query plan capture. Off by default: it issues an extra (read-only)
+      # EXPLAIN against the app's own database, so an app opts in deliberately.
+      # Threshold defaults to the slow query threshold — a fast query has no
+      # plan worth looking at.
+      @pulse_explain_enabled = ENV['BRAINZLAB_PULSE_EXPLAIN_ENABLED'] == 'true'
+      @pulse_explain_threshold = (ENV['BRAINZLAB_PULSE_EXPLAIN_THRESHOLD'] || @slow_query_threshold).to_i
+      @pulse_explain_timeout = (ENV['BRAINZLAB_PULSE_EXPLAIN_TIMEOUT'] || 2).to_i
       @very_slow_query_threshold  = (ENV['BRAINZLAB_VERY_SLOW_QUERY_THRESHOLD'] || 2000).to_i # ms (was hardcoded 1000)
       @slow_query_log_level       = (ENV['BRAINZLAB_SLOW_QUERY_LOG_LEVEL'] || 'debug').to_sym  # was :warn → floods
       @very_slow_query_log_level  = (ENV['BRAINZLAB_VERY_SLOW_QUERY_LOG_LEVEL'] || 'warn').to_sym
@@ -498,6 +509,67 @@ module BrainzLab
       @enabled && !@secret_key.nil? && !@secret_key.empty?
     end
 
+    # Settings validated eagerly by #validate!, grouped by the shape they must
+    # have. Kept as data so adding a setting is a one-line change here rather
+    # than another branch in the validation logic.
+    SAMPLE_RATE_SETTINGS = %i[pulse_sample_rate reflex_sample_rate].freeze
+
+    POSITIVE_INTEGER_SETTINGS = %i[
+      recall_buffer_size recall_flush_interval
+      pulse_buffer_size pulse_flush_interval
+      flux_buffer_size flux_flush_interval
+      pulse_explain_timeout
+    ].freeze
+
+    NON_NEGATIVE_NUMBER_SETTINGS = %i[
+      pulse_always_keep_slow_ms
+      slow_query_threshold very_slow_query_threshold
+      slow_request_threshold very_slow_request_threshold
+      n_plus_one_threshold pulse_explain_threshold
+    ].freeze
+
+    # Validate the configuration and raise on anything that would misbehave
+    # silently at runtime. Called by BrainzLab.configure once the user's block
+    # has been applied, so a typo surfaces at boot rather than as missing
+    # telemetry days later.
+    #
+    # @return [Configuration] self, when every setting is valid
+    # @raise [ConfigurationError] listing every invalid setting at once
+    def validate!
+      problems = []
+
+      SAMPLE_RATE_SETTINGS.each do |setting|
+        value = public_send(setting)
+        next if value.nil? # nil means "fall back to the tier default"
+
+        unless value.is_a?(Numeric) && value.between?(0, 1)
+          problems << "#{setting} must be a number between 0 and 1 (got #{value.inspect})"
+        end
+      end
+
+      POSITIVE_INTEGER_SETTINGS.each do |setting|
+        value = public_send(setting)
+        problems << "#{setting} must be a positive number (got #{value.inspect})" unless positive_number?(value)
+      end
+
+      NON_NEGATIVE_NUMBER_SETTINGS.each do |setting|
+        value = public_send(setting)
+        unless value.is_a?(Numeric) && !value.negative?
+          problems << "#{setting} must be a non-negative number (got #{value.inspect})"
+        end
+      end
+
+      return self if problems.empty?
+
+      raise ConfigurationError.new(
+        "Invalid BrainzLab configuration: #{problems.join('; ')}",
+        hint: 'Fix these values in your BrainzLab.configure block or the matching environment variables. ' \
+              'Sample rates are fractions (0.5 = 50%), not percentages.',
+        code: 'invalid_configuration',
+        context: { problems: problems }
+      )
+    end
+
     def enabled?
       @enabled == true
     end
@@ -714,6 +786,10 @@ module BrainzLab
 
     private
 
+    def positive_number?(value)
+      value.is_a?(Numeric) && value.positive?
+    end
+
     def detect_environment
       return ::Rails.env.to_s if defined?(::Rails) && ::Rails.respond_to?(:env)
       return ENV['RACK_ENV'] if ENV['RACK_ENV']

data/lib/brainzlab/instrumentation/active_record.rb

@@ -31,6 +31,36 @@ module BrainzLab
           BrainzLab.debug_log('ActiveRecord instrumentation installed (sql, instantiation, transactions, strict_loading)')
         end
 
+        # Capture the execution plan for a query slow enough to be worth one.
+        #
+        # Runs here, in the app, because Pulse never has access to the app's
+        # database — a plan can only be produced on this side of the wire. The
+        # plan travels with the span so the backend can point at a sequential
+        # scan instead of guessing from normalized SQL.
+        #
+        # @param payload [Hash] the sql.active_record payload
+        # @param duration [Numeric] query duration in ms
+        # @return [String, nil] the plan, or nil when not captured
+        def explain_plan_for(payload, duration)
+          config = BrainzLab.configuration
+          return nil unless config.pulse_explain_enabled
+          return nil if duration < config.pulse_explain_threshold
+          return nil if payload[:cached] # never reached the database
+
+          connection = payload[:connection]
+          return nil if connection.nil?
+
+          result = BrainzLab::Pulse::ExplainCapture.capture(
+            sql: payload[:sql],
+            connection: connection,
+            timeout: config.pulse_explain_timeout
+          )
+          result && result[:plan]
+        rescue StandardError => e
+          BrainzLab.debug_log("Explain plan capture failed: #{e.message}")
+          nil
+        end
+
         def installed?
           @installed == true
         end
@@ -134,7 +164,8 @@ module BrainzLab
               'db.cached' => payload[:cached] || false,
               'db.async' => payload[:async] || false,
               'db.row_count' => payload[:row_count],
-              'db.affected_rows' => payload[:affected_rows]
+              'db.affected_rows' => payload[:affected_rows],
+              'db.explain_plan' => explain_plan_for(payload, duration)
             }.compact
           }
 

data/lib/brainzlab/instrumentation/grape.rb

@@ -25,6 +25,26 @@ module BrainzLab
           @installed = false
         end
 
+        # Resolve the route pattern to name a trace by.
+        #
+        # Grape exposes the matched pattern (/users/:id) via routing_args, and
+        # that is always preferred. When it does not, naming the trace after the
+        # raw path turns every record into its own endpoint — /users/1,
+        # /users/2, ... — so the path is normalized first, using the routing
+        # args as param hints when they are present.
+        #
+        # @param env [Hash] the Rack env
+        # @param path [String, nil] the concrete request path
+        # @return [String, nil] a pattern safe to aggregate on
+        def route_pattern_for(env, path)
+          routing_args = safe_routing_args(env)
+          pattern = routing_args && safe_dig(routing_args, :route_info)&.pattern&.path
+          return pattern if pattern
+
+          params = routing_args.is_a?(Hash) ? routing_args.reject { |k, _| k.to_sym == :route_info } : nil
+          BrainzLab::Utilities::RoutePathNormalizer.normalize(path, params)
+        end
+
         private
 
         def install_notifications!
@@ -176,6 +196,18 @@ module BrainzLab
           }
         end
 
+        def safe_routing_args(env)
+          env.is_a?(Hash) ? env['grape.routing_args'] : nil
+        rescue StandardError
+          nil
+        end
+
+        def safe_dig(routing_args, key)
+          routing_args.respond_to?(:dig) ? routing_args.dig(key) : nil
+        rescue StandardError
+          nil
+        end
+
         def extract_route_pattern(endpoint)
           return '/' unless endpoint
 
@@ -242,8 +274,9 @@ module BrainzLab
           method = request.request_method
           path = request.path
 
-          # Get route pattern from Grape if available
-          route_pattern = env['grape.routing_args']&.dig(:route_info)&.pattern&.path || path
+          # Get route pattern from Grape if available, else normalize the raw
+          # path so /users/1 and /users/2 aggregate as one endpoint.
+          route_pattern = route_pattern_for(env, path)
 
           spans = Thread.current[:brainzlab_pulse_spans] || []
 

data/lib/brainzlab/pulse/explain_capture.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module BrainzLab
+  module Pulse
+    # Captures a query execution plan from the application's own database
+    # connection and attaches it to the span.
+    #
+    # This runs client-side on purpose: Pulse is an external service and never
+    # has access to a customer's database, so an EXPLAIN can only be produced
+    # here, where the connection already exists. It is what turns "this query
+    # took 340ms" into "this query sequentially scans orders".
+    #
+    # Safety rules, in order of importance:
+    #   * read-only statements only — never explain a write
+    #   * plain EXPLAIN, never EXPLAIN ANALYZE (which executes the statement)
+    #   * a wall-clock timeout, so a slow planner cannot stall a request
+    #   * one EXPLAIN per distinct statement, not per occurrence
+    #   * every failure is swallowed — instrumentation must never break the app
+    module ExplainCapture
+      DEFAULT_TIMEOUT = 2 # seconds
+      # Bounds the memory held by the "already explained" set on an app with
+      # heavily varied SQL.
+      MAX_CACHED_STATEMENTS = 500
+
+      # Guards against the EXPLAIN itself emitting a sql.active_record event
+      # that feeds straight back into capture.
+      IN_FLIGHT_KEY = :brainzlab_explain_in_flight
+
+      READ_ONLY_START = /\A\s*(?:SELECT|WITH)\b/i
+      # Any statement separator followed by more content: a plan-only statement
+      # must be a single query.
+      MULTI_STATEMENT = /;\s*\S/
+
+      class << self
+        # @param sql [String] the statement to explain
+        # @param connection [Object] an ActiveRecord-like connection
+        # @param timeout [Integer] seconds to wait for the plan
+        # @return [Hash, nil] { plan:, adapter: } or nil when not captured
+        def capture(sql:, connection:, timeout: DEFAULT_TIMEOUT)
+          return nil if Thread.current[IN_FLIGHT_KEY]
+          return nil unless explainable?(sql)
+          return nil unless connection.respond_to?(:exec_query)
+
+          fingerprint = fingerprint_for(sql)
+          return nil if already_explained?(fingerprint)
+
+          Thread.current[IN_FLIGHT_KEY] = true
+          begin
+            remember(fingerprint)
+            plan = Timeout.timeout(timeout) { run_explain(sql, connection) }
+            return nil if plan.nil? || plan.empty?
+
+            { plan: plan, adapter: adapter_for(connection) }
+          rescue StandardError => e
+            BrainzLab.debug_log("Explain capture failed: #{e.message}")
+            nil
+          ensure
+            Thread.current[IN_FLIGHT_KEY] = nil
+          end
+        end
+
+        # Forget which statements have been explained. Used by the specs and
+        # available to long-lived processes that want to re-sample plans.
+        def reset!
+          mutex.synchronize { explained.clear }
+        end
+
+        private
+
+        def explainable?(sql)
+          return false if sql.nil? || sql.strip.empty?
+          return false unless sql.match?(READ_ONLY_START)
+          return false if sql.match?(MULTI_STATEMENT)
+
+          true
+        end
+
+        def run_explain(sql, connection)
+          result = connection.exec_query("EXPLAIN #{sql}")
+          rows = result.respond_to?(:rows) ? result.rows : result
+          return nil if rows.nil?
+
+          Array(rows).map { |row| Array(row).join(' | ') }.join("\n")
+        end
+
+        def adapter_for(connection)
+          return nil unless connection.respond_to?(:adapter_name)
+
+          connection.adapter_name.to_s.downcase
+        rescue StandardError
+          nil
+        end
+
+        # Collapse whitespace so that the same statement formatted differently
+        # is not explained twice.
+        def fingerprint_for(sql)
+          sql.strip.gsub(/\s+/, ' ')
+        end
+
+        def already_explained?(fingerprint)
+          mutex.synchronize { explained.include?(fingerprint) }
+        end
+
+        def remember(fingerprint)
+          mutex.synchronize do
+            explained.clear if explained.size >= MAX_CACHED_STATEMENTS
+            explained << fingerprint
+          end
+        end
+
+        def explained
+          @explained ||= Set.new
+        end
+
+        def mutex
+          @mutex ||= Mutex.new
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/pulse.rb

@@ -5,6 +5,7 @@ require_relative 'pulse/provisioner'
 require_relative 'pulse/tracer'
 require_relative 'pulse/instrumentation'
 require_relative 'pulse/propagation'
+require_relative 'pulse/explain_capture'
 
 module BrainzLab
   module Pulse

data/lib/brainzlab/signal/client.rb

@@ -11,16 +11,30 @@ module BrainzLab
         @config = config
       end
 
+      # ⚠️ Signal NO expone un endpoint de alta de alertas ad-hoc.
+      # `resources :alerts` es `only: [:index, :show]`, así que este POST
+      # devolvía 404 (verificado contra producción el 2026-10-16). Se enruta a
+      # `alerts#trigger`, que es lo más cercano que existe — pero exige que YA
+      # exista una AlertRule con ese `name` en el proyecto, o responde 404.
+      # Ver company/tasks/signal-alertas-caidas en el OS: reconciliar la API
+      # del SDK con el modelo de Signal es una decisión de producto pendiente.
       def send_alert(alert)
-        post('/api/v1/alerts', alert)
+        post('/api/v1/alerts/trigger', alert)
       end
 
+      # ⚠️ Signal no tiene ninguna ruta `notifications` (grep en su
+      # config/routes.rb: 0 coincidencias). Este POST siempre fue un 404.
+      # No se reenruta a ciegas porque no hay equivalente: entregar a un canal
+      # concreto es otra cosa que disparar una alerta.
       def send_notification(notification)
         post('/api/v1/notifications', notification)
       end
 
+      # Antes posteaba a '/api/v1/rules/trigger', que no existe —
+      # `resources :rules` solo expone los miembros mute/unmute/test.
+      # La ruta real es `post "alerts/trigger" => "alerts#trigger"`.
       def trigger_rule(payload)
-        post('/api/v1/rules/trigger', payload)
+        post('/api/v1/alerts/trigger', payload)
       end
 
       private

data/lib/brainzlab/signal.rb

@@ -72,9 +72,17 @@ module BrainzLab
         ensure_provisioned!
         return unless BrainzLab.configuration.signal_valid?
 
+        # `alerts#trigger` en Signal lee params[:name], params[:value] y
+        # params[:labels] — NO params[:rule] ni params[:context]. Mandar `rule:`
+        # hacía que `find_by!(name: nil)` levantara RecordNotFound → 404, así
+        # que ni con la ruta correcta habría funcionado. Se mantienen las claves
+        # viejas por compatibilidad con cualquier consumidor que las lea.
         payload = {
           type: 'trigger',
+          name: rule_name,
           rule: rule_name,
+          value: context[:value] || context['value'],
+          labels: context,
           context: context,
           timestamp: Time.now.utc.iso8601(3),
           environment: BrainzLab.configuration.environment,

data/lib/brainzlab/utilities/route_path_normalizer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Utilities
+    # Collapses concrete request paths into route patterns, so that
+    # /users/1, /users/2 ... /users/99999 aggregate as a single /users/:id
+    # endpoint instead of one endpoint per record.
+    #
+    # Rails instrumentation names traces by controller#action and does not need
+    # this. Grape and plain Rack do: when the router does not expose a route
+    # pattern the SDK falls back to the raw PATH_INFO, which is where the
+    # cardinality blowup comes from.
+    #
+    # Two modes:
+    #   * with path params — substitute the exact values the router resolved
+    #   * without them — fall back to recognising id-shaped segments
+    module RoutePathNormalizer
+      # Params that describe the dispatch rather than the path itself.
+      SKIP_PARAMS = %i[controller action format].freeze
+
+      UUID_PATTERN = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+      NUMERIC_PATTERN = /\A\d+\z/
+      # 16+ hex chars: git SHAs, hex tokens. Shorter hex strings are too easily
+      # a real word segment ("beef", "cafe") to risk substituting.
+      LONG_HEX_PATTERN = /\A\h{16,}\z/
+
+      module_function
+
+      # @param path [String, nil] the concrete request path
+      # @param path_params [Hash, nil] params the router resolved, when available
+      # @return [String, nil] the path with variable segments replaced
+      def normalize(path, path_params = nil)
+        return path if path.nil? || path.empty?
+
+        params = normalize_params(path_params)
+
+        # -1 keeps trailing empty segments, so a trailing slash survives.
+        segments = path.split('/', -1)
+        normalized = segments.map do |segment|
+          next segment if segment.empty?
+
+          params.empty? ? substitute_by_shape(segment) : substitute_by_param(segment, params)
+        end
+
+        normalized.join('/')
+      end
+
+      def normalize_params(path_params)
+        return {} if path_params.nil? || path_params.empty?
+
+        # Map value => [param names]. A value claimed by more than one param is
+        # ambiguous, so it is left alone rather than guessed at.
+        path_params.each_with_object({}) do |(key, value), map|
+          next if SKIP_PARAMS.include?(key.to_sym)
+
+          (map[value.to_s] ||= []) << key
+        end
+      end
+
+      def substitute_by_param(segment, params)
+        keys = params[segment]
+        return ":#{keys.first}" if keys && keys.length == 1
+
+        # "42.json" when the id param is "42"
+        if segment.include?('.')
+          base, extension = segment.split('.', 2)
+          keys = params[base]
+          return ":#{keys.first}.#{extension}" if keys && keys.length == 1
+        end
+
+        segment
+      end
+
+      def substitute_by_shape(segment)
+        base, extension = segment.include?('.') ? segment.split('.', 2) : [segment, nil]
+        placeholder = placeholder_for(base)
+        return segment if placeholder.nil?
+
+        extension ? "#{placeholder}.#{extension}" : placeholder
+      end
+
+      def placeholder_for(segment)
+        return ':uuid' if segment.match?(UUID_PATTERN)
+        return ':id' if segment.match?(NUMERIC_PATTERN)
+        return ':id' if segment.match?(LONG_HEX_PATTERN)
+
+        nil
+      end
+    end
+  end
+end

data/lib/brainzlab/utilities.rb

@@ -4,6 +4,7 @@ require_relative 'utilities/rate_limiter'
 require_relative 'utilities/circuit_breaker'
 require_relative 'utilities/health_check'
 require_relative 'utilities/log_formatter'
+require_relative 'utilities/route_path_normalizer'
 
 module BrainzLab
   module Utilities

data/lib/brainzlab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BrainzLab
-  VERSION = '0.1.33'
+  VERSION = '0.1.34'
 end

data/lib/brainzlab.rb

@@ -63,6 +63,7 @@ module BrainzLab
 
     def configure
       yield(configuration) if block_given?
+      configuration.validate!
       configuration
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainzlab
 version: !ruby/object:Gem::Version
-  version: 0.1.33
+  version: 0.1.34
 platform: ruby
 authors:
 - BrainzLab
@@ -177,6 +177,7 @@ files:
 - lib/brainzlab/nerve/provisioner.rb
 - lib/brainzlab/pulse.rb
 - lib/brainzlab/pulse/client.rb
+- lib/brainzlab/pulse/explain_capture.rb
 - lib/brainzlab/pulse/instrumentation.rb
 - lib/brainzlab/pulse/propagation.rb
 - lib/brainzlab/pulse/provisioner.rb
@@ -211,6 +212,7 @@ files:
 - lib/brainzlab/utilities/health_check.rb
 - lib/brainzlab/utilities/log_formatter.rb
 - lib/brainzlab/utilities/rate_limiter.rb
+- lib/brainzlab/utilities/route_path_normalizer.rb
 - lib/brainzlab/vault.rb
 - lib/brainzlab/vault/cache.rb
 - lib/brainzlab/vault/client.rb