foam-otel 1.0.2 → 1.2.0

data/RESEARCH.md

@@ -58,8 +58,13 @@ record_histogram/add_up_down_counter/set_metric`, `log`, `redact`,
 
 **Context / Baggage / Propagation** — excluded from the helper surface (low-level
 plumbing): `Context.*` (`context.rb`), `Baggage.*` (`baggage.rb`), and
-`OpenTelemetry.propagation` which foam SETS at init (W3C TraceContext + Baggage,
-`lib/foam/otel/init.rb`). Reachable through the passthroughs where needed.
+`OpenTelemetry.propagation`, which foam sets at init (W3C TraceContext + Baggage,
+`lib/foam/otel/init.rb`) ONLY when the slot still holds the API's built-in
+default (`NoopTextMapPropagator`, memoized by the reader —
+`opentelemetry-api opentelemetry.rb:69-71`); the slot is a last-write-wins
+global (`attr_writer :propagation`, `opentelemetry.rb:27`), so a propagator a
+foreign SDK installed first is KEPT with one warning (rule 18 B: "a foreign
+owner keeps them" — GOTCHAS F5). Reachable through the passthroughs where needed.
 
 **Lifecycle** (`init/flush/shutdown/after_fork!`) and `redact` are foam-composed
 (no single API primitive): providers' `shutdown`/`force_flush`, the OTLP
@@ -105,29 +110,58 @@ consumer) or tier-2 (patch/prepend). foam activates by presence: `init` greps
 `Gem.loaded_specs` for `opentelemetry-instrumentation-*`, requires each, and
 calls `registry.install_all` (each gem presence-checks its own target). foam
 maintains **no per-gem allow/deny list** — activation is bundle-driven
-(`lib/foam/otel/init.rb`).
-
-**Always-activated (foam bundles them):** `-rack` (direct) + the `-rails 0.42.0`
-meta-gem, which pulls `-action_pack`, `-action_view`, `-action_mailer`,
-`-active_record`, `-active_job`, `-active_storage`, `-active_support`,
-`-concurrent_ruby`. Non-Rails apps get inert presence-check skips.
-
-**Activated-when-present (FDE bundles, foam auto-installs):** HTTP clients
-(`-net_http`, `-faraday`, `-http`, `-http_client`, `-httpx`, `-excon`, `-ethon`,
-`-restclient`), datastores (`-pg`, `-mysql2`, `-trilogy`, `-redis`, `-dalli`,
-`-mongo`, `-lmdb`), messaging (`-bunny`, `-rdkafka`, `-racecar`,
-`-ruby_kafka`), jobs (`-sidekiq`, `-resque`, `-delayed_job`, `-que`), web/rpc
-(`-sinatra`, `-grape`, `-graphql`, `-grpc`, `-gruf`), and `-aws_sdk`,
-`-aws_lambda`, `-koala`, `-active_model_serializers`, `-rake`, `-anthropic`
-(context-propagation only — see §5), plus the stdlib `-logger` bridge (§4).
-
-`install_all` runs each instrumentation with its DEFAULT config — foam sets no
-per-gem options. For the PHI-sensitive datastores (`-pg` full SQL text,
-`-redis` keys/values), the integration MUST set `db_statement: :omit` (or a
-verified `:obfuscate`) via the standard `OTEL_RUBY_INSTRUMENTATION_<NAME>_CONFIG_OPTS`
-env var so raw statements/keys never ship. This is integration configuration,
-not a foam default (there is no `db_statement` anywhere in `lib/`); graduating
-it into the package would need real-backend e2e per the NOT-TESTED bar.
+(`lib/foam/otel/init.rb`). Activation is GATED on the traces verdict (rule
+18 B): when a foreign SDK owns the tracer slot, `init` installs NOTHING
+automatically (every contrib gem binds its tracer to the live global — the
+foreign provider) and warns once; explicit `additional_instrumentations` still
+install (`spec/activation_spec.rb` claimed-traces cases).
+
+**Always-activated (foam bundles them — the UNIVERSAL FLOOR, landed):**
+`-rack` (direct) + the `-rails 0.42.0` meta-gem (pulls `-action_pack`,
+`-action_view`, `-action_mailer`, `-active_record`, `-active_job`,
+`-active_storage`, `-active_support`, `-concurrent_ruby`); the HTTP clients
+`-net_http 0.29.0` and `-faraday 0.33.0`; the primary datastores `-pg 0.36.0`,
+`-mysql2 0.34.0`, `-redis 0.29.0`, `-mongo 0.26.0`; and `-sidekiq 0.29.0` —
+verified against the gemspec, the ground truth. Every entry is
+presence-checked, so a gem whose target library is absent is an inert skip
+(a non-Rails app skips the Rails family; an app without Postgres skips `-pg`;
+and so on). The landed floor also includes foam's own non-contrib pieces: the
+stdlib **Logger bridge** (§4), hand-written **runtime + GC metrics** (below),
+**session stitching** (baggage→attributes), and the **LLM shims** (§5).
+
+**Activated-when-present (FDE bundles the long tail, foam auto-installs):** the
+remaining HTTP clients (`-http`, `-http_client`, `-httpx`, `-excon`, `-ethon`,
+`-restclient`), datastores (`-trilogy`, `-dalli`, `-lmdb`),
+messaging (`-bunny`, `-rdkafka`, `-racecar`, `-ruby_kafka`), jobs (`-resque`,
+`-delayed_job`, `-que`), web/rpc (`-sinatra`, `-grape`, `-graphql`, `-grpc`,
+`-gruf`), and `-aws_sdk`, `-aws_lambda`, `-koala`,
+`-active_model_serializers`, `-rake`, `-anthropic` (context-propagation only —
+see §5).
+
+`install_all` receives foam's CENTRAL raw-capture config
+(`FLOOR_INSTRUMENTATION_CONFIG`, `lib/foam/otel/init.rb`): the datastore
+statement posture is **captured RAW, never suppressed** (2026-07-26 ruling —
+coverage is the mission), and the upstream `-pg`/`-mysql2`/`-redis`/`-mongo`
+gems all DEFAULT to `db_statement: :obfuscate` — a sanitizer — so foam
+explicitly activates them with `db_statement: :include` (GOTCHAS F9; pinned
+by `spec/floor_spec.rb`). Redaction stays fully opt-in, applied only for keys
+the customer lists in `redact_keys`/`redact_pii_keys`. An FDE can still clamp
+`db_statement: :omit`/`:obfuscate` per customer via the standard
+`OTEL_RUBY_INSTRUMENTATION_<NAME>_CONFIG_OPTS` env var when a compliance
+context calls for it — per-customer tightening (rule 18 / Area 4), not the
+default.
+
+**Runtime + GC metrics (hand-written — landed,
+`lib/foam/otel/runtime_metrics.rb`).** Ruby has no drop-in upstream metrics
+instrumentation gem (unlike Python's `-system-metrics` or the Node
+host-metrics package), so foam ships its OWN collector: asynchronous
+observable instruments over `GC.stat` / `Thread.list` / `/proc`, emitting GC
+counts + timing, heap slots, allocation/free totals, thread count, and RSS
+(`process.runtime.ruby.*` + `process.memory.usage`). Registered by `init`
+when foam owns the metrics slot; collection runs on the
+`PeriodicMetricReader`'s thread, which foam's `Process._fork` hook restarts
+in cluster workers (GOTCHAS R1/R7/G15). No labels at all — safe by
+construction (rule 26). Tests: `spec/runtime_metrics_spec.rb`.
 
 **Excluded (with reason):** `-factory_bot`, `-rspec` (test-only, no production
 value); `-net_ldap` (niche, PII/credential-adjacent — explicit FDE opt-in);
@@ -148,36 +182,61 @@ Registry: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main
 
 Ruby's Logs signal is "development" (https://opentelemetry.io/docs/languages/ruby/).
 foam ships the logs pipeline + `log()` helper (trace-correlated) — the mechanism
-rule 20 requires. **Named logger bridges are correctly deferred.** The only
-official contrib bridge is `opentelemetry-instrumentation-logger 0.4.0` (stdlib
-`Logger`, not bundled today). `Rails.logger`/`TaggedLogging`/`BroadcastLogger`,
-Semantic Logger, Lograge, and Ougai have **no** official OTel appender (the Rails
-logs discussion https://github.com/open-telemetry/opentelemetry-ruby/discussions/1789
-is open/unresolved). Resolves rule 20's TODO(pcga11): the OTel Logs Bridge API
-exists (`opentelemetry-logs-api`) and the stdlib `-logger` bridge covers the
-base, but the framework loggers are not covered — foam's job is activation of
-`-logger` on first demand (tested at add time), plus a documented gap.
+rule 20 requires. The stdlib **Logger bridge is LANDED as foam's own code**
+(`lib/foam/otel/logger_bridge.rb`, console-logs ruling 2026-07-26): one
+prepend on `Logger#add` turns every message a host logger accepts into a
+trace-correlated OTel log record — body RAW (opt-in key-masking only),
+severity mapped, loop-guarded (the OTel SDK's internal logger is skipped by
+identity + a thread-local re-entrancy flag), gated on foam owning the logs
+slot, and never able to break the host's log call (GOTCHAS F10; tests
+`spec/logger_bridge_spec.rb`). Because `Rails.logger`, Sidekiq's logger, and
+Semantic Logger's appenders all bottom out in stdlib `Logger` instances, the
+one prepend covers most framework logging in practice;
+`BroadcastLogger`/Lograge/Ougai-specific appenders remain uncovered upstream
+(the Rails logs discussion
+https://github.com/open-telemetry/opentelemetry-ruby/discussions/1789 is
+open/unresolved) — a documented gap, narrowed to the non-Logger-backed exotics.
 
 ---
 
 ## 5. LLM ecosystem (rule 31)
 
