rails-otel-context 0.9.7 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8ea9eb65d7e405bbd14a39889bbad983edbba5c4bdcce252157d426a2372bc6
-  data.tar.gz: c70ddac87d64c8359fe82fe142bda62e4968b3429ea6944796b475270310d1d7
+  metadata.gz: 0aa66c7dfd0480bd0a9100e00fbea58eaab5ec0153dd5cb4a82b8df840092787
+  data.tar.gz: 9743746552b3a934798f2812a61f9d4f72f5c296ba75dae943b9dcb5120e8f5e
 SHA512:
-  metadata.gz: cfee7357103d1336be233b9b6724c1b6678117f7fcd3e57dda75ca473a3a608c8f511e7151db29cd9bce34627fcd8d0b482fcdb640812941c960385bf57acadd
-  data.tar.gz: 15888432fb759223a87cdf35f0dd9ae00c07ac59ef038b06bd49644968996b23fc910b0cca0f0912857bf8a4101ad9d005aa66596cef5b4a1e29de68a12486c8
+  metadata.gz: 40c59f1db646b5d159e23b36d9f651b4809ee19dc8f797ef9b6a5d261810ccfabc7d50c4460e01ac1b132058e1a28d9312b235d0c66e2f99fa6503f98a5ce4b9
+  data.tar.gz: 828f792d02e5ff2c7588d946f8535f5d41f25ad84e55f22854f73e007cb6bf6c39eaf1f05ab40eedae6a37c0d8d5c9e952d127428255221d47bee6d72e51170f

data/lib/rails_otel_context/activerecord_context.rb

@@ -12,11 +12,12 @@ module RailsOtelContext
   #    Relation#exec_queries. This handles lazy scopes like
   #    Transaction.recent_completed.to_a where the scope method returns before
   #    SQL fires.
-  module ActiveRecordContext
-    THREAD_KEY       = :_rails_otel_ctx_ar
-    SCOPE_THREAD_KEY = :_rails_otel_ctx_scope
-    DB_SLOW_ATTR     = 'db.slow'
-    private_constant :THREAD_KEY, :SCOPE_THREAD_KEY
+  module ActiveRecordContext # rubocop:disable Metrics/ModuleLength
+    THREAD_KEY              = :_rails_otel_ctx_ar
+    SCOPE_THREAD_KEY        = :_rails_otel_ctx_scope
+    PENDING_PREPARE_KEY     = :_rails_otel_ctx_pending_prepare_spans
+    DB_SLOW_ATTR            = 'db.slow'
+    private_constant :THREAD_KEY, :SCOPE_THREAD_KEY, :PENDING_PREPARE_KEY
 
     # Frozen regex — only the verb regex remains; table extraction uses index+slice.
     SQL_VERB_RE = /\A(\w+)/i
@@ -102,18 +103,29 @@ module RailsOtelContext
         ctx[:async] = true if payload[:async]
         Thread.current[THREAD_KEY] = ctx
 
+        return unless defined?(OpenTelemetry::Trace)
+
         # Enrich the current span directly. When OTel instruments via driver-level
         # prepend (Trilogy, PG, Mysql2), the span is created BEFORE this notification
         # fires, so CallContextProcessor#on_start sees nil AR context. Applying here
         # fixes those spans after the fact.
-        return unless defined?(OpenTelemetry::Trace)
-
         ActiveRecordContext.apply_to_span(OpenTelemetry::Trace.current_span, ctx)
+
+        # Retroactively enrich any PREPARE spans that finished before this notification
+        # fired. PG's prepared-statement flow sends PREPARE then EXECUTE as separate wire
+        # operations; the PREPARE span finishes before sql.active_record starts, so it
+        # never sees AR context. CallContextProcessor#on_finish stashes those spans here.
+        pending = Thread.current[PENDING_PREPARE_KEY]
+        return unless pending
+
+        pending.each { |s| ActiveRecordContext.retroactively_apply_to_span(s, ctx) }
+        Thread.current[PENDING_PREPARE_KEY] = nil
       end
 
       def finish(_name, _id, _payload)
       ensure
         Thread.current[THREAD_KEY] = nil
