rails-otel-context 0.9.8 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aa66c7dfd0480bd0a9100e00fbea58eaab5ec0153dd5cb4a82b8df840092787
-  data.tar.gz: 9743746552b3a934798f2812a61f9d4f72f5c296ba75dae943b9dcb5120e8f5e
+  metadata.gz: 4eb35396c5cddc8f420624441b7f2bdacf2d1ef005510db0855cb9803cfb4635
+  data.tar.gz: e8a3ffbb994abad920bf7ccbc66903777d380952711237ca4ce0cd7ef153c7c0
 SHA512:
-  metadata.gz: 40c59f1db646b5d159e23b36d9f651b4809ee19dc8f797ef9b6a5d261810ccfabc7d50c4460e01ac1b132058e1a28d9312b235d0c66e2f99fa6503f98a5ce4b9
-  data.tar.gz: 828f792d02e5ff2c7588d946f8535f5d41f25ad84e55f22854f73e007cb6bf6c39eaf1f05ab40eedae6a37c0d8d5c9e952d127428255221d47bee6d72e51170f
+  metadata.gz: b1c75e3474d1d922f96427658daafbe73b7ca41e9f8f59a6654f7cc2ef4576a7d055287d1fb95b75161a1c178848350672f7b05f798ef080aef50236d6d36824
+  data.tar.gz: e2708c7b6dfa266cd62f66d7b302f54aa181108b47fa7fc589fe5e5a0645a42bab0a4d73753f3fd3c326df24c99280052b025808995cda86815662d7848bb573

data/README.md

@@ -76,7 +76,7 @@ DB spans additionally get:
 
 ## Configuration
 
-Zero configuration gets you everything above. The optional initializer adds span naming and slow-query detection:
+Zero configuration gets you everything above. The optional initializer adds span naming, slow-query detection, and opts into the heavier adapters:
 
 ```ruby
 # config/initializers/rails_otel_context.rb
@@ -115,6 +115,11 @@ RailsOtelContext.configure do |c|
 
   # Attach any per-request context to every span
   c.custom_span_attributes = -> { { 'tenant' => Current.tenant } if Current.tenant }
+
+  # Opt-in adapters — disabled by default because they patch third-party classes
+  # and add a span per call. Turn on what you actually use.
+  c.clickhouse_enabled             = true  # instrument click_house gem queries
+  c.connection_pool_tracing_enabled = true  # span per AR connection checkout
 end
 ```
 
@@ -222,7 +227,13 @@ end
 
 ## Redis and ClickHouse
 
-Redis and ClickHouse spans get the same `code.*` attributes pointing to the app-code frame that issued the call:
+Redis is enabled by default. ClickHouse requires opt-in:
+
+```ruby
+c.clickhouse_enabled = true
+```
+
+Both get the same `code.*` attributes pointing to the app-code frame that issued the call:
 
 ```json
 {
@@ -237,6 +248,70 @@ Redis and ClickHouse spans get the same `code.*` attributes pointing to the app-
 }
 ```
 
+### ClickHouse span naming
+
+ClickHouse spans follow the OTel DB convention: `"{VERB} {table}"`. No configuration required — this happens automatically when the ClickHouse adapter is active.
+
+| Query | Span name |
+|---|---|
+| `SELECT * FROM events` | `SELECT events` |
+| `INSERT INTO analytics.page_views ...` | `INSERT page_views` |
+| `OPTIMIZE TABLE logs` | `OPTIMIZE clickhouse` (no FROM — falls back gracefully) |
+
+Schema-qualified tables (`db.table`) are supported: `db.name` gets the schema, `db.sql.table` gets the bare table name.
+
+If you've configured a `span_name_formatter`, it runs on ClickHouse spans too — same formatter, no extra wiring. The original OTel name is preserved in `l9.orig.name`.
+
+## Capturing request and response bodies
+
+`BodyCapture` is a Rack middleware that attaches request and response bodies to the active OTel span. It's opt-in — add it to your middleware stack:
+
+```ruby
+# config/application.rb (or an initializer, after OTel is configured)
+config.middleware.use RailsOtelContext::BodyCapture
+```
+
+That's the zero-config path. Bodies land on `http.request.body` and `http.response.body`, capped at 8 KB, for `application/json`, `application/xml`, and `text/plain` content types. `/health`, `/ready`, and `/metrics` are excluded by default.
+
+The option that matters most in production:
+
+```ruby
+config.middleware.use RailsOtelContext::BodyCapture, on_error_only: true
+```
+
+With `on_error_only: true`, the response body is never buffered on the success path — zero overhead for 2xx. Bodies are only captured when status >= 400, which is exactly when you need them.
+
+Full options:
+
+| Option | Default | Description |
+|---|---|---|
+| `on_error_only:` | `false` | Capture only on 4xx/5xx |
+| `max_bytes:` | `8192` | Truncate bodies above this size |
+| `content_types:` | `%w[application/json application/xml text/plain]` | Allowlist |
+| `include_paths:` | `nil` | Restrict capture to these path prefixes |
+| `exclude_paths:` | `%w[/health /ready /metrics]` | Skip these path prefixes |
+
+## Connection pool tracing
+
+When you're chasing timeouts or thread starvation, knowing that `checkout` spent 200ms waiting for a connection is the difference between guessing and knowing. Both `clickhouse_enabled` and `connection_pool_tracing_enabled` are off by default — they patch third-party classes and add a span per call, which is overhead you should choose consciously. Enable it:
+
+```ruby
+RailsOtelContext.configure do |c|
+  c.connection_pool_tracing_enabled = true
+end
+```
+
+Each `checkout` call gets its own span with pool state at the moment of acquisition:
+
+| Attribute | Description |
+|---|---|
+| `db.pool.size` | Total pool capacity |
+| `db.pool.busy` | Connections currently checked out |
+| `db.pool.idle` | Connections available |
+| `db.pool.waiting` | Threads queued waiting for a connection |
+
+Spans inside transactions and `with_connection` blocks are skipped — a pinned connection is already held, so there's nothing to measure.
+
 ## Performance
 
 `CallContextProcessor#on_start` fires for every span. For a typical 10–20 span request the overhead is in the low-microsecond range and does not require configuration.