-**No official OpenTelemetry Ruby gen_ai attribute instrumentation exists.** The
-package ships NO LLM surface in v1 (rule 22); this is the classification
-deliverable.
+**No OFFICIAL OpenTelemetry Ruby gen_ai instrumentation exists for ANY LLM
+SDK — foam ships its own thin gap-filler shims (LANDED,
+`lib/foam/otel/llm.rb` + `llm/*_shim.rb`; provider-parity ruling
+2026-07-26: OpenAI + Anthropic + Gemini in every server language).** The
+shims patch the SDKs' public call sites — official `openai`
+(chat.completions.create + responses.create), official `anthropic`
+(messages.create), `gemini-ai` (generate_content / stream_generate_content;
+Google ships no official Ruby SDK), and `ruby_llm` (Provider#complete, one
+seam covering all its providers) — emitting the same GenAI semconv attribute
+set the fleet's js/python gap-fillers emit. **LLM traces are captured in
+full — activity (model, response id, finish reasons, tokens, latency) AND
+prompt/completion content, raw by default** (2026-07-26 ruling: LLM content
+is never gated or dropped; the FDE reactive clamp is the only per-customer
+restriction). Presence-checked, version-windowed, fail-to-dark, one call =
+one span (the SDK transport rides the untraced suppression context), and
+the model call is never breakable by telemetry (GOTCHAS F11). LLM testing is
+MANDATORY and landed: per-provider specs against the REAL SDKs with only the
+3rd party mocked (`spec/llm_openai_spec.rb`, `spec/llm_anthropic_spec.rb`,
+`spec/llm_gemini_spec.rb`, `spec/llm_ruby_llm_spec.rb` — the last is the
+wire-level Gemini proof over a local fake provider).
 
 - `-anthropic` (in the registry / `all` meta-gem) is **context-propagation ONLY**
   — its sole patch stores/restores OTel context across the SDK's connection pool;
   it sets no `gen_ai.*` attributes, captures no tokens/content (CHANGELOG v0.1–0.5
-  are context/semconv/version bumps).
-- `ruby_llm`: **COVERED-tier2** *when the app uses it*, via thoughtbot's
-  **third-party** `opentelemetry-instrumentation-ruby_llm 0.7.0` (not official
-  registry, not bundled — if foam ever ships it, the NOT-TESTED bar + supply-chain
-  review apply).
-- `ruby-openai`, official `openai`, `langchainrb`, Gemini, AWS Bedrock (via
-  `-aws_sdk`, which emits no gen_ai attributes), `llm.rb`: **TIER3-recipe** —
+  are context/semconv/version bumps). Not the LLM-activity vehicle — foam's
+  shim is.
+- `opentelemetry-instrumentation-ruby_llm` (thoughtbot, third-party) exists
+  but is NOT bundled: foam's own `ruby_llm` shim emits the fleet-identical
+  attribute set instead, avoiding a non-registry supply-chain dependency and
+  a cross-language semconv divergence.
+- `ruby-openai` (community gem), `langchainrb`, AWS Bedrock (via `-aws_sdk`,
+  which emits no gen_ai attributes), `llm.rb`: **TIER3-recipe** —
   hand-written spans via helpers + passthroughs with `gen_ai.*` semconv + token