+        Thread.current[PENDING_PREPARE_KEY] = nil # clear any leftovers from skipped notifications
       end
     end
 
@@ -173,8 +185,16 @@ module RailsOtelContext
     end
 
     def clear!
-      Thread.current[THREAD_KEY]       = nil
-      Thread.current[SCOPE_THREAD_KEY] = nil
+      Thread.current[THREAD_KEY]          = nil
+      Thread.current[SCOPE_THREAD_KEY]    = nil
+      Thread.current[PENDING_PREPARE_KEY] = nil
+    end
+
+    # Called from CallContextProcessor#on_finish when a PREPARE span finishes
+    # before its sql.active_record notification. Stashed spans are flushed by
+    # Subscriber#start when the notification fires.
+    def stash_prepare_span(span)
+      (Thread.current[PENDING_PREPARE_KEY] ||= []) << span
     end
 
     # Test helpers: set AR context directly for unit tests.
@@ -186,6 +206,34 @@ module RailsOtelContext
       Thread.current[SCOPE_THREAD_KEY] = scope_name
     end
 
+    # Retroactively applies AR context to a finished span (e.g. PREPARE spans that
+    # finished before sql.active_record fired). Uses direct @attributes mutation
+    # because span.recording? is false — set_attribute would be a no-op.
+    def retroactively_apply_to_span(span, ctx)
+      attrs = span.instance_variable_get(:@attributes)
+      return unless attrs.respond_to?(:store)
+
+      attrs.store(AR_MODEL_ATTR,  ctx[:model_name])  if ctx[:model_name]
+      attrs.store(AR_METHOD_ATTR, ctx[:method_name]) if ctx[:method_name]
+      attrs.store(AR_SCOPE_ATTR,  ctx[:scope_name])  if ctx[:scope_name]
+
+      formatter = RailsOtelContext.configuration.span_name_formatter
+      return unless formatter && span.respond_to?(:name) && attrs.key?('db.system')
+
+      ar_ctx = ctx.dup
+      ar_ctx[:code_namespace] = attrs['code.namespace']
+      ar_ctx[:code_function]  = attrs['code.function']
+
+      original_name = span.name
+      new_name = formatter.call(original_name, ar_ctx)
+      return unless new_name && new_name != original_name
+
+      attrs.store(ORIG_NAME_ATTR, original_name)
+      span.instance_variable_set(:@name, new_name)
+    rescue StandardError
+      nil
+    end
+
     # Applies AR context directly to a span. Used by Subscriber#start to enrich spans
     # created by driver-level OTel instrumentation (Trilogy, PG) before our notification
     # subscriber runs. Also reads code.namespace/code.function already set by

data/lib/rails_otel_context/adapters/clickhouse.rb

@@ -5,7 +5,14 @@ module RailsOtelContext
     module Clickhouse
       module_function
 
-      CANDIDATE_METHODS = %i[query select insert execute command].freeze
+      # click_house gem v1.x used :query/:select; v2.x uses :select_all/:select_one/:select_value.
+      # We list all known variants so install! picks whichever the loaded gem version defines.
+      CANDIDATE_METHODS = %i[
+        select_all select_one select_value
+        insert insert_compact insert_rows
+        execute command
+        query select
+      ].freeze
       REENTRANCY_KEY = :_rails_otel_ctx_clickhouse_instrumenting
 
       def install!(app_root:)
@@ -43,6 +50,52 @@ module RailsOtelContext
         @patch_modules[key] ||= build_patch_module(methods)
       end
 
