foam-otel 3.0.0.alpha.9 → 3.0.0.alpha.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 240906547c665dd40513921db5ab9f00d65febef81d40848faa91a1f5ae02e15
-  data.tar.gz: 9a2c4c5045ba080c21b165e1a87836cd9288408343b049c293352162e9be7083
+  metadata.gz: a99c91ac48b87605a88f36e38e06ceddf80a6af6f029aad030203bc3d09603fb
+  data.tar.gz: 840a2d7cbf0baebf643c3f0422c310da434d3dc147c23e0c919792f36b4e3726
 SHA512:
-  metadata.gz: f891d7d8a749ce8a9042f08183581ec43924445d21137b863619a912cd0be0bb516e340d01e2ed6e238356a3b61f3cedb5739b769b04e38213d785712616cb9f
-  data.tar.gz: dd19f649f254cff7a00da71b14f158cc3d3d370a3affcc587ec86156d5439aaecd956564e106c54f0c0b2d229195065f69c03ab3eae9058459265ea479b71aaf
+  metadata.gz: b01ef004f8ee7e8638badb8ee4934b07df03a2f636ec61bbf6a0f1d77fae7e187ddb41dca30c0b0dc667e9a3a1c2d9792bb70fe7f4f38295c0e03e4474d40471
+  data.tar.gz: 666a66c3c6a5da5e8d3daf5c50b4536155538bfa321ce82bd6bfa3dcf97f407fac976b81999b50abdd4e0d7d50ac7e3172b55f30f1dca3afbbb223653ca3eea3

data/README.md

@@ -227,7 +227,7 @@ Do not combine `init` and an ingest component for the same signal. The ingest co
 
 ### `inject_trace_context(carrier)`
 
-Writes the W3C `traceparent`, `tracestate`, and `baggage` headers for the current span into `carrier`, a hash of string keys.
+Writes the W3C `traceparent`, `tracestate`, and `baggage` headers for the current span into `carrier`, a hash of string keys. A `tracestate` the carrier already holds is kept, since Foam adds no entry of its own and another SDK may have added one.
 
 Use it when the app sends a message itself (a Kafka record, a queue payload, a custom socket). The HTTP instrumentations already inject these headers; do not call it on ordinary HTTP requests. Without an active span it writes only `baggage`, and only when baggage is set.
 
@@ -252,7 +252,18 @@ 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 outbound requests, Foam writes its propagation headers after any other SDK's. Another SDK's own propagation headers are left as written.
+On outbound requests, Foam writes its propagation headers after any other SDK's. Another SDK's own propagation headers are left as written, and Foam's baggage entries are merged into the members it wrote to `baggage`. These writes go through the propagator in the global slot.
+
+### `propagator`
+
+The propagator `inject_trace_context` and `extract_trace_context` use, for an app that sets its own composite in the global slot. List it last, so a caller's `traceparent` wins over another SDK's trace header:
+
+```ruby
+OpenTelemetry.propagation = OpenTelemetry::Context::Propagation::CompositeTextMapPropagator.compose_propagators([
+  other_sdk_propagator,
+  Foam.propagator
+])
+```
 
 ### `set_baggage(key, value)`
 
