foam-otel 1.8.1 → 1.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ef766d3509a7ee5daa25c7f53dce352b9c67c8ed22283099c72f3d6f0b8e957
-  data.tar.gz: caca5adca96f4e3dab3d0610ce54000858cb231cbf167e5bb6dd0c6f1dcd6a9b
+  metadata.gz: a2e506ae900650923638df263e5775efa20dd8ab7a63540eefb9d5156c1d008c
+  data.tar.gz: 64ea4091c85c9541ec1f08dd5560608e560ec80e8ee6918f95098b976b0ec82e
 SHA512:
-  metadata.gz: 55da8fd55a07d287d81fddf5a65eeb8b7e0f743d1ec8b034362972f5c02a15a84bab18119aacf9e881b4deefc61d6958e062990fe3b205f66f2a88fd11ba514b
-  data.tar.gz: 70e46934c6250308cb8d15c90a160eeab5ce916b294cfc7395e46fc07e0d8d2027ded17f3f21cdcf3125c35773fb899324eb0374c6326c04d73a2908e0e1024d
+  metadata.gz: 4c776696c10dc442394e5b023db7b47d178ec4b328addd693ba72b60e726c19f923533f0f1645e7b62ec322e63d6fcd0b39b1ca917cd9aa66403295c0b67e266
+  data.tar.gz: 615ec0ee4400e6e11baa6a6572fcafdccdeb6764f9bb2e65afcf4ff72a8185e9ba45086cd5e8e039934ea1043fe165d94784983539ac0d3e361a6b28f72a986e

data/GOTCHAS.md

@@ -866,6 +866,132 @@ exfiltratable — the value-pattern secret layer is the required second control
   "REAL OTLP encode", "aggregates hook faults", "arity", "in-place value
   mutation never bleeds"); `spec/before_send_champ_scenario_spec.rb` (the
   export-thread / stamped-context proof).
