foam-otel 1.0.2 → 1.2.0

data/lib/foam/otel/ingest_metric_reader.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# The door-2 metrics tap. Required LAZILY by the ingest factory AFTER
+# require_sdk! (rule 41): the superclass constant only exists once the
+# metrics SDK is loaded.
+#
+# SUBCLASSING (flagged deviation, fleet-accepted): composition is preferred
+# everywhere else, but MeterProvider#add_metric_reader requires the
+# `metric_store` seam (meter_provider.rb registers every instrument with the
+# reader's store — including BACK-FILLING instruments created before attach,
+# meter.rb) and the periodic ticker thread + after_fork machinery is exactly
+# what the tap must inherit (periodic_metric_reader.rb). This is an alpha-SDK
+# behavioral reliance, capped by the gemspec range and pinned by tests
+# (GOTCHAS R5/R6).
+module Foam
+  module Otel
+    module Ingest
+      class MetricReader < OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader
+        def initialize(exporter:, config:)
+          @foam_config = config
+          @foam_claim_checked = false
+          @foam_double_claim_warned = false
+          @foam_stood_down = false
+          # super LAST: the superclass constructor starts the ticker thread,
+          # which reads the ivars above via collect.
+          super(exporter: exporter)
+        end
+
+        # Guarded collect (GOTCHAS R6): PeriodicMetricReader#export has NO
+        # rescue — a raising collect (or exporter) would kill the reader
+        # thread silently and the tap would go dark with no warning. Foam's
+        # exporter chain already rescues everything to FAILURE; this guard
+        # closes the collect half. Also the metrics double-claim gate (fleet
+        # ruling 2c / audit R9): checked once, on the first non-empty
+        # collection, BEFORE anything reaches the exporter — a stand-down
+        # exports zero duplicates ever.
+        def collect
+          batch = super
+          admit_metrics(batch.is_a?(Array) ? batch : [])
+        rescue StandardError, SystemStackError
+          []
+        end
+
+        # A stood-down tap must stay down across forks; everything else
+        # inherits the upstream fork recovery (exporter reset + restart),
+        # driven by foam's own Process._fork hook via the @ingest_taps
+        # registry (GOTCHAS R7 — upstream only wires after_fork through
+        # SDK.configure, which door 2 never runs).
+        def after_fork
+          return if @foam_stood_down
+
+          super
+        end
+
+        private
+
+        def admit_metrics(batch)
+          return [] if @foam_stood_down
+          return batch if batch.empty?
+
+          # Self-ingest is structural — decided once, on the first non-empty
+          # collection.
+          unless @foam_claim_checked
+            @foam_claim_checked = true
+            if Ingest.foam_resource?(batch.first&.resource)
+              Diagnostics.warn(Ingest.self_ingest_warning(:metrics))
+              @foam_stood_down = true
+              # Stop the ticker after this pass: a stood-down tap exports
+              # nothing and should not keep waking a thread to do it.
+              @continue = false
+              return []
+            end
+          end
+          # The same-signal double-claim is RE-CHECKED on every non-empty
+          # collection until the W3 warning fires once: init() may register
+          # metrics AFTER the foreign reader starts collecting (fleet ruling 2c
+          # — a late init() is still caught, matching JS/Python).
+          if !@foam_double_claim_warned && Foam::Otel.send(:foam_exports_signal?, :metrics)
+            @foam_double_claim_warned = true
+            Diagnostics.warn(Ingest.double_claim_warning(:metrics))
+          end
+          batch
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/init.rb

@@ -14,6 +14,10 @@ require_relative "instance"
 require_relative "api"
 require_relative "pipelines"
 require_relative "fork_hooks"
+require_relative "ingest" # door-2 entries (SDK still lazy — rule 41)
+require_relative "logger_bridge"
+require_relative "runtime_metrics"
+require_relative "llm"
 
 module Foam
   module Otel
@@ -28,10 +32,19 @@ module Foam
     # NOT self-heal across forks (batch span/log processors reset_on_fork
     # themselves; verified upstream) and needs explicit after_fork.
     @metric_readers = []
