foam-otel 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8650474eaaa3dec06f5500839b073d5c2b211750da4ad2a068459cbbb5feb3f1
-  data.tar.gz: 6c7b40fe1a9297f0c81547222f4ea7a36c716a9bc1eb6a2f97c5e44d49f6b9eb
+  metadata.gz: 89cc714cc54a1a460ea2876e90e1d6e444cddb25c24a3dd854f7ae59a2289286
+  data.tar.gz: dd8e3e10cd12c5b5246a6e50ce5ef175c40d97212d274336d28b2a54e6582cbd
 SHA512:
-  metadata.gz: 39fd5531d0478acdff0ae4e36ae901ee3975a2b2c55e84319bba959683ac3fa69dd226639f2c1c7f4682eec9d064843071209f7ed56bf149d30591cecc732ba8
-  data.tar.gz: b32886c34c0b60fd1f7751a7cb7e1a81152804c7c495078217ef7e63a83025b15b5336acffad32ebc23e730c42120aa8e32519cd3a9d1154f049130b75ad8160
+  metadata.gz: 401f450f54df5b4787f180a9f3a12ff367381aa731b4c28cc8ff13722900957f69a38e1cad9f0e5563940b2b9f66459fe62d1b946d1b32574adffdeba9d7b640
+  data.tar.gz: 7e1b45715643ab7eede7baea523ef2e7784766d62bf77ec1cad1fcd61fd37988d76667f8b5f4279489fb89a13311c449c4998973f37f3246eab5059dff102f76

data/README.md

@@ -20,8 +20,28 @@ detection (zero customer effort):
   controller exceptions that `rescue_from` swallows (via
   `process_action.action_controller`), and broadcasts `Rails.logger` lines to
   foam as `log.rails` records — the app's own logger chain is never touched.
-- **Sidekiq**: server middleware auto-registers; one `sidekiq.consume <queue>`
-  consumer span per job, failures re-raised identically (retries untouched).
+- **Sidekiq**: client middleware injects W3C `traceparent` into the job hash;
+  server middleware restores parent context and emits one
+  `sidekiq.consume <queue>` consumer span per job; failures re-raised
+  identically (retries untouched).
+- **Outbound HTTP**: `Net::HTTP` shadow spans via `Module#prepend` (composes
+  with Datadog; never injects headers; never captures query strings). The
+  OTLP endpoint host, known vendor SaaS intake hosts (Rollbar, Datadog,
+  New Relic, LaunchDarkly — SPEC §8), and a loaded Datadog tracer's
+  configured agent host (presence-detected) are never shadow-spanned; other
+  local sidecars are deployment config — add them via
+  `ignored_outbound_hosts:` (a `:port` suffix is ignored, and `localhost` /
+  `127.0.0.1` / `::1` cover each other).
+- **Auto metrics**: `http.server.request.duration`, `sidekiq.job.duration`,
+  `errors.total` (no fabrication on clean 4xx).
+- **Gen AI**: `gen_ai` spans for ruby-openai (Faraday), Anthropic/`http` gem,
+  and Faraday/http traffic to known LLM hosts (OpenTelemetry gen_ai semconv).
+  No prompt/response content capture; streaming response bodies are never
+  consumed (usage tokens are read from `application/json` responses only).
+- **DB**: `db.postgres` spans via `sql.active_record` (operation only, no SQL text).
+- **Redis**: `cache.redis` spans via redis-client / Redis::Client prepend.
+- **Queue produce**: Sidekiq client middleware emits `queue.produce` Producer
+  spans and injects W3C traceparent for consume continuity.
 - **Datadog** (SPEC §7.3): foam spans and logs carry `dd.trace_id`/`dd.span_id`
   verbatim from the DD correlation API when a DD trace is active. Foam never
   patches, parents from, or reconfigures the DD tracer.
@@ -38,7 +58,9 @@ detection (zero customer effort):
 | `redact_contact_info:` | `false` | append email/phone/telefono/celular to redaction |
 | `redact_keys:` | `[]` | extra redacted keys |
 | `health_routes:` | `[]` | routes exempted from request-context capture (none by default — health checks are captured) |