+## F17: There is no unwrapped Net::HTTP instance — foam's export must own its transport (export isolation, 2026-07-29)
+
+- **Trap**: Ruby APM agents instrument by PREPENDING modules onto `Net::HTTP`
+  itself, so every instance in the process — including the one inside the
+  upstream OTLP exporter — dispatches through the foreign prepend chain, and
+  private helper names from different vendors resolve against each other on
+  the shared ancestry (the wrong-arity `annotate_span_with_response!`
+  collision class: every export crashes, zero rows land, the app looks
+  healthy). The upstream exporter's `untraced` suppression does NOT protect
+  the send — foreign agents never check OTel's flag; the exporter died with
+  it active. Reproduced at production parity against a real proprietary
+  auto-instrumenting agent (docs/decisions/export-isolation-ruby.md, with
+  before/after crash and rows-landed counts).
+- **Sources**:
+  - Installed source — the vulnerable transport: `Net::HTTP.new` inside
+    `http_connection` and the `Net::HTTPResponse`-matching send loop
+    (opentelemetry-exporter-otlp `exporter.rb:129,150-258`; same shape in
+    -otlp-logs `logs_exporter.rb` and -otlp-metrics `metrics_exporter.rb` —
+    with drifting private `backoff?` signatures across the three gems).
+  - Design reference (strongest industry mechanism, isolation by
+    construction): the Go OTLP exporter's owned internal transport and its
+    documented warning against injecting an instrumented transport; the
+    error-tracking vendors' native-fetch browser transports.
+  - The prior collision incident class: the upstream contrib `net_http`
+    patch's private helper namespace
+    (opentelemetry-instrumentation-net_http `patches/stable/instrumentation.rb:81`).
+- **Decision & why**: Isolation by construction, layered over suppression —
+  never suppression alone. `Foam::Otel::IsolatedHttpClient` is a hand-written
+  HTTP/1.1 sender over foam-owned `TCPSocket`/`OpenSSL::SSL::SSLSocket`
+  (VERIFY_PEER + hostname verification, CA/mTLS options, HTTP(S)_PROXY /
+  NO_PROXY with CONNECT tunneling, deadline IO, keep-alive with one
+  stale-socket retransmit, chunked/`Connection: close` reading, pid-keyed
+  reconnect for fork safety). `IsolatedExporters::{Trace,Logs,Metrics}Exporter`
+  subclass the upstream exporters, replacing exactly `http_connection` and
+  `send_bytes` (foam-owned retry loop, upstream semantics verbatim: 429/503
+  honor Retry-After, 408/502/504 + transient socket errors back off with
+  jitter, other 4xx drop; `untraced` kept as layer two). All six construction
+  sites (door 1 + door 2 × three signals) — the package's entire outbound
+  surface — build these subclasses. Capture is untouched; and foam's own
+  prepends (LLM shims, Logger bridge, fork hook) define ONLY the intercepted
+  public method, so foam can never be the colliding party on anyone's class.
+- **Mitigation**: a foreign prepend chain on `Net::HTTP` structurally cannot
+  sit in foam's delivery path; a hostile wrong-arity prepend that crashes
+  every ordinary `Net::HTTP` caller leaves foam's rows landing.
+- **Test**: `spec/export_isolation_spec.rb` (hostile prepend in a forked
+  child + spy-prepend never-dispatches proof, 503/429 Retry-After retries,
+  CONNECT-tunnel and absolute-form proxy paths, NO_PROXY, TLS wrong-hostname
+  rejection, chunked/keep-alive/stale-socket/deadline/fork-safety units, the
+  untraced layer-two pin, and the zero-collidable-private-helpers invariant);
+  `spec/export_isolation_hardening_spec.rb` (protocol edges: 1xx skip,
+  duplicate/trailered/extension-chunked responses, EOF-framed bodies,
+  keep-alive expiry, malformed status lines, IPv6 Host framing, 8-thread
+  concurrency; retry accounting with the backoff clock stubbed: exact
+  retry-cap exhaustion, Retry-After delta AND HTTP-date, 408/502/504,
+  redirects never followed, zero/mid-loop budget exhaustion; compression
+  none + its env var; loud non-protobuf 5xx handling; shutdown lifecycle;
+  mTLS e2e via the spec CERTIFICATE/CLIENT_CERTIFICATE/CLIENT_KEY env vars
+  incl. the rejected no-client-cert half; proxy credentials on CONNECT,
+  refused CONNECT, lowercase env twins, the NO_PROXY shape matrix; all
+  three signals through a full init, door-2 tap e2e, and a REAL fork);
+  `spec/ingest_spec.rb` (case 4 half 3: zero feedback spans with BOTH
+  cooperative layers defeated); `spec/transport_spec.rb` (the exact isolated
+  classes on all six sites); and the REAL-agent coexistence gate
+  `test-apps/ruby-coexistence/run-verify.sh` (two postures booting the
+  actual commercial agents in auto-instrument mode, hard-gated on the
+  vendor module being observed live ahead of Net::HTTP in the running
+  process's ancestor chain, verdict = protobuf-decoded rows on all three
+  signals with zero export errors).
+
+---
+
+## F18: One private-method namespace per class — cross-vendor helper collisions crash the APP, and foam shields them (coexistence mandate 2026-07-29)
+
+- **Trap**: Every module prepended onto a class shares ONE private-method
+  namespace. When two observability vendors prepend same-named private
+  helpers at different signatures onto Net::HTTP, method lookup hands EVERY
+  caller the frontmost definition — one vendor's wrapper invokes the other
+  vendor's helper and raises ArgumentError on EVERY Net::HTTP request the
+  app makes. This is live in the wild today: a proprietary agent's wrapper
+  and the upstream OTel contrib net_http patch both define
+  `annotate_span_with_response!` (3-arg vs 2-arg). Foam ships that contrib
+  patch for capture, so a foam + agent process CONTAINS the collision — and
+  foam's promise is coexistence: the app must keep working.
+- **Sources**:
+  - Installed source — the two colliding definitions:
+    opentelemetry-instrumentation-net_http 0.29.0
+    `patches/stable/instrumentation.rb:81` (`annotate_span_with_response!(span, response)`)
+    and the proprietary agent's contrib HTTP instrumentation calling its own
+    3-arg spelling of the same private name (verified live in the
+    coexistence gate; backtrace pinned in
+    docs/decisions/export-isolation-ruby.md §A).
+  - Ruby semantics: prepended modules join the class's ancestor chain and
+    private methods resolve through the SAME chain for every caller — there
+    is no per-module helper namespace.
+- **Decision & why**: foam cannot rename the upstream helper (its own caller
+  resolves the name through the same shared chain — a rename breaks the
+  gem being "fixed"), and foam must never edit another vendor's module. So
+  foam owns the collision instead: after the instrumentation sweep, init
+  scans Net::HTTP's prepend chain for private-helper names defined by two
+  or more foreign modules at NON-identical positional signatures (names the
+  class itself defines are super-chains, never shielded) and prepends ONE
+  frontmost dispatch method per colliding name — routing by caller source
+  gem first, then by signature fit, falling back to the previously-frontmost
+  definition (status quo ante; the shield never makes a broken chain
+  worse). Its dispatch methods accept (*args, **kwargs, &block), so nothing
+  can arity-crash against the shield itself. No collision → NOTHING is
+  installed. Every shielded name is announced loudly (rule 15). This is the
+  ONE deliberate exception to foam's own-prepend hygiene rule (F17's
+  "foam's prepends carry zero private helpers"): the shield's whole job is
+  to own the already-colliding names.
+- **Mitigation**: with the shield installed the coexistence gate's
+  patched-client probe went from 3/3 crashes to 3/3 passes under the real
+  agent, with both vendors' helpers verifiably executing again.
+- **Residual**: an agent that patches AFTER foam's init lands ahead of the
+  shield and re-exposes the raw collision until a later init/fork re-scan;
+  agents overwhelmingly boot first (initializer/preload) — the order the
+  coexistence gate proves. Identical-signature collisions are left alone
+  (no crash class; dispatch could not disambiguate semantics).
+- **Test**: `spec/prepend_collision_shield_spec.rb` (the unshielded RED
+  control, both-vendors-work dispatch, idempotence, no-op purity on
+  collision-free chains, super-chain and identical-signature exclusions,
+  fall-through to the real error, rule-9 scan degradation, caller-source
+  dispatch across two on-disk gem roots, and the real Net::HTTP + real
+  contrib patch field scenario red→green in a forked child);
+  `test-apps/ruby-coexistence/run-verify.sh` (the patched-client probe is a
+  REQUIRED pass on every vendor posture).
 
 ---
 