-  counts + trace/log correlation.
+  counts + trace/log correlation. An uncovered library the FDE hits becomes a
+  filed package need (the FDE activates, never authors); until then the tier-3
+  recipe covers it.
 - No mainstream library is CANNOT-COVER — no finding against the helper set.
 
 Sources: contrib `-anthropic` CHANGELOG; https://github.com/thoughtbot/opentelemetry-instrumentation-ruby_llm ;
@@ -186,31 +245,40 @@ https://opentelemetry.io/docs/specs/semconv/gen-ai/aws-bedrock/ ; traceloop Ruby
 
 ---
 
-## 6. Redaction floor provenance (rule 14)
-
-The always-on secrets floor (`lib/foam/otel/constants.rb`) is COPIED KNOWLEDGE,
-never a runtime dependency (rule 38). Matching is SUBSTRING, case-insensitive,
-over a normalized key; the `key`/`sid` roots are REJECTED as bare (they eat
-`idempotency_key`/`cache_key`/`public_key` and `consider`/`president`), and
-`auth`/`card` are token-anchored (miss `author`/`wildcard`/`dashboard`). Two mask
-shapes: secret-key matches → tail mask (`********` + last 4 when ≥ 12 chars; the
-8-char body matches raven-ruby's `STRING_MASK` and PCI's last-4 convention);
-`redact_pii_keys` → full `[REDACTED]`, no tail. A value-pattern pass masks
-prefix-anchored vendor token shapes under unlisted keys. Fail-closed (mask on any
-error, cycle + depth guarded).
-
-Sources consulted (permissive — knowledge copied, never installed): raven-ruby
-(MIT), sentry-python/js (MIT), Elastic APM `sanitize_field_names` (Apache-2.0),
-is-secret (MIT), @zapier/secret-scrubber (ISC — read from pinned pre-2025 CDN,
-never installed), HyperDX (MIT), Instana (Apache-2.0), Rails filter_parameters
-(MIT), OTel Collector redactionprocessor (Apache-2.0), detect-secrets
-(Apache-2.0), secretlint (MIT), gitleaks (MIT). Facts-only (never copy regex
-text): trufflehog (AGPL-3.0). Model of record: the shipped `@foam-ai/otel` Node
-core (`js/otel/src/core/{constants,redaction}.ts`, `js/otel/RESEARCH.md`).
-
-Proven by `spec/redaction_spec.rb` (curated hits/non-hits, both masks, value
-pass, fail-closed) and `spec/redacting_exporter_spec.rb` + the conformance app
-(on the wire).
+## 6. Redaction design record (rule 14, as amended 2026-07-26)
+
+**Redaction is FULLY OPT-IN — the default is ZERO redaction** (owner ruling
+2026-07-26, holistic-redesign decision log; `lib/foam/otel/redaction.rb`).
+With neither `redact_keys` nor `redact_pii_keys` set (or both empty) every
+value is captured RAW — attributes, headers, bodies, URL query params,
+`db.statement`, log bodies — including secrets and PII. There is NO always-on
+secrets floor and NO value-pattern auto-masking; the package auto-masks
+nothing and ships no preset. The customer owns the privacy/legal posture; the
+FDE reactive clamp is the per-customer valve.
+
+**The retired floor**: earlier revisions shipped an always-on researched
+secrets floor in `constants.rb` (roots + value-pattern pass, sourced from the
+OSS-scrubber consensus — raven-ruby, sentry, Elastic APM, Rails
+filter_parameters, gitleaks et al. — modeled on the Node core). It was
+REMOVED by the 2026-07-26 ruling; the provenance record lives in this file's
+git history and the decision log. Do not reintroduce it without a new ruling.
+
+**The current engine** (`redaction.rb`): redaction runs ONLY over the keys
+the customer enumerates. `redact_keys` matches → tail mask, shape-preserving
+(`********` + last 4 when ≥ 12 chars; the fixed 8-char body never reveals
+length; non-scalars redact in full); `redact_pii_keys` matches → full
+`[REDACTED]`, no tail. Matching is SUBSTRING, case-insensitive, over the
+lowercased key — the customer's lists, nothing inferred. The pass runs at the
+exporter boundary (`redacting_exporter.rb` — the Ruby SDK freezes span
+attributes at finish before any `on_finish` processor runs, so the exporter
+boundary is the seam; see GOTCHAS) and is a true pass-through when no keys
+are configured. The explicit `redact(value)` helper always masks (calling it
+is the opt-in). Fail-closed for listed keys (mask on any error, cycle + depth
+guarded).
+
+Proven by `spec/redaction_spec.rb` (opt-in defaults — nothing masked with no
+keys; both mask shapes; fail-closed) and `spec/redacting_exporter_spec.rb` +
+the conformance app (default-path RAW capture on the wire).
 
 ---
 