+    # Door-2 ingest metric readers (taps on FOREIGN pipelines) — deliberately
+    # a SEPARATE registry from @metric_readers: a post-fork re-init retires
+    # foam's own pipelines (retire_foam_pipelines! clears @metric_readers),
+    # which would orphan tap readers that belong to the CUSTOMER'S pipeline,
+    # not foam's (GOTCHAS R7). Walked by after_fork! alongside foam's own.
+    @ingest_taps = []
     # The provider foam registered per signal, and which signals have already
     # warned about a late-arrival displacement (rule 11 / 18 step 5).
     @foam_registered = {}
     @displacement_warned = {}
+    # Whether a post-fork re-init already retired the pipelines inherited
+    # from the parent (retired at most once per init).
+    @inherited_retired = false
 
     class << self
       # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -54,13 +67,16 @@ module Foam
           raise ArgumentError, "Foam::Otel.init requires enabled: true or false (got #{enabled.inspect})"
         end
 
-        # OTEL_SDK_DISABLED=true (exact string) is the operator kill switch and
-        # SUPERSEDES enabled: true (rule 19). Foam bypasses SDK.configure, so it
-        # must honor the var itself.
-        killed = ENV["OTEL_SDK_DISABLED"] == "true"
+        # OTEL_SDK_DISABLED=true is the operator kill switch and SUPERSEDES
+        # enabled: true (rule 19). Foam bypasses SDK.configure, so it must honor
+        # the var itself. Matched trimmed + case-insensitive so the fleet's one
+        # emergency switch behaves identically across languages (JS/Python
+        # trim + downcase; the OTel boolean-env convention is case-insensitive).
+        killed = kill_switch_active?
         effective_enabled = enabled && !killed
 
         endpoint = resolve_endpoint
+        warn_inert_per_signal_endpoints(endpoint)
         config = resolve_config(
           name: name, environment: environment, version: version,
           enabled: effective_enabled,
@@ -68,23 +84,39 @@ module Foam
           ignored_outbound_hosts: ignored_outbound_hosts,
           diagnostics: diagnostics, endpoint: endpoint
         )
-        self.active_config = config
-
         # Calling init twice warns and returns the first instance (rule:
-        # lifecycle). Config above is refreshed so the helpers read the latest
-        # redaction lists, but providers are never re-registered.
+        # lifecycle). The redaction lists (and diagnostics) refresh so the
+        # helpers read the latest customer lists — but enabled/endpoint/identity
+        # are process-global and are NEVER changed by a second init: overwriting
+        # `enabled` here would leave foam HALF-dark (a second init(enabled:false)
+        # would no-op the helpers while the already-registered providers keep
+        # exporting Rack/Net::HTTP spans — the operator believes foam is off
+        # while data still flows), and the reverse would "wake" a service booted
+        # disabled without ever building a pipeline. Merge ONLY the redact lists.
         if @initialized
-          Diagnostics.warn("init already called — returning the existing instance (providers are process-global)")
+          self.active_config = refresh_post_init_config(
+            active_config, redact_keys: redact_keys, redact_pii_keys: redact_pii_keys, diagnostics: diagnostics
+          )
+          Diagnostics.warn("init already called — returning the existing instance (providers are process-global; " \
+                           "enabled and endpoint cannot change after the first init — only the redaction lists refresh)")
           return @instance
         end
+        self.active_config = config
 
         warn_environment(environment)
+        warn_missing_version(version)
 
         unless effective_enabled
-          Diagnostics.warn(
-            killed ? "OTEL_SDK_DISABLED=true — foam is fully off (no SDK, no export)"
-                   : "enabled: false — foam is inert (no SDK loaded, no providers, no export)"
-          )
+          if killed
+            # The kill switch OVERRIDES the code's enabled: true — an operator
+            # intervention is worth one loud line (rule 19 env table).
+            Diagnostics.warn("OTEL_SDK_DISABLED=true — foam is fully off (no SDK, no export)")
+          else
+            # enabled: false is the DOCUMENTED tests/CI posture (README
+            # scenario 6): an EXPECTED state stays silent (rule 10). The
+            # posture line is still visible under diagnostics: true.
+            Diagnostics.info("enabled: false — foam is inert (no SDK loaded, no providers, no export)")
+          end
           @initialized = true
           return @instance = Instance.new(config)
         end
@@ -98,23 +130,37 @@ module Foam
         require_sdk!
         configure_propagation
 