data/README.md

@@ -672,6 +672,11 @@ The per-record contract (Sentry `beforeSend` semantics):
   in place, they are shared structures. Foam re-normalizes the record's
   `total_recorded_*` bookkeeping after your hooks run, so adding/deleting
   attributes never corrupts the wire's dropped-count accounting.
+  `record.resource` and `record.instrumentation_scope` are **identity, not
+  payload**: read them freely, but edits and replacements are discarded —
+  the original identity objects always ship (they are process-global and
+  the encoder groups by them; a writable resource would also bypass
+  redaction, which never masks resource attributes).
 * **return `nil`** → the record is dropped, silently (that is the filter
   mechanism, not an error).
 * **raise, or return a foreign object** → that record is dropped

data/lib/foam/otel/before_send.rb

@@ -62,6 +62,7 @@ module Foam
       # flood an adversary-shaped record stream controls — rule 15's
       # "loud but never a flood" posture).
       def run(hooks, record, signal, faults)
+        identity = identity_of(record)
         current, counters = thaw(record)
         hooks.each do |hook|
           result = hook.call(current)
@@ -74,6 +75,7 @@ module Foam
           current = result
         end
         restore_counters!(current, counters)
+        restore_identity!(current, identity)
         current
       rescue StandardError, SystemStackError => e
         faults << e.class.name
@@ -110,9 +112,43 @@ module Foam
           copy.attributes = attributes.nil? ? {} : attributes.transform_values { |v| thaw_value(v) }
         end
         copy.body = thaw_body(copy.body) if copy.respond_to?(:body) && copy.respond_to?(:body=)
+        # The scope handed to the hook is a COPY: InstrumentationScope is a
+        # mutable Struct, and an in-place `scope.name =` on the shared
+        # object would corrupt process-global identity (see identity_of).
+        if copy.respond_to?(:instrumentation_scope) && copy.respond_to?(:instrumentation_scope=)
+          copy.instrumentation_scope = copy.instrumentation_scope&.dup
+        end
         [copy, sdk_drop_counters(record)]
       end
 