-| `sidekiq:` / `rollbar:` / `rails:` | `true` | opt out of auto-wiring that adapter |
+| `sidekiq:` / `rollbar:` / `rails:` / `outbound:` / `gen_ai:` / `db:` / `redis:` | `true` | opt out of auto-wiring that adapter |
+| `auto_metrics:` | `true` | emit request/job duration + errors counters |
+| `ignored_outbound_hosts:` | OTLP host + vendor SaaS intake hosts + detected DD agent host (SPEC §8) | extra hosts skipped by outbound shadow; `:port` stripped, loopback aliases equivalent |
 
 Export is production-gated (`RAILS_ENV`/`RACK_ENV`/`ENVIRONMENT`/`ENV`/
 `NODE_ENV` ∈ {production, prod}) unless `force_export`. Batch cadence comes

data/lib/foam/otel/constants.rb

@@ -57,6 +57,10 @@ module Foam
       LOG_RAILS = "log.rails"
       LOG_CONSOLE = "log.console"
       APP_CUSTOM = "app.custom"
+      METRIC_ERRORS = "metric.errors"
+      GEN_AI = "gen_ai"
+      DB_POSTGRES = "db.postgres"
+      CACHE_REDIS = "cache.redis"
     end
   end
 end

data/lib/foam/otel/db.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+
+module Foam
+  module Otel
+    # PostgreSQL / ActiveRecord client spans via ActiveSupport::Notifications.
+    #
+    # Subscribes to `sql.active_record` when ActiveSupport is present. One
+    # CLIENT span per query, stamped foam.instrumentation=db.postgres with
+    # db.system=postgresql. Skips SCHEMA/CACHE noise and empty SQL.
+    #
+    # Never captures full SQL text (PHI under multi-tenant apps) — only
+    # db.operation (first keyword) and the short AR name ("User Load").
+    # Notification handler failures never raise into the app.
+    module Db
+      NOTIFICATION = "sql.active_record"
+      SKIP_NAME_RE = /\b(SCHEMA|CACHE)\b/i.freeze
+
+      def self.install!
+        return false if @installed
+        return false unless defined?(::ActiveSupport::Notifications)
+
+        @subscriber = ::ActiveSupport::Notifications.subscribe(NOTIFICATION) do |*args|
+          on_notification(*args)
+        rescue StandardError
+          nil
+        end
+        @installed = true
+        true
+      rescue StandardError => e
+        warn "[foam] Db.install! failed: #{e.class}: #{e.message}"
+        false
+      end
+
+      def self.reset_for_tests!
+        if @subscriber && defined?(::ActiveSupport::Notifications)
+          begin
+            ::ActiveSupport::Notifications.unsubscribe(@subscriber)
+          rescue StandardError
+            nil
+          end
+        end
+        @subscriber = nil
+        @installed = false
+      end
+
+      # ActiveSupport yields an Event object only to arity-1 blocks; the splat
+      # block in install! (arity -1) ALWAYS receives the 5 positional args
+      # (name, start, finish, id, payload) — start/finish are Time (or
+      # monotonic floats); subtraction is seconds either way.
+      def self.on_notification(_name, start, finish, _id, payload)
+        return if payload.nil?
+
+        duration_s = start && finish ? (finish - start).to_f : 0.0
+        emit(payload, duration_s)
+      end
+
+      def self.emit(payload, duration_s)
+        name = payload[:name].to_s
+        return if name.match?(SKIP_NAME_RE)
+
+        sql = payload[:sql].to_s
+        return if sql.empty?
+
+        op = sql.lstrip[/\A([A-Za-z]+)/, 1].to_s.upcase
+        return if op.empty?
+
+        attrs = {
+          INSTRUMENTATION_KEY => STAMPS::DB_POSTGRES,
+          "db.system" => "postgresql",
+          "db.operation" => op,
+        }
+        attrs["db.statement.name"] = name unless name.empty?
+        # Do not pass custom start/end timestamps: the OTLP exporter's protobuf
+        # path rejects some nanosecond shapes ("bignum too big"). The span is
+        # created at notification END, so its own start/end are ~zero-width —
+        # the real query duration is preserved as an attribute instead.
+        attrs["db.duration_ms"] = (duration_s.to_f * 1000).round if duration_s.to_f.positive?
+        span = Foam::Otel.tracer("foam-otel/db").start_span(
+          "db #{op.downcase}",
+          kind: :client,
+          attributes: attrs
+        )
+        begin
+          if (ex = payload[:exception_object])
+            Errors.record_once(span, ex)
+          elsif (pair = payload[:exception]).is_a?(Array)
+            span.status = OpenTelemetry::Trace::Status.error(pair[1].to_s)
+            span.add_event(
+              "exception",
+              attributes: {
+                "exception.type" => pair[0].to_s,
+                "exception.message" => pair[1].to_s,
+              }
+            )
+          else
+            span.status = OpenTelemetry::Trace::Status.ok
+          end
+        ensure
+          begin
+            span.finish
+          rescue StandardError
+            nil
+          end
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/foam/otel/errors.rb