-        # Classify ALL THREE slots before ANY registration (rule 18, step 1).
-        verdicts = Classifier.classify
+        # Providers foam registered in the PARENT process — non-empty only on
+        # a post-fork re-init (the fork hook cleared @initialized, GOTCHAS
+        # R1). A slot still holding one of these is foam's OWN to re-own
+        # (retiring the inherited pipelines and minting a fresh resource — a
+        # NEW service.instance.id per worker, section 0); a genuinely foreign
+        # provider is never touched.
+        inherited = @foam_providers.dup
+        @inherited_retired = false
         resource = Resource.build(config)
         headers = { "Authorization" => "Bearer #{token}" }
         instance = Instance.new(config)
 
-        register_free_signal(:traces, verdicts[:traces], instance) do
+        # Each slot is classified IMMEDIATELY before its own setter — never
+        # as an up-front classify-all pass. Ruby has no atomic set-once
+        # attempt (rule 18 step 4's Ruby row: every setter assigns
+        # unconditionally, so attempt-then-read would DISPLACE an incumbent —
+        # RESEARCH.md §2 / GOTCHAS F7), so a pre-read is forced; classifying
+        # per signal at the last moment keeps the residual pre-read→set race
+        # window as narrow as the platform allows (GOTCHAS F8).
+        traces_verdict = register_free_signal(:traces, instance, inherited) do
           setup_traces(endpoint, headers, resource, config, additional_span_processors)
         end
-        register_free_signal(:logs, verdicts[:logs], instance) do
+        register_free_signal(:logs, instance, inherited) do
           setup_logs(endpoint, headers, resource, config, additional_log_record_processors)
         end
-        register_free_signal(:metrics, verdicts[:metrics], instance) do
+        register_free_signal(:metrics, instance, inherited) do
           setup_metrics(endpoint, headers, resource, config, additional_metric_readers)
         end
 
-        activate_instrumentations(config, additional_instrumentations)
+        activate_instrumentations(config, additional_instrumentations, traces_verdict)
+        activate_floor_extensions
         ForkHooks.install!
 
         at_exit { instance.shutdown }
@@ -124,6 +170,16 @@ module Foam
       end
       # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+      # Called by the fork hook IN THE CHILD: clears the idempotency guard so
+      # the README's per-worker init is honored as a real re-init (the child
+      # then reclaims foam's inherited slots and mints a fresh
+      # service.instance.id — see classify_for_registration). Everything else
+      # is left running for workers that never re-init.
+      def mark_forked!
+        @initialized = false
+      end
+      private :mark_forked!
+
       # Test hook: full reset of module state (NOT for production — OTel
       # globals cannot be cleanly re-registered after a real shutdown).
       def reset_for_tests!
@@ -132,28 +188,118 @@ module Foam
         @foam_providers = []
         @flushables = []
         @metric_readers = []
+        @ingest_taps = []
         @foam_registered = {}
         @displacement_warned = {}
+        @inherited_retired = false
         self.active_config = blank_config
         Metrics.reset_for_tests!
+        RuntimeMetrics.reset_for_tests!
       end
 
       private
 
-      # Registers into a FREE slot; warns once (honestly) for a CLAIMED one and
-      # touches nothing (rule 18, steps 2-3).
-      def register_free_signal(signal, verdict, instance)
+      # Classifies the slot IMMEDIATELY before registering into it (the
+      # narrowest pre-read→set window Ruby's non-atomic globals allow —
+      # GOTCHAS F8), registers into a FREE slot, and warns once (honestly)
+      # for a CLAIMED one, touching nothing (rule 18, steps 2-3). Returns the
+      # verdict so init can gate instrumentation activation on traces.
+      def register_free_signal(signal, instance, inherited)
+        verdict = classify_for_registration(signal, inherited)
         if verdict.free?
           provider = yield
           if provider
             instance.providers << provider
             @foam_registered[signal] = provider # for the late-arrival re-check
           end
+        elsif verdict.unclassifiable?
+          warn_unclassifiable(signal)
         else
           warn_claimed(signal, verdict.owner)
         end
+        verdict
       rescue StandardError => e
         Diagnostics.warn("#{signal} setup failed: #{e.class}: #{e.message}")