@@ -226,6 +294,38 @@ upstream SDK components foam builds on.
 
 ---
 
+## 8. Door-2 attach points (ingest entries) — verified at the pinned versions
+
+Ruby is the rare core where every door-2 attach point exists post-construction
+on a foreign provider (the JS >=2.0/Java "only inside their setup" limitation
+does not bite):
+
+- **Traces**: `TracerProvider#add_span_processor`
+  (`V/opentelemetry-sdk-1.13.0/lib/opentelemetry/sdk/trace/tracer_provider.rb:133`);
+  also reachable inside their setup block via
+  `Configurator#add_span_processor` (`configurator.rb:125`).
+- **Logs**: `LoggerProvider#add_log_record_processor`
+  (`V/opentelemetry-logs-sdk-0.6.1/lib/opentelemetry/sdk/logs/logger_provider.rb:62`).
+- **Metrics**: `MeterProvider#add_metric_reader`
+  (`V/opentelemetry-metrics-sdk-0.15.0/.../meter_provider.rb:110-121`) — and
+  it BACK-FILLS: the registry walk registers every already-created instrument
+  with the new reader's `metric_store`, so attach order is forgiving.
+
+Load-bearing internals the taps rely on (each pinned by a test — GOTCHAS
+R5-R8): the `metric_store` seam forcing the `PeriodicMetricReader` subclass;
+shallow-dup'd data points sharing the LIVE aggregation-key attributes hash
+(`aggregation/sum.rb:44-50` — masking must rebuild copies);
+`LogRecord#resource` for self-ingest detection; batch processors converting
+to fresh `SpanData`/`LogRecordData` structs at export (non-mutation is
+structural); all three OTLP exporters sending inside
+`Common::Utilities.untraced` via `Net::HTTP` (the suppression layer of the
+loop story), with the contrib `untraced_hosts` option declared by Net::HTTP
+and Excon only. The logs/metrics SDKs are pre-1.0 — the entries are SHIPPED,
+pinned inside the capped ranges (GOTCHAS R2/R5) so a 0.x drift is a deliberate
+re-prove; the pre-1.0 maturity is a version-pin caveat, not a deferral.
+
+---
+
 ## Signatures
 
 | Reviewer | Date | Package version | Notes |