@@ -49,6 +49,72 @@ module Foam
       rescue StandardError
         false
       end
+
+      def error_status?(span)
+        span.status&.code == OpenTelemetry::Trace::Status::ERROR
+      rescue StandardError
+        false
+      end
+
+      # --- errors.total dedupe (SPEC §13: one failure, ONE increment) -------
+      # A tracker bridge (Rollbar) fires mid-request, before the Rack/Sidekiq
+      # adapter counts the failure at span end. The bridge marks the span it
+      # counted under; the adapters skip their increment for a marked span.
+      COUNTED_IVAR = :@__foam_otel_error_counted
+
+      def mark_counted!(span)
+        return false unless span.respond_to?(:recording?) && span.recording?
+
+        span.instance_variable_set(COUNTED_IVAR, true)
+        true
+      rescue StandardError
+        false
+      end
+
+      def counted?(span)
+        span.instance_variable_get(COUNTED_IVAR) ? true : false
+      rescue StandardError
+        false
+      end
+
+      # The one client-span lifecycle (SPEC §6/§12), shared by every adapter
+      # that owns a span around a block: attach `context` (defaults to the
+      # span's), run the block, set OK unless an ERROR was recorded or set,
+      # record exceptions through record_once (deduped), RE-RAISE identically,
+      # and always finish the span and detach the context.
+      def with_active_span(span, context: nil)
+        return yield if span.nil?
+
+        ctx = context || OpenTelemetry::Trace.context_with_span(span)
+        token = OpenTelemetry::Context.attach(ctx)
+        begin
+          result = yield
+          begin
+            span.status = OpenTelemetry::Trace::Status.ok unless recorded?(span) || error_status?(span)
+          rescue StandardError
+            nil
+          end
+          result
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          begin
+            record_once(span, e)
+          rescue StandardError
+            nil
+          end
+          raise
+        ensure
+          begin
+            span.finish
+          rescue StandardError
+            nil
+          end
+          begin
+            OpenTelemetry::Context.detach(token)
+          rescue StandardError
+            nil
+          end
+        end
+      end
     end
   end
 end

