foam-otel 3.0.0.alpha.5 → 3.0.0.alpha.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34ec502fdc38ac38099bba65f1fc37c91f1edb79476bff598c6a0dda7245fcf0
-  data.tar.gz: 9596d8c1d746b66103b87587f5c52006e024d0498d93816912ed916014e563e4
+  metadata.gz: 4458e9959661525a33f70692beaeba2f32df91a68b01b7e611ec2ae2e2901b39
+  data.tar.gz: bb9127c1d897dec9f1a8268a338382fa1ffdfe772918abdf920d413ff10b986e
 SHA512:
-  metadata.gz: 85207e2233f8a986bb874f68215960f20216e010978e5d1355808ec2ed6bfb44f19c9b8f8947cc3164cca65864326dab8b5ef95fb8ef6c37a1150fe06923ae2a
-  data.tar.gz: 3a3bc463b06b32e1d1bd4b6c439e5f8a92b031859301f8681e78a32e4e1db655ef73d4439a0755e336abc9fc1b068bca48049172046732da4adb514eb12c00cb
+  metadata.gz: d10e3d644eee2036278ae2c5310fc1afd33ec9acda7b27189247a0cb1dd88e1ebc433538cca528567278f97fa9103319a2e573d97f2ca201e24338b50f1c2764
+  data.tar.gz: 96eefe317fbf6eb8906e30242618fe69d90d303f0b3d2e74ceb008c968adc94884a39279b0a887e8e1ab7e5c1b4595dfd8aaf6e31eaeca123b451a002438f52f

data/README.md

@@ -134,6 +134,7 @@ Foam.init(
   disable_log_sending: false,
   network_capture: :basic,
   ignored_outbound_hosts: [],
+  ignored_outbound_headers: [],
   redact: nil,
   before_send: nil
 )