+        verdict || Verdict.new(false, Classifier::UNCLASSIFIABLE)
+      end
+
+      # rule 42 degraded path (GOTCHAS G14): the FREE predicate itself is
+      # unavailable — say THAT, loudly and accurately, instead of fabricating
+      # a foreign-owner verdict. Foam registers nothing (fail-safe).
+      def warn_unclassifiable(signal)
+        Diagnostics.warn(
+          "foam cannot classify the #{signal} slot on this OpenTelemetry API version " \
+          "(OpenTelemetry::Internal proxy constant missing — the installed API changed shape). " \
+          "Foam registered NOTHING for #{signal} (fail-safe) and is DARK for #{signal}. " \
+          "Check the installed opentelemetry-api version against foam's supported range (README), " \
+          "or file this with foam support."
+        )
+      end
+
+      # The per-signal pre-read, taken as LATE as possible. A CLAIMED verdict
+      # whose live provider is one foam itself registered in the parent
+      # process (inherited across a fork after the fork hook cleared
+      # @initialized) is foam's to re-own: the inherited pipelines are
+      # retired once — their export threads died with the fork — and the slot
+      # is treated as FREE so the re-init rebuilds it with a freshly minted
+      # resource (GOTCHAS R1).
+      def classify_for_registration(signal, inherited)
+        verdict = Classifier.classify_signal(signal)
+        return verdict if verdict.free? || verdict.unclassifiable?
+
+        live = live_provider(signal)
+        return verdict unless inherited.any? { |p| p.equal?(live) }
+
+        retire_inherited_pipelines!
+        Verdict.new(true, nil)
+      end
+
+      def live_provider(signal)
+        case signal
+        when :traces then OpenTelemetry.tracer_provider
+        when :metrics then OpenTelemetry.meter_provider
+        when :logs then OpenTelemetry.logger_provider
+        end
+      end
+
+      def retire_inherited_pipelines!
+        return if @inherited_retired
+
+        @inherited_retired = true
+        retire_foam_pipelines!
+      end
+
+      # Shut down and forget every pipeline foam owned in the parent process:
+      # a forked child re-init must not leave inherited readers exporting the
+      # PARENT's service.instance.id beside the new pipelines.
+      # @ingest_taps is deliberately NOT touched: door-2 tap readers belong to
+      # the CUSTOMER'S pipeline and must survive a foam re-init (GOTCHAS R7).
+      def retire_foam_pipelines!
+        begin
+          @instance&.shutdown
+        rescue StandardError
+          nil
+        end
+        @foam_providers = []
+        @flushables = []
+        @metric_readers = []
+        @foam_registered = {}
+        @displacement_warned = {}
+      end
+
+      # Door-2 fork registry (GOTCHAS R7): tap metric readers registered by
+      # the ingest factory, walked by after_fork! beside foam's own readers.
+      def register_ingest_tap!(reader)
+        @ingest_taps << reader
+        nil
+      end
+
+      # Door-2 same-signal double-claim predicate (fleet ruling 2c): true
+      # when init() registered (and therefore exports) this signal to foam.
+      def foam_exports_signal?(signal)
+        @foam_registered[signal] ? true : false
+      rescue StandardError
+        false
       end
 
       # Late-arrival re-check (rule 11 / 18 step 5). Ruby globals are
@@ -178,15 +324,16 @@ module Foam
         nil
       end
 
-      # The honest situation-B warning (rule 18 B): name the owner and the
-      # signal, say where helper telemetry now flows, and that foam ingest for
-      # the claimed signal is not yet available (door 2 is deferred, rule 22a).
+      # The honest situation-B warning (rule 18 B), fleet template W1: name
+      # the owner and the signal, say where helper telemetry now flows, and
+      # point at the matching door-2 ingest entry — the entries shipped, so
+      # the old "not yet available" text would be the banned hollow pointer
+      # (rule 18 B). Text pinned by spec/ingest_spec.rb.
       def warn_claimed(signal, owner)
         Diagnostics.warn(
-          "#{signal} is already owned by #{owner} — foam did NOT register its #{signal} provider " \
-          "and is DARK for #{signal}. #{signal.capitalize} from foam's helpers now flow through " \
-          "that provider, not to foam. Foam ingest for #{signal} is not yet available; feed foam " \
-          "server-side from that pipeline, or file the need."
+          "#{signal} is owned by #{owner} — foam is dark for #{signal}; helper telemetry for it " \
+          "rides the foreign SDK to ITS backend. To also send that pipeline to foam, add one " \
+          "line in THEIR setup: #{Ingest::ENTRY_NAMES.fetch(signal)}. See README \"Door 2\"."
         )
       end
 