@@ -485,6 +496,50 @@ Foam.init(
 )
 ```
 
+### Sentry
+
+Sentry sends its events to the DSN's host over HTTP, which Foam would otherwise record as spans. Pass that address and Sentry's request header to `init`. This works whether Sentry sends inline or from its background worker:
+
+```ruby
+dsn = Sentry.configuration.dsn
+
+Foam.init(
+  name: "checkout-api", environment: "production", token: ENV["FOAM_OTEL_TOKEN"],
+  ignored_outbound_hosts: ["#{dsn.host}:#{dsn.port}"],
+  ignored_outbound_headers: ["X-Sentry-Auth"]
+)
+```
+
+If the app puts Sentry's propagator in the global slot, through `sentry-opentelemetry`'s `config.otlp.setup_propagator` or `OpenTelemetry.propagation = Sentry::OpenTelemetry::Propagator.new`, outbound requests carry `sentry-trace` but no `traceparent`, so Foam's traces break between services. Once both `init` and that setting have run, wrap Sentry's propagator with Foam's:
+
+```ruby
+OpenTelemetry.propagation = OpenTelemetry::Context::Propagation::CompositeTextMapPropagator.compose_propagators([
+  OpenTelemetry.propagation,
+  Foam.propagator
+])
+```
+
+### New Relic
+
+New Relic's agent sends its data to its collector over HTTP, and probes the AWS, Azure and GCP metadata endpoints when it connects, which Foam would otherwise record as spans. Pass the collector's address and the metadata hosts to `init`. The agent's requests carry no header of its own, so there is none to pass:
+
+```ruby
+collector = "#{NewRelic::Agent.config[:host]}:#{NewRelic::Agent.config[:port]}"
+
+Foam.init(
+  name: "checkout-api", environment: "production", token: ENV["FOAM_OTEL_TOKEN"],
+  ignored_outbound_hosts: [
+    collector,
+    "169.254.169.254", # AWS and Azure metadata
+    "metadata.google.internal" # GCP metadata
+  ]
+)
+```
+
+Start New Relic before `init`, as Rails does through the agent's Railtie. If the agent instruments Net::HTTP in chain mode and starts after `init`, every Net::HTTP request raises `SystemStackError`. The agent uses chain mode when `instrumentation.net_http` is `chain`, or on its own next to ScoutApm, Rack::MiniProfiler, or Airbrake before 10.0.2. Where the order cannot change, set `instrumentation.net_http` to `prepend`.
+
+If the app turns on New Relic's OpenTelemetry bridge (`opentelemetry.enabled`), New Relic takes the tracer provider and propagator, and Foam records no traces. Logs and metrics still reach Foam.
+
 ## 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. When masking a body fails, the whole body is replaced with `********`.

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

@@ -22,7 +22,7 @@ module Foam
         }.freeze
 
         def self.install
-          return unless Instrumentations.instance(INSTRUMENTATION).installed?
+          return unless Instrumentations.installed?(INSTRUMENTATION)
 
           ::OpenTelemetry::Instrumentation::AwsLambda::Wrap.prepend(Wrap)
         end

data/lib/foam/otel/internal/clients/excon.rb

@@ -17,7 +17,7 @@ module Foam
           DECOMPRESSED = %w[gzip x-gzip deflate].freeze
 
           def self.install
-            return unless Instrumentations.instance(INSTRUMENTATION).installed?
+            return unless Instrumentations.installed?(INSTRUMENTATION)
 
             stack = ::Excon.defaults[:middlewares]
             return if stack.include?(self)

data/lib/foam/otel/internal/clients/faraday.rb

@@ -28,7 +28,7 @@ module Foam
           end
 
           def self.install
-            return unless Instrumentations.instance(INSTRUMENTATION).installed?
+            return unless Instrumentations.installed?(INSTRUMENTATION)
 
             ::Faraday::Connection.prepend(Connection)
             instrument_default_connection

data/lib/foam/otel/internal/clients/http_client.rb

@@ -13,7 +13,7 @@ module Foam
           INFLATED_ENCODINGS = %w[gzip x-gzip deflate].freeze
 
           def self.install
-            return unless Instrumentations.instance(INSTRUMENTATION).installed?
+            return unless Instrumentations.installed?(INSTRUMENTATION)
 
             ::HTTPClient::Session.prepend(self)
           end

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

@@ -12,7 +12,7 @@ module Foam
           attr_reader :current
 
           def set(value)
-            if State.current[:initialized]
+            if State.initialized?
               Diagnostics.warn("set_endpoint after init: exporters keep #{@current}; only later reports use #{value}")
             end
             @current = value

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

@@ -36,7 +36,7 @@ module Foam
           end
 
           # A second configure would install a second pipeline next to the first.
-          if State.current[:initialized]
+          if State.initialized?
             Report.call(severity: :warn, message: "SDK already initialized", **identity)
             return
           end
@@ -90,7 +90,7 @@ module Foam
             # 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?
+            ::Logger.prepend(LoggerBridge) if Instrumentations.installed?(Instrumentations::LOGGER)
 
             # 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
@@ -102,6 +102,10 @@ module Foam
             # Foam's logger provider where it flushes the tracer and meter providers.
             Safely.call("aws_lambda") { AwsLambda.install }
 
+            # Leaves out a propagation header Que would refuse as a job tag, so the app's enqueue
+            # does not raise on a long baggage.
+            Safely.call("que") { Que.install }
+
             # A Rails app cannot add the middleware in config.ru the way a plain Rack app does, so
             # Foam adds it through Rails itself.
             Safely.call("rails middleware") { RailsMiddleware.install } unless options[:network_capture] == :off

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

@@ -104,7 +104,7 @@ module Foam
 
         # Labels of the instrumentations that installed, in table order, then the caller's entries.
         def installed(config_map)
-          config_map.filter_map { |name, _config| label(short_name(name)) if instance(name).installed? }
+          config_map.filter_map { |name, _config| label(short_name(name)) if installed?(name) }
         end
 
         # Labels of the instrumentations whose library arrived after init: present, enabled, and
@@ -113,8 +113,10 @@ module Foam
           config_map.filter_map { |name, config| label(short_name(name)) if late?(instance(name), config) }
         end
 
+        # An entry another SDK deleted from the registry after init (see installed?) has no instance to
+        # ask, so it counts as neither installed nor late.
         def late?(instance, config)
-          !instance.installed? && instance.present? && instance.enabled?(config) && compatible?(instance)
+          !instance.nil? && !instance.installed? && instance.present? && instance.enabled?(config) && compatible?(instance)
         end
 
         # A compatibility block reads the library's version constant, which can raise on an odd install.
@@ -128,6 +130,12 @@ module Foam
           OpenTelemetry::Instrumentation.registry.lookup(name)
         end
 
+        # Another SDK can remove entries from the registry, as New Relic's OpenTelemetry bridge does
+        # for the libraries it covers itself, so a missing entry reads as not installed.
+        def installed?(name)
+          instance(name)&.installed? || false
+        end
+
         # The table's short name, or one derived the same way for an instrumentation outside the bundle.
         def short_name(name)
           TABLE.fetch(name) do

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

@@ -4,10 +4,86 @@ module Foam
   module Otel
     module Internal
       module Propagation
+        # Writes W3C trace context, as OpenTelemetry's propagator does, but does not replace a
+        # tracestate header that is already on the outgoing request. Foam has no tracestate entry of
+        # its own. Another SDK, such as New Relic or Datadog, can write tracestate first and put its
+        # entry (@nr, dd) before the caller's entries. If Foam wrote tracestate again, that entry
+        # would be lost. Foam always writes traceparent.
+        module KeptTracestate
+          UPSTREAM = OpenTelemetry::Trace::Propagation::TraceContext.text_map_propagator
+
+          # Passes every header through but tracestate.
+          SkipTracestate = Struct.new(:setter) do
+            def set(carrier, key, value)
+              setter.set(carrier, key, value) unless key == "tracestate"
+            end
+          end
+
+          module_function
+
+          def inject(carrier, context:, setter:)
+            setter = SkipTracestate.new(setter) if header(carrier)
+            UPSTREAM.inject(carrier, context: context, setter: setter)
+          end
+
+          def extract(carrier, **) = UPSTREAM.extract(carrier, **)
+
+          def fields = UPSTREAM.fields
+
+          # Reads the carrier's tracestate header as one string, or nil when it has none. Carriers
+          # differ: HTTPClient returns an array of header values, the others a string. A list carrier,
+          # such as Que's job tags, cannot be read by header name, so there is nothing to keep.
+          def header(carrier)
+            return if carrier.is_a?(Array)
+
+            value = Array(carrier["tracestate"]).join(",")
+            value unless value.empty?
+          end
+        end
+
+        # The W3C baggage header is shared between SDKs: Sentry, for one, writes its sampling context
+        # there as sentry-* members. OpenTelemetry's baggage propagator overwrites the whole header
+        # with Foam's entries, so whichever SDK wrote first loses its members. This wraps it to merge
+        # instead, keeping the other SDK's members and letting Foam's value win a shared key.
+        module MergingBaggage
+          UPSTREAM = OpenTelemetry::Baggage::Propagation.text_map_propagator
+
+          module_function
+
+          def inject(carrier, context:, setter:)
+            theirs = header(carrier)
+            UPSTREAM.inject(carrier, context: context, setter: setter)
+            ours = header(carrier)
+            return if theirs.nil? || ours == theirs
+
+            keys = ours.split(",").map { |member| key(member) }
+            kept = theirs.split(",").map(&:strip).reject { |member| member.empty? || keys.include?(key(member)) }
+            setter.set(carrier, "baggage", [ours, *kept].join(","))
+          end
+
+          def extract(carrier, **) = UPSTREAM.extract(carrier, **)
+
+          def fields = UPSTREAM.fields
+
+          # Reads the carrier's baggage header as one string, or nil when it has none. inject reads it
+          # before and after the upstream write, to tell the other SDK's members from Foam's. Carriers
+          # differ: HTTPClient returns an array of header values, the others a string. A list carrier,
+          # such as Que's job tags, is written through its setter and cannot be read by header name,
+          # so there is nothing to merge.
+          def header(carrier)
+            return if carrier.is_a?(Array)
+
+            value = Array(carrier["baggage"]).join(",")
+            value unless value.empty?
+          end
+
+          def key(member) = member.split("=", 2).first.strip
+        end
+
         # Foam's own W3C propagator, so the helpers work the same whoever configured the global one.
         PROPAGATOR = OpenTelemetry::Context::Propagation::CompositeTextMapPropagator.compose_propagators([
-          OpenTelemetry::Trace::Propagation::TraceContext.text_map_propagator,
-          OpenTelemetry::Baggage::Propagation.text_map_propagator
+          KeptTracestate,
+          MergingBaggage
         ])
 
         module_function

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Foam
+  module Otel
+    module Internal
+      # Foam's addition to the que instrumentation, prepended on its TagSetter by init after
+      # installation. The instrumentation writes each propagation header into the job's tags as
+      # "key:value", and Que refuses to enqueue a job with a tag longer than MAXIMUM_TAG_LENGTH or
+      # more than MAXIMUM_TAGS_COUNT tags, so a long baggage, the app's or another SDK's, would make
+      # the app's enqueue raise. The setter leaves out a header Que would refuse, warning once, and
+      # the job enqueues without it.
+      module Que
+        INSTRUMENTATION = "OpenTelemetry::Instrumentation::Que"
+
+        def self.install
+          return unless Instrumentations.installed?(INSTRUMENTATION)
+
+          ::OpenTelemetry::Instrumentation::Que::TagSetter.singleton_class.prepend(TagSetter)
+        end
+
+        def self.fits?(tags, tag)
+          tag.length <= ::Que::Job::MAXIMUM_TAG_LENGTH && tags.length < ::Que::Job::MAXIMUM_TAGS_COUNT
+        end
+
+        def self.warn_left_out(key)
+          return if @warned
+
+          @warned = true
+          Diagnostics.warn(
+            "propagation header #{key} left out of a Que job's tags; Que allows at most " \
+            "#{::Que::Job::MAXIMUM_TAGS_COUNT} tags of #{::Que::Job::MAXIMUM_TAG_LENGTH} characters"
+          )
+        end
+
+        module TagSetter
+          def set(carrier, key, value)
+            return super if Que.fits?(carrier, "#{key}:#{value}")
+
+            Que.warn_left_out(key)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -46,7 +46,7 @@ module Foam
           # it builds the real stack late in initialize!. Anchored on the OpenTelemetry class, not
           # position 0, so another SDK inserting at the top cannot come between the two.
           def insert(app)
-            return unless Instrumentations.instance(ACTION_PACK).installed?
+            return unless Instrumentations.installed?(ACTION_PACK)
 
             otel = Instrumentations.instance(RACK).middleware_args.first
             app.middleware.insert_after(otel, Foam::Rack::Middleware)

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

@@ -11,8 +11,9 @@ module Foam
       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.
+        # The global propagator, the one the instrumentation used: whoever holds the slot, before or
+        # after init, decides the headers. 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?
 
@@ -108,7 +109,7 @@ module Foam
 
         def install
           HOOKS.each do |hook, (klass, instrumentation)|
-            next unless instrumentation.nil? || Instrumentations.instance(instrumentation).installed?
+            next unless instrumentation.nil? || Instrumentations.installed?(instrumentation)
 
             Object.const_get(klass).prepend(hook)
           end

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

@@ -35,6 +35,12 @@ module Foam
             end
           end
 
+          # Whether init has completed, without reading the live slots as current does, which warns
+          # about a slot another SDK took since.
+          def initialized?
+            @mutex.synchronize { @initialized }
+          end
+
           # Gate for the helpers: the hash is replaced whole, never mutated, so no lock.
           def active?(signal)
             @signals[signal] != :none

data/lib/foam/otel/version.rb

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

data/lib/foam/otel.rb

@@ -23,6 +23,7 @@ require_relative "otel/internal/clients/excon"
 require_relative "otel/internal/clients/http_client"
 require_relative "otel/internal/clients/faraday"
 require_relative "otel/internal/aws_lambda"
+require_relative "otel/internal/que"
 require_relative "otel/internal/rails_middleware"
 require_relative "otel/internal/before_send"
 require_relative "otel/internal/instrumentations"
@@ -129,6 +130,11 @@ module Foam
         end
       end
 
+      # The propagator the two helpers above use, for an app that composes its own.
+      def propagator
+        Internal::Propagation::PROPAGATOR
+      end
+
       def set_baggage(key, value)
         Internal::Safely.call("set_baggage") do
           Internal::Propagation.set_baggage(key, value)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: foam-otel
 version: !ruby/object:Gem::Version
-  version: 3.0.0.alpha.9
+  version: 3.0.0.alpha.11
 platform: ruby
 authors:
 - Foam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-exporter-otlp
@@ -204,6 +204,7 @@ files:
 - lib/foam/otel/internal/own_request.rb
 - lib/foam/otel/internal/patch_resolver.rb
 - lib/foam/otel/internal/propagation.rb
+- lib/foam/otel/internal/que.rb
 - lib/foam/otel/internal/rack/body_tee.rb
 - lib/foam/otel/internal/rack/input_tee.rb
 - lib/foam/otel/internal/rails_middleware.rb