+      # resource / instrumentation_scope are process-global IDENTITY objects
+      # shared by every record the tracer/logger emits — and Ruby's
+      # InstrumentationScope is a plain MUTABLE Struct. A hook that renames
+      # the scope would corrupt the identity of EVERY subsequent span/log
+      # from that instrument (proven live in the 2026-07-29 retro-probe),
+      # and a wholesale `record.resource =` replacement would ship
+      # hook-authored resource attributes RAW — redaction never masks
+      # resource, so that path could widen what ships. Both are closed the
+      # way the Go port does it: identity always comes from the ORIGINAL
+      # record — captured here, force-restored onto the survivor after the
+      # pipeline (hook edits to identity are discarded; the encoder's
+      # group-by-identity stays intact). Documented in the README:
+      # resource/instrumentation_scope are informational, not hook-writable.
+      def identity_of(record)
+        {
+          resource: (record.resource if record.respond_to?(:resource)),
+          scope: (record.instrumentation_scope if record.respond_to?(:instrumentation_scope)),
+        }
+      end
+
+      def restore_identity!(record, identity)
+        record.resource = identity[:resource] if record.respond_to?(:resource=)
+        if record.respond_to?(:instrumentation_scope=)
+          record.instrumentation_scope = identity[:scope]
+        end
+        record
+      end
+
       def thaw_value(value)
         case value
         when String then value.dup

data/lib/foam/otel/ingest.rb

@@ -285,23 +285,25 @@ module Foam
         # CWE-295 — see pipelines.rb setup_traces): door 2 carries the same
         # fleet ingest token over the same TLS connection, so the silent
         # OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE downgrade is pinned out
-        # here identically.
+        # here identically. All three are IsolatedExporters subclasses —
+        # door 2's delivery must be exactly as immune to foreign Net::HTTP
+        # prepends as door 1's (export-isolation design, 2026-07-29).
         def build_otlp_span_exporter(endpoint, headers)
-          OpenTelemetry::Exporter::OTLP::Exporter.new(
+          IsolatedExporters::TraceExporter.new(
             endpoint: "#{endpoint}/v1/traces", headers: headers,
             ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
           )
         end
 
         def build_otlp_log_exporter(endpoint, headers)
-          OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+          IsolatedExporters::LogsExporter.new(
             endpoint: "#{endpoint}/v1/logs", headers: headers,
             ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
           )
         end
 
         def build_otlp_metric_exporter(endpoint, headers)
-          OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+          IsolatedExporters::MetricsExporter.new(
             endpoint: "#{endpoint}/v1/metrics", headers: headers,
             ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
           )

data/lib/foam/otel/init.rb

@@ -528,6 +528,10 @@ module Foam
         require "opentelemetry-exporter-otlp"
         require "opentelemetry-exporter-otlp-logs"
         require "opentelemetry-exporter-otlp-metrics"
+        # The isolated transport subclasses (export-isolation design) load
+        # HERE — after the upstream exporter gems they subclass — so the lazy
+        # rule-41 posture holds: a disabled boot never pays their cost.
+        require_relative "isolated_exporters"
       end
 
       # The central RAW-capture activation config (raised-floor ruling
@@ -610,6 +614,12 @@ module Foam
           FLOOR_INSTRUMENTATION_CONFIG.merge(SUPERSEDED_INSTRUMENTATION_CONFIG)
         )
         Diagnostics.info("instrumentations installed: #{gems.length} bundled gem(s)")
+        # Coexistence shield (2026-07-29, GOTCHAS F18): with the sweep done,
+        # every prepend that will sit on Net::HTTP in the realistic boot
+        # order (agent first, foam second) is in place — scan for cross-
+        # vendor private-helper collisions and shim them. A collision-free
+        # chain (the common case) installs NOTHING.
+        PrependCollisionShield.install!(::Net::HTTP) if defined?(::Net::HTTP)
       rescue StandardError => e
         Diagnostics.warn("instrumentation activation failed: #{e.class}: #{e.message}")
       end