+      # Maps compound gem method names to their SQL verb for span naming.
+      # select_all/select_one/select_value → SELECT; insert_* → INSERT.
+      METHOD_OP_ALIAS = {
+        'SELECT_ALL' => 'SELECT',
+        'SELECT_ONE' => 'SELECT',
+        'SELECT_VALUE' => 'SELECT',
+        'INSERT_COMPACT' => 'INSERT',
+        'INSERT_ROWS' => 'INSERT'
+      }.freeze
+
+      # Derives a human-readable span name from the SQL statement.
+      # Follows OTel DB convention: "{sql_verb} {table}".
+      # Falls back to "{method_op} clickhouse" when the statement is absent
+      # or cannot be parsed (e.g. raw ClickHouse commands with no FROM clause).
+      #
+      # Accepts an optional pre-parsed +table_name+ to avoid a second regex scan
+      # when the caller already holds the result of parse_table.
+      def span_name_for(statement, method_op, table_name: nil)
+        effective_op = METHOD_OP_ALIAS.fetch(method_op, method_op)
+        return "#{effective_op} clickhouse" unless statement.is_a?(String)
+
+        sql_verb   = statement.lstrip.split(/\s/, 2).first&.upcase
+        table_name = parse_table(statement).last if table_name.nil?
+
+        if sql_verb && table_name
+          "#{sql_verb} #{table_name}"
+        elsif sql_verb
+          "#{sql_verb} clickhouse"
+        else
+          "#{effective_op} clickhouse"
+        end
+      end
+
+      # Returns [db_name, table_name] extracted from the SQL statement.
+      # db_name is the schema prefix (e.g. "mailgun_analytics"), nil when absent.
+      # table_name is the bare table (e.g. "mailgun_events"), nil when not found.
+      def parse_table(statement)
+        return [nil, nil] unless statement.is_a?(String)
+
+        qualified = statement.match(/(?:\bFROM\b|\bINTO\b|\bUPDATE\b)\s+([\w.]+)/i)&.captures&.first
+        return [nil, nil] unless qualified
+
+        parts = qualified.split('.')
+        parts.size > 1 ? [parts[0..-2].join('.'), parts.last] : [nil, parts.first]
+      end
+
       def build_patch_module(methods)
         mod = Module.new do
           class << self
@@ -55,11 +108,12 @@ module RailsOtelContext
             end
           end
 
-          # AR context and span renaming handled by CallContextProcessor.apply_db_context.
           reentrancy_key = RailsOtelContext::Adapters::Clickhouse::REENTRANCY_KEY
 
           methods.each do |method_name|
-            operation = method_name.to_s.upcase.freeze
+            method_op = RailsOtelContext::Adapters::Clickhouse::METHOD_OP_ALIAS
+                        .fetch(method_name.to_s.upcase, method_name.to_s.upcase)
+                        .freeze
 
             define_method(method_name) do |*args, &block|
               return super(*args, &block) if Thread.current[reentrancy_key]
@@ -67,16 +121,45 @@ module RailsOtelContext
               site      = mod.call_site_for_app
               statement = args.first.is_a?(String) ? args.first : nil
 
+              # Parse table once — span_name_for accepts the pre-parsed value to skip
+              # the internal regex scan, and we reuse db_name for db.name attribute.
+              db_name, table_name = RailsOtelContext::Adapters::Clickhouse.parse_table(statement)
+              sql_verb  = statement ? statement.lstrip.split(/\s/, 2).first&.upcase || method_op : method_op
+              span_name = RailsOtelContext::Adapters::Clickhouse.span_name_for(
+                statement, method_op, table_name: table_name
+              )
+
               tracer = OpenTelemetry.tracer_provider.tracer('rails-otel-context-clickhouse')
               Thread.current[reentrancy_key] = true
 
-              tracer.in_span("#{operation} clickhouse", kind: :client) do |span|
-                span.set_attribute('db.system', 'clickhouse')
-                span.set_attribute('db.operation', operation)
-                span.set_attribute('db.statement', statement) if statement
+              tracer.in_span(span_name, kind: :client) do |span|
+                span.set_attribute('db.system',    'clickhouse')
+                span.set_attribute('db.operation', sql_verb)
+                span.set_attribute('db.statement', statement)   if statement
+                span.set_attribute('db.name',      db_name)     if db_name
+                span.set_attribute('db.sql.table', table_name)  if table_name
 
                 result = super(*args, &block)
                 mod.apply_call_site_to_span(span, site)