data/lib/rails_otel_context/activerecord_context.rb

@@ -213,9 +213,9 @@ module RailsOtelContext
       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]
+      attrs.store('code.activerecord.model',  ctx[:model_name])  if ctx[:model_name]
+      attrs.store('code.activerecord.method', ctx[:method_name]) if ctx[:method_name]
+      attrs.store('code.activerecord.scope',  ctx[:scope_name])  if ctx[:scope_name]
 
       formatter = RailsOtelContext.configuration.span_name_formatter
       return unless formatter && span.respond_to?(:name) && attrs.key?('db.system')
@@ -228,7 +228,7 @@ module RailsOtelContext
       new_name = formatter.call(original_name, ar_ctx)
       return unless new_name && new_name != original_name
 
-      attrs.store(ORIG_NAME_ATTR, original_name)
+      attrs.store('l9.orig.name', original_name)
       span.instance_variable_set(:@name, new_name)
     rescue StandardError
       nil

data/lib/rails_otel_context/adapters/clickhouse.rb

@@ -7,9 +7,12 @@ module RailsOtelContext
 
       # 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.
+      #
+      # insert/insert_rows/insert_compact are intentionally absent: in v2.x they all delegate
+      # to execute, so patching execute alone is sufficient and avoids wrapping methods whose
+      # keyword-argument signatures may differ across gem versions.
       CANDIDATE_METHODS = %i[
         select_all select_one select_value
-        insert insert_compact insert_rows
         execute command
         query select
       ].freeze
@@ -51,13 +54,11 @@ module RailsOtelContext
       end
 
       # Maps compound gem method names to their SQL verb for span naming.
-      # select_all/select_one/select_value → SELECT; insert_* → INSERT.
+      # select_all/select_one/select_value → SELECT.
       METHOD_OP_ALIAS = {
         'SELECT_ALL' => 'SELECT',
         'SELECT_ONE' => 'SELECT',
-        'SELECT_VALUE' => 'SELECT',
-        'INSERT_COMPACT' => 'INSERT',
-        'INSERT_ROWS' => 'INSERT'
+        'SELECT_VALUE' => 'SELECT'
       }.freeze
 
       # Derives a human-readable span name from the SQL statement.
@@ -115,55 +116,56 @@ module RailsOtelContext
                         .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]
-
-              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
-              )
+            define_method(method_name) do |*args, **kwargs, &block|
+              return super(*args, **kwargs, &block) if Thread.current[reentrancy_key]
 
-              tracer = OpenTelemetry.tracer_provider.tracer('rails-otel-context-clickhouse')
               Thread.current[reentrancy_key] = true
-
-              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
+              begin
+                site      = mod.call_site_for_app
+                statement = args.first.is_a?(String) ? args.first : nil
+
+                # Avoid a second regex scan: pass pre-parsed table_name to span_name_for,
+                # and reuse db_name for the 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')
+                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, **kwargs, &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
-                end
 
-                result
+                  result
+                end
+              ensure
+                Thread.current[reentrancy_key] = false
               end
-            ensure
-              Thread.current[reentrancy_key] = false
             end
           end
         end

data/lib/rails_otel_context/body_capture.rb

@@ -92,7 +92,8 @@ module RailsOtelContext
     end
 
     def drain_response(body, headers)
-      chunks = body.map { |chunk| chunk }
+      chunks = []
+      body.each { |chunk| chunks << chunk } # rubocop:disable Style/MapIntoArray -- RackBody (Rails 8) has no #map
       body.close if body.respond_to?(:close)
 
       content_type = headers['Content-Type'] || headers['content-type']

data/lib/rails_otel_context/configuration.rb

@@ -16,7 +16,7 @@ module RailsOtelContext
 
     def initialize
       @redis_source_enabled = false
-      @clickhouse_enabled = true
+      @clickhouse_enabled = false
       @connection_pool_tracing_enabled = false
       @span_name_formatter = nil
       @custom_span_attributes = nil

data/lib/rails_otel_context/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-otel-context
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 0.9.9
 platform: ruby
 authors:
 - Last9