data/lib/foam/otel/isolated_exporters.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+# The isolated OTLP exporters (export-isolation design, 2026-07-29). The
+# upstream opentelemetry-exporter-otlp{,-logs,-metrics} gems each build a
+# Net::HTTP inside #http_connection and drive it from #send_bytes — which puts
+# every foreign APM's Net::HTTP prepend chain (Datadog, New Relic, Sentry…)
+# INSIDE foam's delivery path. These subclasses keep everything else the
+# upstream classes do — endpoint/headers/compression/timeout resolution
+# including the spec OTEL_EXPORTER_OTLP_* env vars, protobuf encoding, the
+# ssl/mTLS options — and replace exactly two private methods:
+#
+#   * #http_connection → returns Foam::Otel::IsolatedHttpClient (an owned,
+#     hand-written HTTP/1.1 sender; see isolated_http_client.rb);
+#   * #send_bytes → a foam-owned send loop that reimplements the upstream
+#     retry semantics VERBATIM (backoff with jitter on 429/503 honoring
+#     Retry-After, backoff on 408/502/504 and transient socket/SSL errors,
+#     drop on other 4xx/5xx) against the isolated client. Reimplemented, not
+#     inherited, because the upstream loop pattern-matches Net::HTTPResponse
+#     classes and rescues Net::* exceptions — and because its private helper
+#     signatures drift across the three gems (logs' backoff? has no reason:).
+#
+# Suppression stays as LAYER TWO: the send runs inside
+# Common::Utilities.untraced, so cooperative instrumentation (foam's own
+# included) never traces foam's export even if a future capture hook could
+# see it. Layer one — the reason the Datadog crash cannot recur — is that the
+# bytes never enter Net::HTTP at all.
+require "zlib"
+
+require_relative "diagnostics"
+require_relative "isolated_http_client"
+
+module Foam
+  module Otel
+    module IsolatedExporters
+      # Export result codes; == OpenTelemetry::SDK::*::Export::SUCCESS/FAILURE
+      # in every signal's SDK (integers, so this module never reaches into the
+      # per-signal constant trees).
+      SUCCESS = 0
+      FAILURE = 1
+      RETRY_COUNT = 5 # upstream's cap, kept verbatim
+
+      # The shared send path, included by the three per-signal subclasses
+      # below. Relies only on ivars every upstream constructor sets (@http,
+      # @path, @headers, @timeout, @compression, @uri) plus the optional
+      # @metrics_reporter (absent in the logs exporter — every use is nil-safe).
+      module SendPath
+        private
+
+        def http_connection(uri, ssl_verify_mode, certificate_file, client_certificate_file, client_key_file)
+          IsolatedHttpClient.new(
+            uri,
+            ssl_verify_mode: ssl_verify_mode,
+            certificate_file: certificate_file,
+            client_certificate_file: client_certificate_file,
+            client_key_file: client_key_file
+          )
+        end
+
+        def send_bytes(bytes, timeout:) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          return FAILURE if bytes.nil?
+
+          report_value("otel.otlp_exporter.message.uncompressed_size", bytes.bytesize)
+          if @compression == "gzip"
+            body = Zlib.gzip(bytes)
+            report_value("otel.otlp_exporter.message.compressed_size", body.bytesize)
+          else
+            body = bytes
+          end
+          request_headers = @headers.merge("Content-Type" => "application/x-protobuf")
+          request_headers["Content-Encoding"] = "gzip" if @compression == "gzip"
+
+          retry_count = 0
+          timeout ||= @timeout
+          start_time = OpenTelemetry::Common::Utilities.timeout_timestamp
+
+          # Layer two: the cooperative suppression flag, kept even though the
+          # isolated client makes it structurally unnecessary for delivery —
+          # it also stops foam ever tracing its own export.
+          OpenTelemetry::Common::Utilities.untraced do
+            loop do
+              remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+              return FAILURE if remaining_timeout.zero?
+
+              response = @http.post(@path, body: body, headers: request_headers, timeout: remaining_timeout)
+
+              case response.code
+              when 200..299
+                return SUCCESS
+              when 429, 503
+                next if foam_backoff?(retry_after: response["retry-after"],
+                                      retry_count: retry_count += 1, reason: response.code.to_s)
+
+                # Retry exhaustion is announced (fleet-review parity fix:
+                # upstream's per-retry handle_http_error kept failures
+                # visible; foam announces once, at the point data drops).
+                foam_log_request_failure(response.code)
+                return FAILURE
+              when 408, 502, 504
+                next if foam_backoff?(retry_count: retry_count += 1, reason: response.code.to_s)
+
+                foam_log_request_failure(response.code)
+                return FAILURE
+              when 404
+                foam_log_request_failure(response.code)
+                return FAILURE
+              when 300..399
+                # Upstream parity: redirects are not followed (its
+                # handle_redirect is a TODO); drop the connection and back off.
+                @http.finish
+                next if foam_backoff?(retry_after: 0, retry_count: retry_count += 1,
+                                      reason: response.code.to_s)
+
+                return FAILURE
+              when 400..599
+                foam_log_status(response.body)
+                add_to_failure_counter(response.code.to_s)
+                return FAILURE
+              else
+                @http.finish
+                foam_log_request_failure(response.code)
+                return FAILURE
+              end
+            rescue IsolatedHttpClient::TimeoutError
+              # Deliberate divergence from upstream (documented): upstream
+              # lets Net::WriteTimeout fall to the fatal catch-all while
+              # retrying read timeouts; a stalled WRITE is just as transient
+              # (proxy hiccup, slow-start collector), so foam retries both
+              # within the same budget/backoff caps.
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "timeout")
+
+              return FAILURE
+            rescue OpenSSL::SSL::SSLError => e
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "openssl_error")
+
+              OpenTelemetry.handle_error(exception: e, message: "SSL error in isolated OTLP send_bytes")
+              return FAILURE
+            rescue SocketError, IsolatedHttpClient::ProxyConnectError
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "socket_error")
+
+              return FAILURE
+            rescue SystemCallError => e
+              next if foam_backoff?(retry_count: retry_count += 1, reason: e.class.name)
+
+              return FAILURE
+            rescue EOFError
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "eof_error")
+
+              return FAILURE
+            rescue Zlib::DataError
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "zlib_error")
+
+              return FAILURE
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e, message: "unexpected error in isolated OTLP send_bytes")
+              add_to_failure_counter(e.class.to_s)
+              return FAILURE
+            end
+          end
+        end
+
+        # Upstream backoff semantics verbatim (red-flag 2): count the failure,
+        # give up past RETRY_COUNT, honor Retry-After as delta-seconds or
+        # HTTP-date, else exponential jitter — foam-prefixed (rule: foam is
+        # never the colliding party on anyone's class, its own included).
+        def foam_backoff?(retry_count:, reason:, retry_after: nil)
+          add_to_failure_counter(reason)
+          return false if retry_count > RETRY_COUNT
+
+          sleep_interval = nil
+          unless retry_after.nil?
+            sleep_interval = Integer(retry_after, exception: false)
+            sleep_interval ||=
+              begin
+                Time.httpdate(retry_after) - Time.now
+              rescue StandardError
+                nil
+              end
+            sleep_interval = nil unless sleep_interval&.positive?
+          end
+          sleep_interval ||= rand(2**retry_count)
+
+          sleep(sleep_interval)
+          true
+        end
+
+        def foam_log_status(body)
+          status = Google::Rpc::Status.decode(body.to_s)
+          details = status.details.filter_map do |detail|
+            klass = ::Google::Protobuf::DescriptorPool.generated_pool.lookup(detail.type_name).msgclass
+            detail.unpack(klass) if klass
+          end
+          OpenTelemetry.handle_error(
+            message: "OTLP exporter received rpc.Status{message=#{status.message}, details=#{details}} for uri=#{@uri}"
+          )
+        rescue StandardError
+          # A body that isn't a valid rpc.Status (HTML error page from a
+          # proxy, empty 500…) still gets a readable failure line.
+          OpenTelemetry.handle_error(message: "OTLP exporter received an error response for uri=#{@uri}")
+        end
+
+        def foam_log_request_failure(response_code)
+          OpenTelemetry.handle_error(
+            message: "OTLP exporter received http.code=#{response_code} for uri='#{@uri}' in isolated send_bytes"
+          )
+          add_to_failure_counter(response_code.to_s)
+        end
+
+        def add_to_failure_counter(reason)
+          @metrics_reporter&.add_to_counter("otel.otlp_exporter.failure", labels: { "reason" => reason })
+        rescue StandardError
+          nil
+        end
+
+        def report_value(metric, value)
+          @metrics_reporter&.record_value(metric, value: value)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # The three per-signal exporters. Constructors, protobuf encoding,
+      # spec env-var handling, force_flush/shutdown all inherit from upstream;
+      # only the transport-touching privates are replaced by SendPath (module
+      # ancestry: subclass → SendPath → upstream class, so the upstream
+      # constructor's http_connection call dispatches into SendPath's).
+      class TraceExporter < ::OpenTelemetry::Exporter::OTLP::Exporter
+        include SendPath
+      end
+
+      class LogsExporter < ::OpenTelemetry::Exporter::OTLP::Logs::LogsExporter
+        include SendPath
+      end
+
+      class MetricsExporter < ::OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter
+        include SendPath
+      end
+    end
+  end
+end