+
+                # ClickHouse spans don't fire sql.active_record notifications, so
+                # CallContextProcessor#apply_db_context never runs for them.
+                # Apply the span_name_formatter here with a synthetic AR-shaped context
+                # built from code.namespace/code.function set by apply_call_site_to_span.
+                formatter = RailsOtelContext.configuration.span_name_formatter
+                code_ns   = formatter && span.respond_to?(:attributes) &&
+                            span.attributes['code.namespace']
+                if code_ns
+                  fn = span.attributes['code.function']
+                  ar_ctx = { model_name: code_ns, method_name: fn, scope_name: nil,
+                             code_namespace: code_ns, code_function: fn }
+                  new_name = formatter.call(span_name, ar_ctx)
+                  if new_name && new_name != span_name
+                    span.set_attribute('l9.orig.name', span_name)
+                    span.name = new_name
+                  end
+                end
+
                 result
               end
             ensure

data/lib/rails_otel_context/adapters/connection_pool.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  module Adapters
+    module ConnectionPool
+      TRACER_NAME = 'rails_otel_context'
+      SPAN_NAME   = 'active_record.connection_checkout'
+      private_constant :TRACER_NAME, :SPAN_NAME
+
+      module_function
+
+      def install!
+        return unless defined?(::ActiveRecord::ConnectionAdapters::ConnectionPool)
+
+        patch_module = patch_module_for
+        return if ::ActiveRecord::ConnectionAdapters::ConnectionPool.ancestors.include?(patch_module)
+
+        ::ActiveRecord::ConnectionAdapters::ConnectionPool.prepend(patch_module)
+      end
+
+      def patch_module_for
+        @patch_module ||= build_patch_module
+      end
+
+      def build_patch_module
+        # Capture as locals so define_method closes over them — constants declared
+        # private_constant are inaccessible from the anonymous module's def scope.
+        tracer_name   = TRACER_NAME
+        span_name     = SPAN_NAME
+        # Cached lazily on first checkout — tracer_provider may not be fully
+        # configured when install! runs at boot.
+        cached_tracer = nil
+
+        Module.new do
+          define_method(:checkout) do |checkout_timeout = @checkout_timeout|
+            # Rails 7.2+ fast path: pinned connection bypasses pool wait entirely.
+            # No span needed — duration would be ~0ms and it's misleading noise.
+            return super(checkout_timeout) if @pinned_connection
+
+            cached_tracer ||= OpenTelemetry.tracer_provider.tracer(tracer_name)
+
+            cached_tracer.in_span(span_name) do |span|
+              result = super(checkout_timeout)
+
+              # stat acquires the pool's monitor lock and iterates @connections —
+              # acceptable for opt-in diagnostics. Avoid enabling this permanently
+              # on high-traffic pools where lock contention is already a concern.
+              pool_stat = stat
+              span.set_attribute('db.pool.size',    pool_stat[:size])
+              span.set_attribute('db.pool.busy',    pool_stat[:busy])
+              span.set_attribute('db.pool.idle',    pool_stat[:idle])
+              span.set_attribute('db.pool.waiting', pool_stat[:waiting])
+
+              result
+            end
+          end
+        end
+      end
+      private_class_method :patch_module_for, :build_patch_module
+    end
+  end
+end

data/lib/rails_otel_context/adapters.rb

@@ -5,6 +5,7 @@ require 'rails_otel_context/adapters/mysql2'
 require 'rails_otel_context/adapters/trilogy'
 require 'rails_otel_context/adapters/redis'
 require 'rails_otel_context/adapters/clickhouse'
+require 'rails_otel_context/adapters/connection_pool'
 
 module RailsOtelContext
   module Adapters
@@ -16,6 +17,7 @@ module RailsOtelContext
       Trilogy.install!(app_root: app_root)
       Redis.install!(app_root: app_root) if config.redis_source_enabled
       Clickhouse.install!(app_root: app_root) if config.clickhouse_enabled
+      ConnectionPool.install! if config.connection_pool_tracing_enabled
     end
   end
 end