@@ -205,6 +352,24 @@ module Foam
                          "— exported verbatim, not rewritten")
       end
 
+      # version is optional by design, but MISSING = warn + continue (section
+      # 0 init table; the README documents this warning): without it,
+      # service.version is absent and deploy correlation is degraded.
+      def warn_missing_version(version)
+        return unless version.nil? || version.to_s.strip.empty?
+
+        Diagnostics.warn("version is missing — continuing without service.version " \
+                         "(recommended: pass your git SHA for deploy correlation)")
+      end
+
+      # The operator kill switch predicate (rule 19), shared by init() and the
+      # door-2 ingest factory. Trimmed + case-insensitive "true" so
+      # OTEL_SDK_DISABLED=TRUE (or " true") kills foam the same way it kills the
+      # rest of the fleet (JS/Python already trim + downcase).
+      def kill_switch_active?
+        ENV["OTEL_SDK_DISABLED"].to_s.strip.downcase == "true"
+      end
+
       # The pinned fleet endpoint, or the operator's OTEL_EXPORTER_OTLP_ENDPOINT
       # override honored with a LOUD warning naming the destination (rule 19).
       def resolve_endpoint
@@ -216,12 +381,53 @@ module Foam
         override.strip.sub(%r{/+\z}, "")
       end
 
+      # The per-signal OTLP endpoint variants are deliberately INERT in foam:
+      # init resolves ONE endpoint and passes it to every exporter
+      # constructor explicitly, and the installed exporters consult the
+      # per-signal vars only when `endpoint:` is nil — so a per-signal var
+      # can never silently split foam's export across destinations (posture
+      # pinned by spec/env_vars_spec.rb; surfaced as a spec-table divergence
+      # in GOTCHAS F2). An operator who SET one expected a redirect, and
+      # silently not applying it is the rule-15 failure mode — say it loudly.
+      def warn_inert_per_signal_endpoints(endpoint)
+        set_vars = {
+          "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT" => ENV["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"],
+          "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT" => ENV["OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"],
+          "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT" => ENV["OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"],
+        }.reject { |_var, value| value.nil? || value.strip.empty? }
+        return if set_vars.empty?
+
+        Diagnostics.warn(
+          "#{set_vars.keys.join(', ')} set but INERT — foam wires one resolved endpoint into every " \
+          "exporter explicitly, so per-signal OTLP endpoint vars never redirect foam's export " \
+          "(all signals -> #{endpoint}; only OTEL_EXPORTER_OTLP_ENDPOINT is honored — README env table)"
+        )
+      end
+
       # OTEL_PROPAGATORS handling (rule 17 / env table). Foam bypasses
       # SDK.configure, which is the only thing that reads this var, so foam
       # implements it: `none` installs a no-op propagator (injection off,
       # telemetry keeps flowing); the default is W3C TraceContext + Baggage;
       # any other value warns and is ignored (foam's propagator set is fixed).
+      #
+      # The propagation slot is a process-wide last-write-wins global (rule
+      # 18 B): "a foreign owner keeps them". Foam installs its set ONLY when
+      # the slot still holds the API's built-in default (NoopTextMapPropagator
+      # — the exact default the API's reader memoizes); a propagator a
+      # foreign SDK installed first is KEPT, with one honest warning —
+      # displacing it would sever the customer's B3/Jaeger/X-Ray propagation
+      # in THEIR OWN product (GOTCHAS F5).
       def configure_propagation
+        current = OpenTelemetry.propagation
+        unless current.instance_of?(OpenTelemetry::Context::Propagation::NoopTextMapPropagator)
+          Diagnostics.warn(
+            "a propagator is already installed (#{current.class}) — foam KEPT it and did not " \
+            "install its W3C tracecontext+baggage set (rule 18: a foreign owner keeps the " \
+            "process-wide propagator). Inbound/outbound context rides the incumbent's formats."
+          )
+          return
+        end
+
         value = ENV["OTEL_PROPAGATORS"]&.strip
         if value == "none"
           Diagnostics.warn("OTEL_PROPAGATORS=none — trace propagation is OFF (links lost); telemetry still flows")
@@ -248,13 +454,47 @@ module Foam
         require "opentelemetry-exporter-otlp-metrics"
       end
 