data/lib/foam/otel/gen_ai.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+require "json"
+require "opentelemetry"
+require "uri"
+
+require_relative "constants"
+require_relative "errors"
+
+module Foam
+  module Otel
+    # Generative-AI client spans (OpenTelemetry gen_ai semantic conventions).
+    #
+    # Why this exists separately from Outbound (Net::HTTP):
+    # - ruby-openai talks over **Faraday** (not Net::HTTP directly).
+    # - AnthropicService (and similar) talk over the **http** gem.
+    # Net::HTTP prepend alone never sees those calls, so LLM traffic was invisible.
+    #
+    # Install path (presence detection at init):
+    # 1. OpenAI::Client (ruby-openai) — method-level: chat/embeddings/completions/responses
+    # 2. Faraday::Connection#run_request — host/path classifier for OpenAI-compatible APIs
+    # 3. HTTP::Client#request — host classifier for Anthropic / other http-gem clients
+    #
+    # Spans:
+    #   name: "chat <model>" | "embeddings <model>" | "gen_ai <provider>"
+    #   kind: client
+    #   foam.instrumentation: gen_ai
+    #   gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model (when known)
+    #   gen_ai.usage.input_tokens / output_tokens when the response body exposes them
+    #   http.status_code when available
+    #
+    # Never captures prompt/response content (PHI / cost). Never injects headers.
+    # Never consumes a streaming response body (usage is only extracted from
+    # application/json responses). Failures record exception + ERROR and
+    # re-raise identically.
+    module GenAi
+      STAMP = STAMPS::GEN_AI
+      PROVIDER_HOSTS = {
+        "api.openai.com" => "openai",
+        "api.anthropic.com" => "anthropic",
+        "api.together.xyz" => "together",
+        "api.fireworks.ai" => "fireworks",
+        "generativelanguage.googleapis.com" => "gemini",
+        "api.deepseek.com" => "deepseek",
+      }.freeze
+
+      # Paths distinctive enough to classify traffic to an UNKNOWN host as
+      # gen_ai (Azure/OpenAI-compatible proxies, local mocks). Bare
+      # "/messages", "/completions", or "/responses" is NOT enough — half the
+      # REST APIs on the internet have those (api.intercom.io/messages,
+      # api.typeform.com/forms/x/responses would become bogus spans); those
+      # forms must be /v1-prefixed the way the LLM APIs actually serve them
+      # (Azure's Responses API is on the v1 surface: /openai/v1/responses).
+      # "/embeddings" stays bare: classic Azure serves
+      # /openai/deployments/<d>/embeddings with no /v1, and bare /embeddings
+      # is rare on non-LLM APIs.
+      DISTINCTIVE_PATH_RE =
+        %r{/(chat/completions|embeddings)(/|\z)|/v1/(messages|completions|responses)(/|\z)}i
+
+      # Context key marking "a foam gen_ai span owns this call". Carried by
+      # the CONTEXT (not just the current span), so suppression survives
+      # intermediate spans another instrumentation may open in between.
+      SUPPRESS_KEY = OpenTelemetry::Context.create_key("foam-otel-gen-ai-owned")
+
+      def self.install!
+        # No top-level latch: each inner installer is idempotent, so a later
+        # init() can wire a client gem that was required after the first init
+        # (a latch here would permanently blind foam to late-loaded gems).
+        ok = false
+        ok |= install_openai!
+        ok |= install_faraday!
+        ok |= install_http_gem!
+        ok
+      rescue StandardError => e
+        warn "[foam] GenAi.install! failed: #{e.class}: #{e.message}"
+        false
+      end
+
+      def self.reset_for_tests!
+        @openai_installed = false
+        @faraday_installed = false
+        @http_installed = false
+      end
+
+      def self.install_openai!
+        return false if @openai_installed
+        return false unless defined?(::OpenAI::Client)
+
+        ::OpenAI::Client.prepend(OpenAIClientPatch)
+        if defined?(::OpenAI::Responses)
+          ::OpenAI::Responses.prepend(OpenAIResponsesPatch)
+        end
+        @openai_installed = true
+        true
+      rescue StandardError
+        false
+      end
+
+      def self.install_faraday!
+        return false if @faraday_installed
+        return false unless defined?(::Faraday::Connection)
+
+        ::Faraday::Connection.prepend(FaradayPatch)
+        @faraday_installed = true
+        true
+      rescue StandardError
+        false
+      end
+
+      def self.install_http_gem!
+        return false if @http_installed
+        return false unless defined?(::HTTP::Client)
+
+        ::HTTP::Client.prepend(HttpGemPatch)
+        @http_installed = true
+        true
+      rescue StandardError
+        false
+      end
+
+      def self.provider_for_host(host)
+        h = host.to_s.downcase
+        return nil if h.empty?
+
+        PROVIDER_HOSTS.each do |suffix, name|
+          return name if h == suffix || h.end_with?(".#{suffix}")
+        end
+        # OpenAI-compatible custom bases often still path like /v1/chat/completions
+        nil
+      end
+
+      def self.operation_for_path(path)
+        p = path.to_s
+        return "chat" if p.include?("/chat/completions") || p.include?("/messages")
+        return "embeddings" if p.include?("/embeddings")
+        return "responses" if p.include?("/responses")
+        return "completions" if p.include?("/completions")
+        return "images" if p.include?("/images")
+
+        "chat"
+      end
+
+      # Query strings carry secrets (Gemini authenticates via ?key=…) — the
+      # http.url attribute is captured without them (SPEC §10).
+      def self.strip_query(url)
+        url.to_s.split("?", 2).first.to_s
+      end
+
+      def self.parse_json_body(body)
+        return body if body.is_a?(Hash)
+        return nil if body.nil?
+
+        s = body.respond_to?(:to_s) ? body.to_s : nil
+        return nil if s.nil? || s.empty?
+
+        JSON.parse(s)
+      rescue StandardError
+        nil
+      end
+
+      def self.extract_usage!(span, body_hash)
+        return unless body_hash.is_a?(Hash)
+
+        usage = body_hash["usage"] || body_hash[:usage]
+        return unless usage.is_a?(Hash)
+
+        in_t = usage["prompt_tokens"] || usage["input_tokens"] || usage[:prompt_tokens] || usage[:input_tokens]
+        out_t = usage["completion_tokens"] || usage["output_tokens"] || usage[:completion_tokens] || usage[:output_tokens]
+        span.set_attribute("gen_ai.usage.input_tokens", in_t.to_i) if in_t
+        span.set_attribute("gen_ai.usage.output_tokens", out_t.to_i) if out_t
+      rescue StandardError
+        nil
+      end
+
+      # Records status code (+ERROR on 5xx) and usage tokens on the span.
+      # `body` must already be safe to read (a Hash or a fully-buffered
+      # String) — callers decide whether reading is safe, this never does.
+      def self.apply_response!(span, code, body)
+        if code
+          span.set_attribute("http.status_code", code.to_i)
+          span.status = OpenTelemetry::Trace::Status.error("") if code.to_i >= 500
+        end
+        extract_usage!(span, parse_json_body(body))
+      rescue StandardError
+        nil
+      end
+
+      def self.inside_gen_ai_span?
+        OpenTelemetry::Context.current.value(SUPPRESS_KEY) ? true : false
+      rescue StandardError
+        false
+      end
+
+      def self.start_span(name:, provider:, operation:, model: nil, extra: nil)
+        attrs = {
+          INSTRUMENTATION_KEY => STAMP,
+          "gen_ai.operation.name" => operation.to_s,
+          "gen_ai.provider.name" => provider.to_s,
+        }
+        attrs["gen_ai.request.model"] = model.to_s if model && !model.to_s.empty?
+        extra&.each { |k, v| attrs[k] = v unless v.nil? }
+
+        Foam::Otel.tracer("foam-otel/gen_ai").start_span(
+          name,
+          kind: :client,
+          attributes: attrs
+        )
+      rescue StandardError
+        nil
+      end
+
+      def self.with_span(span)
+        return yield if span.nil?
+
+        ctx = OpenTelemetry::Trace.context_with_span(span).set_value(SUPPRESS_KEY, true)
+        Errors.with_active_span(span, context: ctx) { yield }
+      end
+
+      # ---- OpenAI gem (ruby-openai) -----------------------------------------
+
+      module OpenAIClientPatch
+        %w[chat embeddings completions].each do |operation|
+          define_method(operation) do |parameters: {}|
+            model = parameters[:model] || parameters["model"]
+            span = GenAi.start_span(
+              name: "#{operation} #{model || "openai"}",
+              provider: openai_provider_name,
+              operation: operation,
+              model: model
+            )
+            GenAi.with_span(span) do
+              resp = super(parameters: parameters)
+              GenAi.extract_usage!(span, resp.is_a?(Hash) ? resp : nil) if span
+              resp
+            end
+          end
+        end
+
+        private
+
+        def openai_provider_name
+          base = begin
+            @uri_base.to_s
+          rescue StandardError
+            ""
+          end
+          host = begin
+            URI.parse(base).host
+          rescue StandardError
+            nil
+          end
+          provider = GenAi.provider_for_host(host)
+          return provider if provider
+
+          # Custom uri_base (proxy, alt region): fall back to matching the
+          # distinctive second-level label of each known host, derived from
+          # PROVIDER_HOSTS so a new provider needs exactly one table entry.
+          GenAi::PROVIDER_HOSTS.each do |host_key, name|
+            label = host_key.split(".")[-2].to_s
+            return name if !label.empty? && base.include?(label)
+          end
+          "openai"
+        end
+      end
+
+      module OpenAIResponsesPatch
+        def create(parameters: {})
+          model = parameters[:model] || parameters["model"]
+          provider = begin
+            client = instance_variable_get(:@client)
+            if client.respond_to?(:uri_base, true) || client.instance_variable_defined?(:@uri_base)
+              base = client.instance_variable_get(:@uri_base).to_s
+              host = URI.parse(base).host rescue nil
+              GenAi.provider_for_host(host) || "openai"
+            else
+              "openai"
+            end
+          rescue StandardError
+            "openai"
+          end
+          span = GenAi.start_span(
+            name: "responses #{model || provider}",
+            provider: provider,
+            operation: "responses",
+            model: model
+          )
+          GenAi.with_span(span) do
+            resp = super
+            GenAi.extract_usage!(span, resp.is_a?(Hash) ? resp : nil) if span
+            resp
+          end
+        end
+      end
+
+      # ---- Faraday (OpenAI-compatible HTTP) ---------------------------------
+
+      module FaradayPatch
+        def run_request(method, url, body, headers, &block)
+          abs = begin
+            build_exclusive_url(url).to_s
+          rescue StandardError
+            url.to_s
+          end
+          uri = begin
+            URI.parse(abs)
+          rescue StandardError
+            nil
+          end
+          host = uri&.host
+          path = uri&.path.to_s
+          provider = GenAi.provider_for_host(host)
+          # Also treat distinctive gen_ai paths on unknown hosts
+          # (Azure/OpenAI-compatible proxies, conformance mocks).
+          gen_path = path.match?(GenAi::DISTINCTIVE_PATH_RE)
+          return super if provider.nil? && !gen_path
+          # OpenAI::Client (or other method-level) patch already owns the gen_ai span.
+          return super if GenAi.inside_gen_ai_span?
+
+          provider ||= (path.include?("/messages") ? "anthropic" : "openai")
+          operation = GenAi.operation_for_path(path)
+          model = nil
+          begin
+            parsed = GenAi.parse_json_body(body)
+            model = parsed["model"] || parsed[:model] if parsed
+          rescue StandardError
+            nil
+          end
+          # body may be set in the block — model often only there; still span without model
+          span = GenAi.start_span(
+            name: "#{operation} #{model || provider}",
+            provider: provider,
+            operation: operation,
+            model: model,
+            extra: {
+              "http.method" => method.to_s.upcase,
+              "http.url" => GenAi.strip_query(abs),
+            }
+          )
+          return super if span.nil?
+
+          GenAi.with_span(span) do
+            resp = super
+            begin
+              # Faraday adapters buffer resp.body (a String, or a Hash when
+              # the json middleware ran) unless the caller streams via
+              # on_data — in which case body is nil/empty and this reads
+              # nothing.
+              code = resp.respond_to?(:status) ? resp.status.to_i : nil
+              GenAi.apply_response!(span, code, resp.respond_to?(:body) ? resp.body : nil)
+            rescue StandardError
+              nil
+            end
+            resp
+          end
+        end
+      end
+
+      # ---- http gem (AnthropicService etc.) ---------------------------------
+
+      module HttpGemPatch
+        def request(verb, uri, opts = {})
+          url = uri.to_s
+          parsed = begin
+            URI.parse(url)
+          rescue StandardError
+            nil
+          end
+          host = parsed&.host
+          path = parsed&.path.to_s
+          provider = GenAi.provider_for_host(host)
+          gen_path = path.match?(GenAi::DISTINCTIVE_PATH_RE)
+          return super if provider.nil? && !gen_path
+          return super if GenAi.inside_gen_ai_span?
+
+          # Path-based provider when host is a mock/proxy (127.0.0.1, localhost, …)
+          provider ||= (path.include?("/messages") ? "anthropic" : "openai")
+          operation = GenAi.operation_for_path(path)
+          model = nil
+          begin
+            json_body = opts[:json] || opts["json"]
+            if json_body.is_a?(Hash)
+              model = json_body[:model] || json_body["model"]
+            elsif opts[:body]
+              parsed_body = GenAi.parse_json_body(opts[:body])
+              model = parsed_body["model"] if parsed_body
+            end
+          rescue StandardError
+            nil
+          end
+          span = GenAi.start_span(
+            name: "#{operation} #{model || provider}",
+            provider: provider,
+            operation: operation,
+            model: model,
+            extra: {
+              "http.method" => verb.to_s.upcase,
+              "http.url" => GenAi.strip_query(url),
+            }
+          )
+          return super if span.nil?
+
+          GenAi.with_span(span) do
+            resp = super
+            begin
+              code = if resp.respond_to?(:status)
+                       s = resp.status
+                       s.respond_to?(:code) ? s.code.to_i : s.to_i
+                     end
+              # The http gem's response body is a lazy stream: reading it here
+              # would consume it (Body#to_s buffers and poisons a later
+              # body.each with StateError). Only JSON responses — which the
+              # caller will buffer anyway, and Body#to_s caches — are read for
+              # usage; SSE/streaming responses are never touched.
+              body = nil
+              if resp.respond_to?(:mime_type) && resp.mime_type.to_s.include?("json")
+                body = resp.body if resp.respond_to?(:body)
+              end
+              GenAi.apply_response!(span, code, body)
+            rescue StandardError
+              nil
+            end
+            resp
+          end
+        end
+      end
+    end
+  end
+end