data/THIRD-PARTY-NOTICES

@@ -10,17 +10,21 @@ redistributes).
 Foam thanks the OpenTelemetry authors and community
 (https://opentelemetry.io) — this package is built on their work.
 
-The always-on redaction floor (lib/foam/otel/constants.rb) is COPIED KNOWLEDGE,
-not vendored code (rule 38): its key roots and value-pattern shapes were
-researched from the published defaults of permissively-licensed open-source
-scrubbers (Sentry / raven-ruby MIT, Elastic APM Apache-2.0, is-secret MIT,
-@zapier/secret-scrubber ISC, HyperDX MIT, detect-secrets Apache-2.0, secretlint
-MIT, gitleaks MIT) and Rails' filter_parameters (MIT). Token FORMATS are facts,
-not copyrightable; no regex text was copied from any AGPL source. None of these
-libraries is a runtime dependency of foam-otel. Provenance: RESEARCH.md.
+The OPT-IN redaction mask shapes (lib/foam/otel/constants.rb — the 8-char
+MASK_BODY and tail-mask convention applied only to customer-listed
+redact_keys/redact_pii_keys; foam redacts NOTHING by default) are COPIED
+KNOWLEDGE, not vendored code (rule 38): the shapes were researched from the
+published conventions of permissively-licensed open-source scrubbers
+(raven-ruby MIT STRING_MASK precedent among them) and Rails'
+filter_parameters (MIT). Mask FORMATS are facts, not copyrightable; no code
+was copied. None of these libraries is a runtime dependency of foam-otel.
+Provenance: RESEARCH.md.
 
 Direct runtime dependencies (name version — license — repository):
 
+  opentelemetry-api 1.11.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby
+  opentelemetry-metrics-api 0.6.1 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby
+  opentelemetry-logs-api 0.4.1 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby
   opentelemetry-sdk 1.13.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby
   opentelemetry-exporter-otlp 0.34.1 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby
   opentelemetry-logs-sdk 0.6.1 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby
@@ -29,10 +33,17 @@ Direct runtime dependencies (name version — license — repository):
   opentelemetry-exporter-otlp-metrics 0.10.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby
   opentelemetry-instrumentation-rack 0.31.1 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
   opentelemetry-instrumentation-rails 0.42.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
+  opentelemetry-instrumentation-net_http 0.29.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
+  opentelemetry-instrumentation-faraday 0.33.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
+  opentelemetry-instrumentation-pg 0.36.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
+  opentelemetry-instrumentation-mysql2 0.34.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
+  opentelemetry-instrumentation-redis 0.29.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
+  opentelemetry-instrumentation-mongo 0.26.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
+  opentelemetry-instrumentation-sidekiq 0.29.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby-contrib
 
 The opentelemetry-instrumentation-rails meta-gem transitively pulls the Rails
 instrumentation family (action_pack, action_view, action_mailer, active_record,
 active_job, active_storage, active_support, concurrent_ruby), each Apache-2.0,
 from https://github.com/open-telemetry/opentelemetry-ruby-contrib. Additional
-opentelemetry-instrumentation-* gems the FDE bundles are the customer's declared
-dependencies, not foam's.
+opentelemetry-instrumentation-* gems the FDE bundles beyond the floor above are
+the customer's declared dependencies, not foam's.

data/lib/foam/otel/api.rb

@@ -43,53 +43,104 @@ module Foam
       def get_logger(name = "foam")
         provider = OpenTelemetry.logger_provider
         warn_if_displaced(:logs, provider)
-        provider.logger(name: name)
+        # Never register into the PRE-INIT proxy registry (GOTCHAS L1): the
+        # logs-api 0.4.1 ProxyLoggerProvider#delegate= upgrades cached proxy
+        # loggers with a POSITIONAL provider.logger(name, version) call, but
+        # the logs SDK's #logger is keyword-only — one cached proxy logger
+        # makes init's logger_provider assignment raise and would leave the
+        # logs pipeline dark for the process. Pre-init logs are a silent
+        # no-op by contract, so hand back the API's no-op Logger directly.
+        # (Same feature-detected Internal read as the classifier — rule 42,
+        # GOTCHAS G14; when the constant is missing this check degrades to
+        # the plain provider call below.)
+        if defined?(OpenTelemetry::Internal::ProxyLoggerProvider) &&
+           provider.instance_of?(OpenTelemetry::Internal::ProxyLoggerProvider)
+          return noop_logger
+        end
+
+        begin
+          provider.logger(name: name) # the logs SDK's keyword-only signature
+        rescue ArgumentError
+          provider.logger(name) # a positional-signature (older/foreign) provider
+        end
       end
 
       # ---- traces ----------------------------------------------------------
 
       # A custom span around a block. Re-raises the block's error identically,
       # records the exception + ERROR status, and ALWAYS ends the span (rule 9
-      # / never-ended-span leak). Safe pre-init (no-op span).
+      # / never-ended-span leak). Safe pre-init (no-op span). Argument
+      # preparation NEVER throws (rule 9): garbage attributes degrade to nil,
+      # a poisoned name to "unnamed" — the block always runs and only ITS
+      # error re-raises. When foam is initialized disabled, the block runs on
+      # a non-recording no-op span: disabled beats everything, including
+      # inert-mode emission through a foreign provider (section 0).
       def span(name, attributes: nil, &block)
-        get_tracer.in_span(name.to_s, attributes: stringify(attributes), &block)
+        span_name = begin
+          name.to_s
+        rescue StandardError, SystemStackError
+          # SystemStackError is not a StandardError: a name object whose #to_s
+          # recurses unboundedly must degrade to "unnamed", never escape into
+          # the customer's thread (rule 9).
+          "unnamed"
+        end
+        return noop_tracer.in_span(span_name, &block) if helpers_disabled?
+
+        get_tracer.in_span(span_name, attributes: stringify(attributes), &block)
       end
 
       # Records an exception on the active span (status ERROR) when one is
       # recording. Accepts customer error classes; NEVER notifies a vendor
       # tracker. Deduped per span. Never raises.
       def record_exception(error)
+        return nil if helpers_disabled?
+
         Errors.record_once(OpenTelemetry::Trace.current_span, error)
         nil
       end
 
       def set_attribute(key, value)
+        return false if helpers_disabled?
+
         span = OpenTelemetry::Trace.current_span
         return false unless span.respond_to?(:recording?) && span.recording?
 
-        span.set_attribute(key.to_s, value)
+        # Capture-time key pass (rule 18 C.3): when the customer configured
+        # redact_keys/redact_pii_keys the value lands ALREADY-MASKED, so tenant
+        # processors and inert-mode providers only ever see the redacted view of
+        # helper-set data. The exporter pass re-applies (idempotent). With no
+        # keys configured this is a pass-through — the value is captured RAW.
+        # scrub_utf8 is encoding hygiene, not masking: an invalid-UTF-8 value
+        # would make the upstream OTLP encoder drop the WHOLE batch (rule 15).
+        span.set_attribute(key.to_s, Redaction.mask_one(key.to_s, Redaction.scrub_utf8(value), active_config))
         true
-      rescue StandardError
+      rescue StandardError, SystemStackError
+        # SystemStackError is not a StandardError: a poisoned key/value (e.g. a
+        # recursive #to_s/#hash) must never crash the caller's thread (rule 9).
         false
       end
 
       def set_attributes(attributes)
+        return false if helpers_disabled?
+
         span = OpenTelemetry::Trace.current_span
         return false unless span.respond_to?(:recording?) && span.recording?
 
         span.add_attributes(stringify(attributes))
         true
-      rescue StandardError
+      rescue StandardError, SystemStackError
         false
       end
 
       def add_event(name, attributes: nil)
+        return false if helpers_disabled?
+
         span = OpenTelemetry::Trace.current_span
         return false unless span.respond_to?(:recording?) && span.recording?
 
         span.add_event(name.to_s, attributes: stringify(attributes))
         true
-      rescue StandardError
+      rescue StandardError, SystemStackError
         false
       end
 
@@ -101,7 +152,7 @@ module Foam
         return nil if ctx.nil? || !ctx.valid?
 
         { trace_id: ctx.hex_trace_id, span_id: ctx.hex_span_id }
-      rescue StandardError
+      rescue StandardError, SystemStackError
         nil
       end
 
@@ -128,15 +179,17 @@ module Foam
       # is an OTel severity NUMBER (1..24) or a level symbol (:info, :warn,
       # :error, :debug, :fatal, :trace). Safe pre-init (no-op). Never raises.
       def log(severity, body, attributes: nil)
+        return true if helpers_disabled? # disabled means fully dark — accepted, silently dropped
+
         get_logger.on_emit(
           severity_number: severity_number(severity),
           severity_text: severity_text(severity),
-          body: body,
+          body: mask_log_body(body),
           attributes: stringify(attributes),
           context: OpenTelemetry::Context.current
         )
         true
-      rescue StandardError
+      rescue StandardError, SystemStackError
         false
       end
 
@@ -153,7 +206,10 @@ module Foam
       def flush
         (@flushables || []).dup.each do |flushable|
           flushable.force_flush
-        rescue StandardError
+        rescue StandardError, SystemStackError
+          # SystemStackError is not a StandardError: a poisoned (e.g. cyclic)
+          # payload deep in a pipeline must still never escape into the
+          # customer's thread (rule 9).
           nil
         end
         nil
@@ -165,16 +221,19 @@ module Foam
       def shutdown
         @instance&.shutdown
         nil
-      rescue StandardError
+      rescue StandardError, SystemStackError
         nil
       end
 
       # Restart foam's PeriodicMetricReader export threads after a fork (the
       # trace/log batch processors self-heal on their own — GOTCHAS R1).
-      # Called automatically by foam's Process._fork hook; also safe to call
-      # from Puma on_worker_boot / Unicorn after_fork.
+      # Walks BOTH registries: foam's own door-1 readers AND the door-2
+      # @ingest_taps registry (kept separate so a post-fork re-init that
+      # retires foam's pipelines never orphans a tap riding the CUSTOMER'S
+      # pipeline — GOTCHAS R7). Called automatically by foam's Process._fork
+      # hook; also safe to call from Puma on_worker_boot / Unicorn after_fork.
       def after_fork!
-        (@metric_readers || []).each do |reader|
+        ((@metric_readers || []) + (@ingest_taps || [])).each do |reader|
           reader.after_fork if reader.respond_to?(:after_fork)
         rescue StandardError
           nil
@@ -201,10 +260,59 @@ module Foam
         LEVEL_TEXT[severity.to_s.downcase.to_sym]
       end
 
+      # Stringify keys, then apply the customer's key lists AT CAPTURE (rule 18
+      # C.3): when redact_keys/redact_pii_keys are configured, helper-set
+      # attributes are ALREADY-MASKED when they reach the span/log record, so a
+      # tenant processor (or a foreign provider in inert mode) only ever sees the
+      # redacted view of foam-helper data. The exporter-boundary pass re-applies
+      # — masking is idempotent. With no keys configured this is a pass-through
+      # (raw capture). NEVER throws (rule 9): non-enumerable garbage degrades to
+      # nil (attributes dropped, telemetry still flows).
       def stringify(attributes)
         return nil if attributes.nil?
 
-        attributes.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+        # scrub_utf8 per value: encoding hygiene at capture (see set_attribute
+        # — one invalid-UTF-8 value kills its whole OTLP batch upstream).
+        stringified = attributes.each_with_object({}) { |(k, v), out| out[k.to_s] = Redaction.scrub_utf8(v) }
+        Redaction.mask_attributes(stringified, active_config)
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # The customer key pass over a log BODY at capture (same rationale as
+      # stringify). When keys are configured mask_body is fail-closed and
+      # depth-guarded, so a cyclic structure is bounded before it can reach any
+      # encoder; with no keys configured the body is captured RAW.
+      def mask_log_body(body)
+        return body if body.nil?
+
+        Redaction.mask_body(Redaction.scrub_utf8(body), active_config)
+      rescue StandardError, SystemStackError
+        # Fail CLOSED on a masking failure: in inert mode (a foreign SDK owns
+        # logs) the capture-time pass is the ONLY pass on foam-helper log
+        # bodies, so returning the raw String after a mask error would ship a
+        # half-processed body — REDACTED for every body type instead.
+        REDACTED
+      end
+
+      # section 0: "enabled: false beats everything — including inert-mode
+      # emission. Disabled means fully dark." Helpers consult the resolved
+      # config once foam is initialized; before init the proxy providers
+      # already make them silent no-ops (and a foreign pre-init provider is
+      # the pre-init passthrough contract, unchanged).
+      def helpers_disabled?
+        @initialized && !active_config.enabled
+      end
+
+      # The API's no-op tracer: in_span still yields a (non-recording) span
+      # and re-raises only the block's own error — nothing is emitted.
+      def noop_tracer
+        @noop_tracer ||= OpenTelemetry::Trace::Tracer.new
+      end
+
+      # The API's no-op logger (see get_logger / GOTCHAS L1).
+      def noop_logger
+        @noop_logger ||= OpenTelemetry::Logs::Logger.new
       end
     end
   end