+      # The central RAW-capture activation config (raised-floor ruling
+      # 2026-07-26): the upstream datastore instrumentations default
+      # db_statement to :obfuscate — a sanitizer, which the zero-default-
+      # redaction ruling explicitly disables. Foam activates them with
+      # `db_statement: :include` so raw SQL / redis args / mongo commands
+      # land on the wire; masking happens ONLY for customer-listed redact
+      # keys at foam's redaction stage. Keys are registry instrumentation
+      # names; entries whose target gem is absent are simply never installed
+      # (rule 6 presence checks are the gems' own).
+      FLOOR_INSTRUMENTATION_CONFIG = {
+        "OpenTelemetry::Instrumentation::PG" => { db_statement: :include }.freeze,
+        "OpenTelemetry::Instrumentation::Mysql2" => { db_statement: :include }.freeze,
+        "OpenTelemetry::Instrumentation::Redis" => { db_statement: :include }.freeze,
+        "OpenTelemetry::Instrumentation::Mongo" => { db_statement: :include }.freeze,
+      }.freeze
+
       # Tier-1/2 activation (rules 5-7): install every bundled official
       # opentelemetry-instrumentation-* gem, presence-checked by the gem
       # itself. The outbound loop guard (rule 24) is wired by pre-installing
       # the HTTP-client instrumentations with untraced_hosts = the export host
       # + ignored_outbound_hosts BEFORE install_all (install is idempotent, so
       # the later install_all skips the ones already configured).
-      def activate_instrumentations(config, additional)
+      #
+      # GATED on the traces verdict (rule 18 B): every contrib instrumentation
+      # binds its tracer to the CURRENT global — when a FOREIGN SDK owns the
+      # tracer slot, install_all would silently add span producers (and Rack
+      # middleware) to the incumbent's pipeline, on their vendor's bill. Foam
+      # registers NOTHING into a claimed pipeline: automatic activation is
+      # skipped with a loud warning. `additional_instrumentations` instances
+      # are the FDE's EXPLICIT choice and are still installed.
+      def activate_instrumentations(config, additional, traces_verdict)
+        unless traces_verdict.free?
+          Diagnostics.warn(
+            "foam does not own the traces slot — automatic instrumentation activation SKIPPED " \
+            "(foam adds no span producers or middleware to a pipeline it does not own; rule 18 B). " \
+            "additional_instrumentations passed explicitly are still installed."
+          )
+          install_additional(additional)
+          return
+        end
+
         gems = Gem.loaded_specs.keys.grep(/\Aopentelemetry-instrumentation-/)
         gems.each do |name|
           require name
@@ -265,12 +505,43 @@ module Foam
 
         configure_loop_guard(config)
         install_additional(additional)
-        OpenTelemetry::Instrumentation.registry.install_all
+        OpenTelemetry::Instrumentation.registry.install_all(FLOOR_INSTRUMENTATION_CONFIG)
         Diagnostics.info("instrumentations installed: #{gems.length} bundled gem(s)")
       rescue StandardError => e
         Diagnostics.warn("instrumentation activation failed: #{e.class}: #{e.message}")
       end
 
+      # The non-contrib floor pieces (raised-floor ruling 2026-07-26). Each
+      # activation is gated on foam OWNING the slot its telemetry flows into
+      # (rule 18 B: never a new producer on a foreign pipeline), presence-
+      # checked, and fault-isolated — a broken piece warns and the rest of
+      # init proceeds (rule 9: never abort boot).
+      def activate_floor_extensions
+        if foam_exports_signal?(:logs)
+          begin
+            LoggerBridge.install!
+          rescue StandardError => e
+            Diagnostics.warn("stdlib Logger bridge activation failed: #{e.class}: #{e.message}")
+          end
+        end
+
+        if (meter_provider = @foam_registered[:metrics])
+          begin
+            RuntimeMetrics.install!(meter_provider)
+          rescue StandardError => e
+            Diagnostics.warn("runtime metrics activation failed: #{e.class}: #{e.message}")
+          end
+        end
+
+        return unless foam_exports_signal?(:traces)
+
+        begin
+          LLM.activate!
+        rescue StandardError => e
+          Diagnostics.warn("LLM shim activation failed: #{e.class}: #{e.message}")
+        end
+      end
+
       # Pre-install the HTTP-client instrumentations with untraced_hosts so
       # foam's exports and FDE-listed hosts never produce outbound spans.
       # Each entry is the Instrumentation *class* (…::Instrumentation), not the