data/lib/rails_otel_context/body_capture.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  # Rack middleware that captures request and response bodies as OpenTelemetry
+  # span attributes. Works with any OTel Rack instrumentation — the middleware
+  # must sit inside (after) the span-creating middleware so current_span is set.
+  #
+  # Usage:
+  #   # config/application.rb (or an initializer after OTel is configured)
+  #   config.middleware.use RailsOtelContext::BodyCapture
+  #
+  #   # With options:
+  #   config.middleware.use RailsOtelContext::BodyCapture,
+  #     on_error_only: true,
+  #     max_bytes:     4096
+  #
+  # Span attributes set:
+  #   http.request.body  — captured request body (when content type matches)
+  #   http.response.body — captured response body (when content type matches)
+  class BodyCapture
+    DEFAULT_CONTENT_TYPES = %w[application/json application/xml text/plain].freeze
+    DEFAULT_EXCLUDE_PATHS = %w[/health /ready /metrics].freeze
+    DEFAULT_MAX_BYTES     = 8_192
+    TRUNCATED_SUFFIX      = '...[TRUNCATED]'
+    private_constant :DEFAULT_CONTENT_TYPES, :DEFAULT_EXCLUDE_PATHS,
+                     :DEFAULT_MAX_BYTES, :TRUNCATED_SUFFIX
+
+    def initialize(app, # rubocop:disable Metrics/ParameterLists
+                   capture_request:  true,
+                   capture_response: true,
+                   max_bytes:        DEFAULT_MAX_BYTES,
+                   on_error_only:    false,
+                   content_types:    DEFAULT_CONTENT_TYPES,
+                   include_paths:    [],
+                   exclude_paths:    DEFAULT_EXCLUDE_PATHS)
+      @app              = app
+      @capture_request  = capture_request
+      @capture_response = capture_response
+      @max_bytes        = max_bytes
+      @on_error_only    = on_error_only
+      @content_types    = content_types
+      @include_paths    = include_paths
+      @exclude_paths    = exclude_paths
+    end
+
+    def call(env)
+      return @app.call(env) unless should_capture?(env['PATH_INFO'])
+
+      request_str           = read_request(env)
+      status, headers, body = @app.call(env)
+
+      # With on_error_only, skip body drain on successful responses — no buffering
+      # overhead on the happy path. (Synchronous Rack means we know status before
+      # deciding to drain, unlike async frameworks that must always buffer.)
+      should_record = !@on_error_only || status >= 400
+
+      if should_record && @capture_response
+        body, response_str = drain_response(body, headers)
+      end
+
+      set_span_attributes(request_str, response_str) if should_record
+
+      [status, headers, body]
+    end
+
+    private
+
+    def should_capture?(path)
+      return false if @exclude_paths.any? { |p| path.start_with?(p) }
+      return true  if @include_paths.empty?
+
+      @include_paths.any? { |p| path.start_with?(p) }
+    end
+
+    def allowed_content_type?(content_type)
+      return false unless content_type && !content_type.empty?
+      return true  if @content_types.empty?
+
+      @content_types.any? { |ct| content_type.include?(ct) }
+    end
+
+    def read_request(env)
+      return unless @capture_request
+      return unless allowed_content_type?(env['CONTENT_TYPE'])
+
+      input = env['rack.input']
+      return unless input
+
+      raw = input.read
+      input.rewind
+      cap(raw)
+    end
+
+    def drain_response(body, headers)
+      chunks = body.map { |chunk| chunk }
+      body.close if body.respond_to?(:close)
+
+      content_type = headers['Content-Type'] || headers['content-type']
+      body_str     = cap(chunks.join) if allowed_content_type?(content_type)
+
+      [chunks, body_str]
+    end
+
+    def set_span_attributes(request_str, response_str)
+      return unless defined?(OpenTelemetry)
+
+      span = OpenTelemetry::Trace.current_span
+      return unless span.context.valid?
+
+      span.set_attribute('http.request.body',  request_str)  if request_str
+      span.set_attribute('http.response.body', response_str) if response_str
+    end
+
+    def cap(str)
+      return nil if str.nil? || str.empty?
+      return str if str.bytesize <= @max_bytes
+
+      # scrub cleans up any incomplete multibyte sequence at the slice boundary
+      str.byteslice(0, @max_bytes).scrub + TRUNCATED_SUFFIX
+    end
+  end
+end