@@ -150,7 +151,8 @@ Foam.init(
 - `additional_span_processors`, `additional_log_record_processors`, `additional_metric_readers` - the app's own OpenTelemetry components, added to Foam's providers after Foam's own exporters.
 - `additional_resource_attributes` - attributes merged into the resource of every signal. `service.name`, `service.version`, and `deployment.environment.name` come from the options above and `service.instance.id` from Foam; a value for one of them here is reported on stderr and ignored.
 - `additional_instrumentations` - instrumentations to install next to the bundle. An entry is an instrumentation's registry name, which is its class name without the trailing `::Instrumentation` (`"OpenTelemetry::Instrumentation::Logger"`), or a `[name, config]` pair to install it with options (`["OpenTelemetry::Instrumentation::PG", {db_statement: :include}]`). Require the instrumentation's gem before `init`; an entry whose instrumentation is not loaded fails `init`. An entry naming a bundled instrumentation replaces Foam's configuration for it.
-- `ignored_outbound_hosts` - skips tracing of outbound HTTP requests to these hostnames. The endpoint host is always skipped. Use it for hosts whose traffic would drown the traces, such as a sidecar health check on `localhost` or another vendor's OTLP ingest host. Hosts are compared as written; `localhost` and `127.0.0.1` are different hosts. A request to a skipped host still carries a `traceparent` marked not sampled, so an OpenTelemetry service behind it records nothing for that request.
+- `ignored_outbound_hosts` - skips tracing of outbound HTTP requests to these hosts, each written `host` or `host:port`. The endpoint host is always skipped. Use it for hosts whose traffic would drown the traces, such as a sidecar health check on `localhost`, another SDK's agent on `127.0.0.1:8126`, or another vendor's OTLP ingest host. Hosts are compared as written; `localhost` and `127.0.0.1` are different hosts, and an entry with a port matches that port only. A request to a skipped host still carries a `traceparent` marked not sampled, so an OpenTelemetry service behind it records nothing for that request.
+- `ignored_outbound_headers` - skips tracing of outbound Net::HTTP requests carrying any of these request headers, compared case-insensitively. Another SDK's transport stamps its own header on every request to its backend, such as `Datadog-Meta-Tracer-Version`, which tells that traffic apart when it has no host to ignore, as over a Unix socket. A connection opened before the request, as `Net::HTTP.start` does, has its connect span before any header is seen, so over TCP ignore the host as well.
 - `disable_log_sending` - `true` stops shipping the app's `Logger` lines to Foam. `Foam.log` is unaffected. See Loggers.
 - `network_capture` - `:off`, `:basic`, or `:advanced`. Use `:advanced` unless security and compliance rule it out. See Network capture.
 - `redact` - keys to mask beyond the built-in list, as `{secrets: [...], pii: [...]}`. A value under a `secrets` key keeps its last four characters when it is 12 characters or longer; a value under a `pii` key is fully masked. See Redaction.
@@ -254,6 +256,8 @@ end
 
 `inject_trace_context` and `extract_trace_context` always use the W3C `traceparent`, `tracestate`, and `baggage` headers, whatever propagator holds the global slot. Foam does not read `OTEL_PROPAGATORS`. An app that needs a different propagator registers it before `init`, and Foam leaves it in place.
 
+On the outbound requests Foam instruments, the propagation headers are written last, at the transport, after any other SDK's: Net::HTTP, HTTPClient, Excon, http.rb, Ethon, gRPC, and Sidekiq job payloads, and Faraday, RestClient, and Typhoeus through those. Another SDK's own propagation headers are left as written.
+
 ### `set_baggage(key, value)`
 
 Adds a key-value pair to the current context's baggage. Baggage travels with the trace context to every downstream service, where `baggage(key)` reads it; it is not written onto spans. The value lasts for the rest of the current scope, for example the rest of the request when called from a Rails controller, and is dropped when that scope ends. Outside any span or context scope the call is ignored and warned about once, so a value can never outlive the work it belongs to. No-op before `init`.
@@ -436,6 +440,8 @@ Covered:
 
 Not covered, since they do not build on `Logger`: Semantic Logger, `logging`, log4r, yell, and Puma's own server lines. Use `Foam.log` for a record from these. Semantic Logger also ships an `:open_telemetry` appender. `puts` and direct writes to `$stdout` or `$stderr` are never captured, nor is a `Logger` whose device is `nil` or `File::NULL`.
 
+Lines another SDK writes through its own `Logger` are shipped like the app's; `before_send` can drop them.
+
 If another SDK owns logs, set `disable_log_sending: true` so records do not arrive twice, and attach `create_foam_ingest_log_record_processor` to that SDK's provider. `Foam.log` delivers either way.
 
 Secrets in a log line are masked before export. See Redaction.
@@ -459,6 +465,27 @@ Thread.new do
 end
 ```
 
+## Other backends installed
+
+An app may already run another vendor's SDK, such as Datadog, which records its own telemetry and sends it to that vendor. Do not change its configuration.
+
+Call `init` after configuring the existing SDK. If the app already configures OpenTelemetry itself with `OpenTelemetry::SDK.configure`, instead attach the ingest helpers to the app's providers and do not call `init`; see `create_foam_ingest_span_processor` under Public API.
+
+### Datadog
+
+Datadog sends its data to its agent over HTTP, which Foam would otherwise record as spans. Pass the agent's address and Datadog's request header to `init`. This works whether the agent is on TCP or a Unix socket:
+
+```ruby
+agent = Datadog::Core::Configuration::AgentSettingsResolver.call(Datadog.configuration)
+agent_hosts = agent.uds_path ? [] : ["#{agent.hostname}:#{agent.port}"]
+
+Foam.init(
+  name: "checkout-api", environment: "production", token: ENV["FOAM_OTEL_TOKEN"],
+  ignored_outbound_hosts: agent_hosts,
+  ignored_outbound_headers: ["Datadog-Meta-Tracer-Version"]
+)
+```
+
 ## Redaction
 
 Foam masks the values of sensitive keys in everything it exports: span, span event, and span link attributes; log bodies and attributes; metric data point attributes; and resource attributes. A built-in list of credential and personal-data keys always applies, matched by exact name or by a sensitive segment of the key (`legacy_api_key_2`, `stripeToken`). Keys match after normalization: case, `-`, `.`, and camelCase boundaries are folded, so `apiKey`, `api-key`, and `API_KEY` are one key. Header attributes match on the header name. SQL statements arrive from the database instrumentations with every literal replaced with `?` (see Instrumentation) and are redacted like any other string. Captured HTTP bodies are masked by content type with the same keys, with their framing kept. When masking a body fails, the whole body is replaced with `********`.

data/lib/foam/otel/internal/ignored_headers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    module Internal
+      # Drops the spans of a request carrying one of the ignored headers: the request runs under a
+      # flagged context, and the sampler drops every span started there. Another SDK's transport stamps
+      # its header on every request to its backend, whether over TCP or a Unix socket. A connection
+      # opened before the request has its connect span before any header is seen; ignoring the host
+      # covers that one.
+      module IgnoredHeaders
+        CONTEXT_KEY = OpenTelemetry::Context.create_key("foam-ignored-request")
+
+        class << self
+          attr_reader :names
+
+          def install(names)
+            @names = names
+            ::Net::HTTP.prepend(self) unless names.empty?
+          end
+        end
+
+        def request(req, body = nil, &block)
+          return super unless IgnoredHeaders.names.any? { |name| req.key?(name) }
+
+          OpenTelemetry::Context.with_value(CONTEXT_KEY, true) { super }
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/internal/ignored_hosts.rb

@@ -6,26 +6,32 @@ require "opentelemetry-semantic_conventions"
 module Foam
   module Otel
     module Internal
-      # The tracer provider's sampler: drops every outbound span to an ignored host and leaves the rest
-      # to the sampler built from sample_rate. A dropped span never records, so no processor sees it.
+      # The tracer provider's sampler: drops every outbound span to an ignored host and every span under
+      # an ignored request, and leaves the rest to the sampler built from sample_rate. A dropped span
+      # never records, so no processor sees it.
       class IgnoredHosts
-        # Where the client instrumentations put the host when the span starts.
+        # Where the client instrumentations put the host and port when the span starts.
         HOST_KEYS = [
           OpenTelemetry::SemConv::SERVER::SERVER_ADDRESS,
           OpenTelemetry::SemConv::Incubating::NET::NET_PEER_NAME
         ].freeze
+        PORT_KEYS = [
+          OpenTelemetry::SemConv::SERVER::SERVER_PORT,
+          OpenTelemetry::SemConv::Incubating::NET::NET_PEER_PORT
+        ].freeze
 
         # Skipped: server spans carry the local host in server.address.
         INBOUND_KINDS = %i[server consumer].freeze
 
-        # Hosts as written, no resolution: localhost and 127.0.0.1 are different hosts.
+        # Hosts as written, no resolution: localhost and 127.0.0.1 are different hosts. An entry
+        # written host:port matches that port only.
         def initialize(hosts, delegate)
           @hosts = Set.new(hosts)
           @delegate = delegate
         end
 
         def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
-          return drop(parent_context) if ignored?(kind, attributes)
+          return drop(parent_context) if parent_context.value(IgnoredHeaders::CONTEXT_KEY) || ignored?(kind, attributes)
 
           @delegate.should_sample?(
             trace_id: trace_id, parent_context: parent_context, links: links,
@@ -52,16 +58,20 @@ module Foam
         def ignored?(kind, attributes)
           return false if attributes.nil? || INBOUND_KINDS.include?(kind)
 
-          # The host the client instrumentation set, if it set one.
+          # The host and port the client instrumentation set, if it set them.
           host = attributes.values_at(*HOST_KEYS).compact.first
+          port = attributes.values_at(*PORT_KEYS).compact.first
           # The rest-client gem's instrumentation sets no host, only the URL.
-          host ||= url_host(attributes[OpenTelemetry::SemConv::URL::URL_FULL])
+          url = parsed(attributes[OpenTelemetry::SemConv::URL::URL_FULL])
+          host ||= url&.host
+          port ||= url&.port
+          return false if host.nil?
 
-          !host.nil? && @hosts.include?(host)
+          @hosts.include?(host) || @hosts.include?("#{host}:#{port}")
         end
 
-        def url_host(url)
-          URI(url).host if url
+        def parsed(url)
+          URI(url) if url
         rescue URI::Error
           nil
         end

data/lib/foam/otel/internal/init.rb

@@ -73,6 +73,23 @@ module Foam
           begin
             ForkHooks.attach
 
+            # Where another SDK's patch and an instrumentation's define the same helper on a class,
+            # each keeps its own, whichever of the two came first.
+            Safely.call("patch resolver") { PatchResolver.install }
+
+            # Drops the spans of the requests carrying an ignored header, in every capture mode.
+            IgnoredHeaders.install(options[:ignored_outbound_headers])
+
+            # Writes the W3C headers last on the requests Foam instruments, in every capture mode.
+            Reinject.install
+
+            # The logger instrumentation emits a record from inside every Logger call, and that emit
+            # reads the current OpenTelemetry context. An SDK that supplies its own context can raise
+            # there while it boots, which would make every app log line raise. LoggerBridge is
+            # prepended after the instrumentation's patch, so it sits in front of it and drops just
+            # the record whose emit failed.
+            ::Logger.prepend(LoggerBridge) if Instrumentations.instance(Instrumentations::LOGGER).installed?
+
             # The client patches set the safe headers on every client span and, in advanced mode,
             # capture bodies too. Bodies are redacted by the same rules as attributes, so only
             # advanced builds a body redactor; its presence is what switches body capture on.
@@ -229,8 +246,8 @@ module Foam
 
         # The caller's hosts plus the endpoint host, so Foam's own exports never become client spans.
         def ignored_hosts(hosts)
-          unless hosts.is_a?(Enumerable)
-            raise ArgumentError, "ignored_outbound_hosts must be an array of hostnames, got #{hosts.inspect}"
+          unless hosts.is_a?(Enumerable) && hosts.all? { |host| host.is_a?(String) && !Internal.blank?(host) }
+            raise ArgumentError, "ignored_outbound_hosts must be an array of hostnames, each with an optional :port, got #{hosts.inspect}"
           end
 
           Set.new(hosts) << URI(Endpoint.current).host
@@ -239,7 +256,7 @@ module Foam
         # The first option holding a value init cannot use, described as "<option> must be ..., got
         # <value>", or nil when every option is usable.
         def invalid_option(
-          sample_rate:, disable_log_sending:, network_capture:, redact:, before_send:, **
+          sample_rate:, disable_log_sending:, network_capture:, ignored_outbound_headers:, redact:, before_send:, **
         )
           unless sample_rate.is_a?(Numeric) && sample_rate.finite? && (0..1).cover?(sample_rate)
             return "sample_rate must be a number from 0.0 to 1.0, got #{sample_rate.inspect}"
@@ -253,6 +270,10 @@ module Foam
             return "network_capture must be :off, :basic, or :advanced, got #{network_capture.inspect}"
           end
 
+          unless ignored_outbound_headers.is_a?(Enumerable) && ignored_outbound_headers.all? { |name| name.is_a?(String) && !Internal.blank?(name) }
+            return "ignored_outbound_headers must be an array of header names, got #{ignored_outbound_headers.inspect}"
+          end
+
           if (problem = Redactor.invalid_option(redact) || BeforeSend.invalid_option(before_send))
             return problem
           end

data/lib/foam/otel/internal/logger_bridge.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    module Internal
+      # Guards the emit the logger instrumentation runs inside every Logger line, so a failing emit
+      # drops that one record instead of raising into the app. Prepended on Logger by init once that
+      # instrumentation installed, so it sits ahead of the patch.
+      module LoggerBridge
+        private
+
+        # Another SDK's OpenTelemetry bridge can raise from Context.current while that SDK boots.
+        def emit_to_otel(severity, datetime, body)
+          Safely.call("logger bridge") { super }
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/internal/patch_resolver.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    module Internal
+      # Keeps each patch on a class calling its own helper when another patch defines one of the same
+      # name. Without this, Ruby would resolve the bare call from the front of the ancestor chain,
+      # whichever module made it, so one patch would always reach the other's helper.
+      module PatchResolver
+        # The namespace of the instrumentation patches init installs. A collision is resolved only
+        # when one of them is party to it; two unrelated gems fighting over a class are not Foam's to fix.
+        INSTRUMENTATION = "OpenTelemetry::Instrumentation::"
+
+        # Foam's own patches wrap a helper by calling super, so they are never party to a collision.
+        FOAM = "Foam::Otel::"
+
+        # The Thread.current key holding the patch whose method is running.
+        RUNNING = :foam_otel_running_patch
+
+        # Marks the modules the resolver prepends on the class, so a chain scan can leave them out.
+        module Dispatcher
+          attr_reader :names
+        end
+
+        # Marks the modules the resolver prepends on an owner.
+        module Marker
+        end
+
+        # Prepended on the class's singleton, so a module prepended later does not stay ahead.
+        module Watch
+          def prepend(*modules)
+            super
+            PatchResolver.assert(self)
+            self
+          end
+        end
+
+        class << self
+          # Watches every loaded class carrying an instrumentation patch and resolves what already
+          # collides on it. Runs after the instrumentations installed.
+          def install
+            patched_classes.each do |klass|
+              klass.singleton_class.prepend(Watch) unless klass.singleton_class.include?(Watch)
+              assert(klass)
+            end
+          end
+
+          def patched_classes
+            ObjectSpace.each_object(Class).select do |klass|
+              !klass.singleton_class? && patches(klass).any? { |mod| instrumentation?(mod) }
+            end
+          end
+
+          # Marks the owners and prepends a dispatcher for the helpers that collide on klass, unless
+          # the front of the chain already holds one for the same helpers. Warns when a collision is
+          # first resolved, once per helper.
+          def assert(klass)
+            modules = patches(klass)
+            names = collisions(klass, modules)
+            return if names.empty?
+
+            front = klass.ancestors.first
+            return if front.is_a?(Dispatcher) && front.names == names
+
+            owners = modules.select { |mod| names.any? { |name| defines?(mod, name) } }
+            if owners.map { |owner| mark(owner, names) }.any?
+              names.each do |name|
+                holders = owners.select { |mod| defines?(mod, name) }
+                Diagnostics.warn("#{klass}: #{name} is defined by #{holders.join(" and ")}; each patch keeps its own")
+              end
+            end
+            klass.prepend(dispatcher(names, owners))
+          end
+
+          # The helpers two or more of the modules define, an instrumentation patch among them, that
+          # nothing behind the modules defines. A method the class itself has is overridden on purpose
+          # and chains through super, as Net::HTTP#request does under two SDKs; a helper exists nowhere
+          # below the patches, so two definitions fight.
+          def collisions(klass, modules)
+            behind = klass.ancestors.drop_while { |ancestor| !ancestor.equal?(klass) }
+            counts = modules.flat_map { |mod| mod.instance_methods(false) + mod.private_instance_methods(false) }.tally
+            counts.filter_map do |name, count|
+              next if count < 2 || behind.any? { |ancestor| defines?(ancestor, name) }
+
+              name if modules.any? { |mod| instrumentation?(mod) && defines?(mod, name) }
+            end
+          end
+
+          # The modules prepended on klass, the resolver's own and Foam's left out.
+          def patches(klass)
+            klass.ancestors.take_while { |ancestor| !ancestor.equal?(klass) }
+              .reject { |mod| mod.is_a?(Dispatcher) || mod.is_a?(Marker) || mod.name.to_s.start_with?(FOAM) }
+          end
+
+          def instrumentation?(mod)
+            mod.name.to_s.start_with?(INSTRUMENTATION)
+          end
+
+          def defines?(mod, name)
+            mod.method_defined?(name, false) || mod.private_method_defined?(name, false)
+          end
+
+          # Records the owner as the running patch for the duration of each of its methods, the
+          # helpers themselves aside. Prepended on the owner module, the wrapper sits right ahead of it
+          # in every class that prepended the owner. Returns whether the owner was marked now rather
+          # than earlier.
+          def mark(owner, names)
+            return false if owner.ancestors.any? { |mod| mod.is_a?(Marker) }
+
+            marker = Module.new do
+              extend Marker
+
+              methods = owner.instance_methods(false) + owner.private_instance_methods(false) - names
+              methods.each do |method_name|
+                define_method(method_name) do |*args, **options, &block|
+                  previous = Thread.current[RUNNING]
+                  Thread.current[RUNNING] = owner
+                  super(*args, **options, &block)
+                ensure
+                  Thread.current[RUNNING] = previous
+                end
+                private method_name if owner.private_method_defined?(method_name, false)
+              end
+            end
+            owner.prepend(marker)
+            true
+          end
+
+          # Answers each colliding helper with the running patch's own implementation. A call from
+          # outside every marked patch continues down the chain, where the first owner's helper
+          # answers as it would without the resolver. A helper every owner keeps private stays private.
+          def dispatcher(names, owners)
+            Module.new do
+              extend Dispatcher
+
+              @names = names
+              names.each do |name|
+                holders = owners.select { |owner| PatchResolver.defines?(owner, name) }
+                implementations = holders.to_h { |owner| [owner, owner.instance_method(name)] }
+                define_method(name) do |*args, **options, &block|
+                  implementation = implementations[Thread.current[RUNNING]]
+                  implementation ? implementation.bind_call(self, *args, **options, &block) : super(*args, **options, &block)
+                end
+                private name if holders.all? { |owner| owner.private_method_defined?(name, false) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/internal/reinject.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    module Internal
+      # Handles another backend SDK in the same process, such as Datadog. Both SDKs write trace
+      # headers on the outbound requests, and whichever writes last owns traceparent. Foam writes
+      # its W3C headers again at the transport, so traceparent always carries Foam's trace. The
+      # other SDK's own headers (such as Datadog's x-datadog-*) are left as written, so each
+      # backend continues its own trace downstream. Installed by init in every capture mode.
+      module Reinject
+        module_function
+
+        # The global propagator, the one the instrumentation used. Without a span there is nothing
+        # the instrumentation wrote, so nothing is written here either.
+        def call(carrier, context: OpenTelemetry::Context.current)
+          return if OwnRequest.current? || !OpenTelemetry::Trace.current_span(context).context.valid?
+
+          OpenTelemetry.propagation.inject(carrier, context: context)
+        end
+
+        module NetHttp
+          private
+
+          def transport_request(req)
+            Safely.call("propagation") { Reinject.call(req) }
+            super
+          end
+        end
+
+        module HttpClient
+          def query(req)
+            Safely.call("propagation") { Reinject.call(req.header) }
+            super
+          end
+        end
+
+        module Excon
+          def request_call(datum)
+            Safely.call("propagation") { Reinject.call(datum[:headers]) }
+            super
+          end
+        end
+
+        module HttpRb
+          def send_request(req)
+            Safely.call("propagation") { Reinject.call(req.headers) }
+            super
+          end
+        end
+
+        # Every header write reaches libcurl through this setter, the instrumentation's and any
+        # other SDK's alike, so the last one carries Foam's headers whichever it was.
+        module Ethon
+          def headers=(headers)
+            headers = (headers || {}).dup
+            Safely.call("propagation") { Reinject.call(headers, context: foam_ethon_context) }
+            super
+          end
+
+          private
+
+          # The instrumentation starts its span in @otel_span without making it current.
+          def foam_ethon_context
+            span = @otel_span if instance_variable_defined?(:@otel_span)
+            span ? OpenTelemetry::Trace.context_with_span(span) : OpenTelemetry::Context.current
+          end
+        end
+
+        # The client interceptors, where both SDKs inject, run outside these calls.
+        module Grpc
+          %i[request_response client_streamer server_streamer bidi_streamer].each do |name|
+            define_method(name) do |*args, metadata: {}, **rest, &block|
+              Safely.call("propagation") { Reinject.call(metadata) }
+              super(*args, metadata: metadata, **rest, &block)
+            end
+          end
+        end
+
+        # The chain's final block runs inside every client middleware, where both SDKs inject, with
+        # the producer span current.
+        module Sidekiq
+          # The client chain is invoked as (worker_class, job, queue, redis_pool), the server chain as
+          # (worker, job, queue).
+          def invoke(*args, &block)
+            return super unless args.size == 4
+
+            _worker_class, job, _queue, _redis_pool = args
+            super do
+              Safely.call("propagation") { Reinject.call(job) }
+              block.call
+            end
+          end
+        end
+
+        # The transport class each hook prepends onto, and the instrumentation that has to be
+        # installed for the hook to apply; Net::HTTP is patched without a check, since foam-otel
+        # loads it for its own exporters.
+        HOOKS = {
+          NetHttp => ["Net::HTTP", nil],
+          HttpClient => ["HTTPClient::Session", Clients::HttpClient::INSTRUMENTATION],
+          Excon => ["Excon::Connection", Clients::Excon::INSTRUMENTATION],
+          HttpRb => ["HTTP::Connection", "OpenTelemetry::Instrumentation::HTTP"],
+          Ethon => ["Ethon::Easy", "OpenTelemetry::Instrumentation::Ethon"],
+          Grpc => ["GRPC::ActiveCall", "OpenTelemetry::Instrumentation::Grpc"],
+          Sidekiq => ["Sidekiq::Middleware::Chain", "OpenTelemetry::Instrumentation::Sidekiq"]
+        }.freeze
+
+        def install
+          HOOKS.each do |hook, (klass, instrumentation)|
+            next unless instrumentation.nil? || Instrumentations.instance(instrumentation).installed?
+
+            Object.const_get(klass).prepend(hook)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/version.rb

@@ -2,6 +2,6 @@
 
 module Foam
   module Otel
-    VERSION = "3.0.0.alpha.5"
+    VERSION = "3.0.0.alpha.6"
   end
 end

data/lib/foam/otel.rb

@@ -26,9 +26,13 @@ require_relative "otel/internal/aws_lambda"
 require_relative "otel/internal/rails_middleware"
 require_relative "otel/internal/before_send"
 require_relative "otel/internal/instrumentations"
+require_relative "otel/internal/ignored_headers"
+require_relative "otel/internal/logger_bridge"
+require_relative "otel/internal/reinject"
 require_relative "otel/internal/ignored_hosts"
 require_relative "otel/internal/slots"
 require_relative "otel/internal/fork_hooks"
+require_relative "otel/internal/patch_resolver"
 require_relative "otel/internal/resource"
 require_relative "otel/internal/init"
 require_relative "otel/internal/exporters"
@@ -58,6 +62,7 @@ module Foam
         disable_log_sending: false,
         network_capture: :basic,
         ignored_outbound_hosts: [],
+        ignored_outbound_headers: [],
         redact: nil,
         before_send: nil
       )
@@ -77,6 +82,7 @@ module Foam
             disable_log_sending: disable_log_sending,
             network_capture: network_capture,
             ignored_outbound_hosts: ignored_outbound_hosts,
+            ignored_outbound_headers: ignored_outbound_headers,
             redact: redact,
             before_send: before_send
           )

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: foam-otel
 version: !ruby/object:Gem::Version
-  version: 3.0.0.alpha.5
+  version: 3.0.0.alpha.6
 platform: ruby
 authors:
 - Foam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-exporter-otlp
@@ -176,21 +176,25 @@ files:
 - lib/foam/otel/internal/endpoint.rb
 - lib/foam/otel/internal/exporters.rb
 - lib/foam/otel/internal/fork_hooks.rb
+- lib/foam/otel/internal/ignored_headers.rb
 - lib/foam/otel/internal/ignored_hosts.rb
 - lib/foam/otel/internal/ingest.rb
 - lib/foam/otel/internal/init.rb
 - lib/foam/otel/internal/instrumentations.rb
 - lib/foam/otel/internal/lifecycle.rb
+- lib/foam/otel/internal/logger_bridge.rb
 - lib/foam/otel/internal/logs.rb
 - lib/foam/otel/internal/metrics.rb
 - lib/foam/otel/internal/otlp.rb
 - lib/foam/otel/internal/own_request.rb
+- lib/foam/otel/internal/patch_resolver.rb
 - lib/foam/otel/internal/propagation.rb
 - lib/foam/otel/internal/rack/body_tee.rb
 - lib/foam/otel/internal/rack/input_tee.rb
 - lib/foam/otel/internal/rails_middleware.rb
 - lib/foam/otel/internal/redactor.rb
 - lib/foam/otel/internal/redactor/keys.rb
+- lib/foam/otel/internal/reinject.rb
 - lib/foam/otel/internal/report.rb
 - lib/foam/otel/internal/resource.rb
 - lib/foam/otel/internal/safely.rb