@@ -278,12 +549,26 @@ module Foam
       # the trailing ::Instrumentation the NameError/NoMethodError is swallowed
       # and install_all then installs with default untraced_hosts: [] — the
       # export-loop guard and ignored_outbound_hosts silently never apply.
+      #
+      # ONLY the clients whose upstream instrumentation DECLARES the
+      # `untraced_hosts` option: Net::HTTP (option :untraced_hosts) and Excon
+      # (Concerns::UntracedHosts). Faraday, HTTP (httprb) and HTTPX declare NO
+      # such option — Base#config_options silently DROPS unknown keys
+      # (instrumentation-base base.rb), so pre-installing them would install
+      # UNGUARDED with foam's option discarded; foam instead warns that
+      # ignored_outbound_hosts cannot apply to them (GOTCHAS G13).
       HTTP_CLIENT_INSTRUMENTATIONS = %w[
         OpenTelemetry::Instrumentation::Net::HTTP::Instrumentation
+        OpenTelemetry::Instrumentation::Excon::Instrumentation
+      ].freeze
+
+      # Bundled HTTP-client instrumentations that CANNOT honor untraced_hosts
+      # upstream — named so init can warn (never silently not-apply) when the
+      # FDE wires ignored_outbound_hosts while one of these is present.
+      UNGUARDABLE_HTTP_CLIENT_INSTRUMENTATIONS = %w[
         OpenTelemetry::Instrumentation::Faraday::Instrumentation
         OpenTelemetry::Instrumentation::HTTP::Instrumentation
         OpenTelemetry::Instrumentation::HTTPX::Instrumentation
-        OpenTelemetry::Instrumentation::Excon::Instrumentation
       ].freeze
 
       def configure_loop_guard(config)
@@ -293,9 +578,41 @@ module Foam
         HTTP_CLIENT_INSTRUMENTATIONS.each do |const|
           klass = const.split("::").reduce(Object) { |mod, name| mod.const_get(name) }
           klass.instance.install(untraced_hosts: hosts)
-        rescue NameError, StandardError
-          nil
+        rescue NameError
+          # The gem is simply not bundled — the expected path; narrate it only
+          # under diagnostics (rule 15: a swallowed error still logs).
+          Diagnostics.info("loop guard: #{const} not present — skipped")
+        rescue StandardError => e
+          # A PRESENT client whose pre-install failed: the guard silently not
+          # applying was the 1.0.0 bug's hiding mechanism — never again (rule 15).
+          Diagnostics.warn("loop guard: could not pre-configure #{const} (#{e.class}: #{e.message}) — " \
+                           "outbound calls from that client to #{hosts.join(', ')} may still produce spans")
+        end
+        warn_unguardable_clients(config)
+      end
+
+      # ignored_outbound_hosts silently not applying is a feedback-loop risk
+      # (rule 24 / rule 18 C.4): when the FDE listed hosts and a bundled
+      # HTTP-client instrumentation has no untraced_hosts support upstream,
+      # say so loudly once at init (GOTCHAS G13). Foam's OWN export loop is
+      # safe regardless — the OTLP exporters send inside Common::Utilities
+      # .untraced (GOTCHAS G4).
+      def warn_unguardable_clients(config)
+        return if config.ignored_outbound_hosts.empty?
+
+        present = UNGUARDABLE_HTTP_CLIENT_INSTRUMENTATIONS.select do |const|
+          Object.const_defined?(const)
+        rescue NameError
+          false
         end
+        return if present.empty?
+
+        names = present.map { |const| const.split("::")[-2] }.join(", ")
+        Diagnostics.warn(
+          "ignored_outbound_hosts cannot be applied to #{names} — the upstream instrumentation has " \
+          "no untraced_hosts option, so calls made through #{names} to the listed hosts WILL still " \
+          "produce spans (see GOTCHAS G13; foam's own export loop stays guarded regardless)"
+        )
       end
 
       def endpoint_host(endpoint)

data/lib/foam/otel/instance.rb

@@ -30,7 +30,10 @@ module Foam
         @providers.each do |provider|
           begin
             provider.shutdown
-          rescue StandardError
+          rescue StandardError, SystemStackError
+            # SystemStackError is not a StandardError; a poisoned payload deep
+            # in a pipeline must never escape through the at_exit hook into
+            # the customer's process teardown (rule 9).
             nil
           end
           Foam::Otel.send(:forget_provider, provider)