data/lib/rails_otel_context/call_context_processor.rb

@@ -52,8 +52,14 @@ module RailsOtelContext
     end
 
     def on_finish(span)
+      return unless span.respond_to?(:attributes)
+
+      attrs = span.attributes
+      return unless attrs&.key?('db.system')
+
+      stash_if_prepare_span(span, attrs)
+
       return unless @slow_query_threshold_ms
-      return unless span.respond_to?(:attributes) && span.attributes&.key?('db.system')
 
       start_ns = span.start_timestamp
       end_ns   = span.end_timestamp
@@ -65,8 +71,8 @@ module RailsOtelContext
       # span.recording? is false here — the span has finished and current_span
       # has reverted to the HTTP parent. Write directly to the backing attributes
       # hash so db.slow lands on the actual DB span, not the HTTP parent.
-      attrs = span.instance_variable_get(:@attributes)
-      attrs.store(ActiveRecordContext::DB_SLOW_ATTR, true) if attrs.respond_to?(:store)
+      raw_attrs = span.instance_variable_get(:@attributes)
+      raw_attrs.store(ActiveRecordContext::DB_SLOW_ATTR, true) if raw_attrs.respond_to?(:store)
     rescue StandardError
       nil
     end
@@ -79,6 +85,17 @@ module RailsOtelContext
 
     private
 
+    # Stash PREPARE spans so Subscriber#start can retroactively apply AR context
+    # once the enclosing sql.active_record notification fires. PG's prepared-statement
+    # flow runs PREPARE → EXECUTE as separate wire operations; the PREPARE span
+    # finishes before the notification, so on_start never sees AR context for it.
+    def stash_if_prepare_span(span, attrs)
+      return unless attrs['db.operation'] == 'PREPARE'
+      return if attrs.key?('code.activerecord.model')
+
+      ActiveRecordContext.stash_prepare_span(span)
+    end
+
     def apply_call_context(span)
       # Explicit override: app code called FrameContext.with_frame (or Frameable).
       # O(1) — no stack walk. Takes priority over automatic detection.

data/lib/rails_otel_context/configuration.rb

@@ -4,6 +4,7 @@ module RailsOtelContext
   class Configuration
     attr_accessor :redis_source_enabled,
                   :clickhouse_enabled,
+                  :connection_pool_tracing_enabled,
                   :span_name_formatter,
                   :slow_query_threshold_ms
 
@@ -16,6 +17,7 @@ module RailsOtelContext
     def initialize
       @redis_source_enabled = false
       @clickhouse_enabled = true
+      @connection_pool_tracing_enabled = false
       @span_name_formatter = nil
       @custom_span_attributes = nil
       @request_context_enabled = false

data/lib/rails_otel_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsOtelContext
-  VERSION = '0.9.7'
+  VERSION = '0.9.8'
 end

data/lib/rails_otel_context.rb

@@ -14,6 +14,7 @@ require 'rails_otel_context/adapters'
 require 'rails_otel_context/request_context'
 require 'rails_otel_context/frame_context'
 require 'rails_otel_context/call_context_processor'
+require 'rails_otel_context/body_capture'
 require 'rails_otel_context/railtie' if defined?(Rails::Railtie)
 
 module RailsOtelContext

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-otel-context
 version: !ruby/object:Gem::Version
-  version: 0.9.7
+  version: 0.9.8
 platform: ruby
 authors:
 - Last9
@@ -66,10 +66,12 @@ files:
 - lib/rails_otel_context/activerecord_context.rb
 - lib/rails_otel_context/adapters.rb
 - lib/rails_otel_context/adapters/clickhouse.rb
+- lib/rails_otel_context/adapters/connection_pool.rb
 - lib/rails_otel_context/adapters/mysql2.rb
 - lib/rails_otel_context/adapters/pg.rb
 - lib/rails_otel_context/adapters/redis.rb
 - lib/rails_otel_context/adapters/trilogy.rb
+- lib/rails_otel_context/body_capture.rb
 - lib/rails_otel_context/call_context_processor.rb
 - lib/rails_otel_context/configuration.rb
 - lib/rails_otel_context/frame_context.rb