foam-otel 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4e3f8240b1b181676669710856d6f7a2cd6c95ebf34c7598b1197a2b54c3de7
-  data.tar.gz: c81e51f8331c9d60ed0f59e1638a220a1943429c41496af77b27877d35deeaad
+  metadata.gz: bb41e8c47c944ac8f252f47bededb07f8c73e152411f3a7069a8fcab3d1185a2
+  data.tar.gz: ab93229a7820e4b60439d8c30f903fd3d1be93a8d2dd723b032862813ac4278f
 SHA512:
-  metadata.gz: 2f2ea8f51b7ccc19bc042a360e4892d5d7a75bf7c19ab06f27ef104782e063333dd2f22eef34a3ee0b0034256005db3398f5ffeb5a943f8bec4354c44bf33fba
-  data.tar.gz: 830a7a9c6ac02f4168a6575c14f9d373b9781c50d5e6feda19a23d3da114bd4a440259ff53b573653e6b3321a081ed2cc181f3899959738d80da336378730f9a
+  metadata.gz: 291f81494a360ee3ce94a09b6b98dafde0574e4078d61ec01bb3e3e3b7803a4f7034bc36ef17a33db79cbb886ad5c0d337c2ffa75762c5a9d04f52e89cdf6669
+  data.tar.gz: e81c1c075606402562ee74a8dc6752dd4d96f4b73235303a43cd0d20569ca7238a031b3c6c6d6726f5cf3f3c32858c2452cc5cbfac8ffd61f834f549738c6c1b

data/GOTCHAS.md

@@ -8,7 +8,10 @@ those tests.
 
 Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
 1.13.0, -logs-sdk 0.6.1, -metrics-sdk 0.15.0, -api 1.11.0, -exporter-otlp 0.34.1,
--instrumentation-rack 0.31.1, -instrumentation-rails 0.42.0).
+-instrumentation-rack 0.31.1, -instrumentation-rails 0.42.0, and the floor
+contrib pins: -net_http 0.29.0, -faraday 0.33.0, -pg 0.36.0, -mysql2 0.34.0,
+-redis 0.29.0, -mongo 0.26.0, -sidekiq 0.29.0; LLM shim refs at openai 0.72.0,
+anthropic 1.59.0, gemini-ai 4.3.0, ruby_llm 1.16.0).
 
 ---
 
@@ -119,7 +122,7 @@ Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
   real Rails app boots with foam and the official rack span carries the inbound
   telemetry (`/ok`, `/fail`, `/reject` assertions).
 
-## R5: Door-2 ingest taps ride the alpha logs/metrics SDKs — every behavioral reliance pinned (rule 22a / fleet audit R8)
+## R5: Door-2 ingest taps ride the alpha logs/metrics SDKs — SHIPPED, every behavioral reliance pinned (fleet audit R8)
 
 - **Trap**: the log and metric ingest entries attach to upstream SDKs that are
   pre-1.0 ("development"/alpha). Four load-bearing behaviors could drift under
@@ -136,11 +139,11 @@ Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
   (`metric_store` seam), `aggregation/sum.rb:44-50` (`ndp.dup` shallow
   copies), `logs/log_record.rb:16-26` (`attr_accessor :resource`);
   maturity statement — https://opentelemetry.io/docs/languages/ruby/
-- **Decision & why**: ship the entries under rule 22a's experimental posture
-  (stated in the README Door 2 section), keep every reliance inside the
-  already-capped gemspec ranges (R2), and pin each with a test so a 0.x bump
-  is a deliberate rule-44 re-prove (any widening re-runs the door-2 e2e),
-  never a silent drift.
+- **Decision & why**: the entries are SHIPPED (README Door 2 section); the
+  pre-1.0 logs/metrics SDKs are a version-pin caveat, not a deferral. Keep every
+  reliance inside the already-capped gemspec ranges (R2), and pin each with a
+  test so a 0.x bump is a deliberate rule-44 re-prove (any widening re-runs the
+  door-2 e2e), never a silent drift.
 - **Mitigation**: capped ranges (`foam-otel.gemspec`); masking rebuilds point
   COPIES with fresh attribute hashes (`Redaction.mask_metric_data`,
   `lib/foam/otel/redaction.rb`); subclassing isolated to
@@ -227,44 +230,44 @@ Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
 
 ---
 
-## F1: Span attributes freeze at finish — the redaction floor cannot be a processor
+## F1: Span attributes freeze at finish — the redaction key pass cannot be a processor
 
-- **Trap**: The obvious place to mask attributes is a SpanProcessor, but the Ruby
-  SDK freezes a span's attributes at `finish` BEFORE any `on_finish` processor
-  runs — so a processor cannot mutate them, and neither can a tenant processor
-  see a masked view.
+- **Trap**: The obvious place to apply the redaction key pass is a SpanProcessor,
+  but the Ruby SDK freezes a span's attributes at `finish` BEFORE any `on_finish`
+  processor runs — so a processor cannot mutate them, and neither can a tenant
+  processor see a masked view.
 - **Sources**: installed source — `Span#finish` does
   `@attributes = validated_attributes(@attributes).freeze` then sets `@ended`
   (opentelemetry-sdk `trace/span.rb:277,280`); `to_span_data` returns the frozen
   `@attributes` by reference (`trace/span.rb:296-307`).
-- **Decision & why**: foam runs the always-on floor (rule 14) at the EXPORTER
-  boundary — a `RedactingSpanExporter`/`RedactingLogRecordExporter` that rebuilds
-  the mutable `SpanData`/`LogRecordData` Structs with masked attributes/events/
-  body before serialization. This guarantees no raw secret leaves the process in
-  foam's own export.
-- **Divergence (TODO pcga11, NARROWED)**: foam's HELPERS now mask AT CAPTURE
-  (`api.rb` `stringify`/`set_attribute`/`log` run the floor before the value
-  reaches the span/log record; `metrics.rb` always did), so a tenant
-  `additional_*` instance receives foam-helper data ALREADY-MASKED (rule 18
-  C.3) — masking is idempotent, so the wire value is unchanged. The residual
-  divergence is THIRD-PARTY INSTRUMENTATION attributes only: those freeze at
-  finish before any processor runs, so a tenant span processor sees them
-  UNMASKED and foam can only mask them at the exporter boundary. Recorded
-  honestly, not papered over; surfaced to pcga11 as spec-gap material (Ruby
-  offers no safe pre-freeze hook — the `on_finishing` hook runs inside the span
-  mutex, so a processor calling `set_attribute` there would deadlock). Foam's
-  own export is always masked, and the exporters FAIL CLOSED: a struct whose
-  rebuild raises is DROPPED with a loud warning (`Redaction.mask_*` return nil
-  on hard failure), never exported raw.
-- **Mitigation**: capture-time masking in `lib/foam/otel/api.rb` +
+- **Opt-in redaction (holistic redesign, 2026-07-26)**: foam does NO redaction by
+  default — with no `redact_keys`/`redact_pii_keys` every value is captured RAW
+  (no secret floor, no value-pattern masking). When keys ARE configured, foam
+  applies the key pass at the EXPORTER boundary — a `RedactingSpanExporter`/
+  `RedactingLogRecordExporter` that rebuilds the mutable `SpanData`/
+  `LogRecordData` Structs with masked attributes/events/body before
+  serialization. With no keys configured the exporter is a true pass-through.
+- **Divergence (NARROWED)**: when keys are configured foam's HELPERS apply the
+  key pass AT CAPTURE (`api.rb` `stringify`/`set_attribute`/`log`; `metrics.rb`
+  always did), so a tenant `additional_*` instance receives foam-helper data
+  ALREADY-MASKED (rule 18 C.3) — the pass is idempotent, so the wire value is
+  unchanged. The residual divergence is THIRD-PARTY INSTRUMENTATION attributes
+  only: those freeze at finish before any processor runs, so a tenant span
+  processor sees them as foam captured them and foam can only apply the key pass
+  at the exporter boundary. Ruby offers no safe pre-freeze hook — the
+  `on_finishing` hook runs inside the span mutex, so a processor calling
+  `set_attribute` there would deadlock. Foam's own export applies the configured
+  key pass, and the exporters FAIL CLOSED once a pass has begun: a struct whose
+  rebuild raises is DROPPED with a loud warning (`Redaction.mask_*` return nil on
+  hard failure), never exported half-masked.
+- **Mitigation**: capture-time key pass in `lib/foam/otel/api.rb` +
   `lib/foam/otel/redacting_exporter.rb` + `lib/foam/otel/redaction.rb`.
-- **Test**: `spec/tenant_seam_spec.rb` ("a generic tenant processor receives
-  HELPER-SET secrets ALREADY-MASKED", "a tenant LOG processor receives
-  helper-set body + attributes ALREADY-MASKED", the byte-identical
+- **Test**: `spec/tenant_seam_spec.rb` (tenant processors receive helper-set
+  LISTED keys ALREADY-MASKED, free-text bodies RAW, the byte-identical
   with/without-tenant proofs for spans, logs, AND metrics),
-  `spec/redacting_exporter_spec.rb` (masking on the wire; "a POISONED SpanData
-  (dup raises) is DROPPED — never exported raw"), `spec/redaction_spec.rb`
-  (the floor, tested exhaustively; capture+floor idempotence).
+  `spec/redacting_exporter_spec.rb` (opt-in masking on the wire; "a POISONED
+  SpanData (dup raises) is DROPPED — never exported raw"), `spec/redaction_spec.rb`
+  (default zero-redaction + the two opt-in key lists; capture+exporter idempotence).
 
 ## F2: OTEL_SDK_DISABLED and OTEL_PROPAGATORS are only honored by SDK.configure
 
@@ -466,6 +469,105 @@ Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
   foreign SDK claiming LOGS while foam registers TRACES is kept and warned,
   never silently displaced".
 
+## F9: The upstream datastore instrumentations SANITIZE by default — db_statement :obfuscate would stand silently
+
+- **Trap**: pg/mysql2/redis/mongo contrib all declare
+  `option :db_statement, default: :obfuscate` — an `install_all` with no
+  config ships OBFUSCATED statements, violating the zero-default-redaction
+  ruling with no error anywhere. Worse, `Base#config_options` silently
+  REPLACES an invalid option value with the default — so a contrib bump that
+  renamed/dropped `:include` would silently fall BACK to `:obfuscate`.
+- **Sources**: installed source — pg `instrumentation.rb:29`, mysql2
+  `instrumentation.rb:24`, redis `instrumentation.rb:24`, mongo
+  `instrumentation.rb:36` (the `option :db_statement, default: :obfuscate`
+  lines); `instrumentation-base base.rb:309-310` (invalid values replaced
+  with the default, warning goes to the upstream logger only). Ruling:
+  docs/decisions/holistic-redesign-decision-log.md (raised floor, raw
+  capture 2026-07-26).
+- **Decision & why**: activation passes a CENTRAL config map
+  (`FLOOR_INSTRUMENTATION_CONFIG`, `lib/foam/otel/init.rb`) setting
+  `db_statement: :include` for all four datastore instrumentations — raw
+  statements are the floor's point; masking is opt-in via redact keys at
+  foam's redaction stage. The option's continued upstream validity is pinned
+  by a test so a contrib rename is a CI failure, never a silent sanitize.
+- **Test**: `spec/floor_spec.rb` — "install_all receives the CENTRAL
+  raw-capture config", ":include is a declared db_statement option on every
+  configured floor gem"; presence checks stay proven there too.
+
+## F10: The stdlib Logger bridge — two feedback loops and the lazy-block contract
+
+- **Trap**: bridging `::Logger` naively (1) turns the OTel SDK's OWN internal
+  logger into a producer — every export failure logs, which emits a record,
+  which must be exported: unbounded growth the per-stack re-entrancy flag
+  cannot see because the batch thread is a different stack; (2) evaluates a
+  caller's lazy `logger.debug { expensive }` block even when the severity is
+  filtered (stdlib's block form exists precisely to avoid that cost), or
+  evaluates an accepted block TWICE (once for the bridge, once in `super`).
+- **Sources**: installed source — opentelemetry-api `opentelemetry.rb:30-31`
+  (`OpenTelemetry.logger` memoized `Logger.new($stdout)`) and `:37` (the
+  error handler logs through it — the export-failure feedback edge); stdlib
+  logger gem `logger.rb:675` (`Logger#add`, the single funnel; lazy block
+  resolution order); foam's emit path `lib/foam/otel/logger_bridge.rb`.
+- **Decision & why**: prepend ONE patch on `Logger#add`; skip
+  `OpenTelemetry.logger` by live identity; hold a thread-local re-entrancy
+  flag around the emit; resolve an accepted block exactly once and hand the
+  RESULT down to `super`; return `super` untouched for filtered severities
+  (block unevaluated). Emission is gated on foam OWNING the logs slot (rule
+  18 B) and every bridge failure degrades to the stdlib write alone (rule 9).
+- **Test**: `spec/logger_bridge_spec.rb` — the two loop-guard examples, the
+  lazy-block pair, the foreign-slot darkness, and "NEVER breaks the host's
+  log call".
+
+## F11: LLM shims patch third-party SDK call sites — the model call is sacred
+
+- **Trap**: no official Ruby contrib instrumentation exists for ANY LLM SDK,
+  so foam patches the SDKs' public methods directly. A raising extractor, a
+  broken tracer, or a semantic drift in the SDK's params/response shapes
+  must never fail the customer's model call (a broken instrumentation that
+  drops a production LLM request is the worst possible trade), and the SDK's
+  own HTTP send must not produce a SECOND span under the gen_ai span.
+- **Sources**: installed source — openai `resources/chat/completions.rb:119`
+  / `resources/responses.rb:96`, anthropic `resources/messages.rb:68`,
+  gemini-ai `controllers/client.rb:151`, ruby_llm `provider.rb:44` (the
+  patched call sites); opentelemetry-common `utilities.rb:104-117`
+  (`untraced` — the suppression context the http contrib honors). Ruling:
+  LLM provider parity + testing-mandatory (decision log 2026-07-26).
+- **Decision & why**: every patch routes through ONE guarded core
+  (`Foam::Otel::LLM.observe`, `lib/foam/otel/llm.rb`): request extraction
+  inside `safe_request` (degrades to bare operation/provider), span start
+  fail-to-dark (call runs unspanned), the SDK call's error re-raised
+  IDENTICALLY with `error.type` (+ the OBSERVED http status only), the SDK's
+  transport run inside `Common::Utilities.untraced` (one call = one span).
+  Presence-checked constants + explicit version windows per SDK; emission
+  gated on foam owning traces. Wire names are the GenAI semconv strings the
+  fleet's js/python gap-fillers emit — content attributes included, RAW.
+- **Test**: `spec/llm_openai_spec.rb`, `spec/llm_anthropic_spec.rb`,
+  `spec/llm_gemini_spec.rb`, `spec/llm_ruby_llm_spec.rb` — real SDKs against
+  a local fake provider (only the 3rd party mocked), per-provider activity +
+  RAW-content assertions, error-path re-raise, and the fail-to-dark set.
+
+## F12: Session stamping must beat the freeze (spans) and the buffer (logs)
+
+- **Trap**: the two signals offer different safe write points. Span
+  attributes FREEZE at finish (F1) — an on_finish stamp is impossible; log
+  records are buffered LIVE by the batch processor and serialized later on
+  another thread — a stamp must land on the emitting thread before export
+  can convert the record.
+- **Sources**: installed source — opentelemetry-sdk `trace/span.rb:277-280`
+  (freeze at finish), logs-sdk `batch_log_record_processor.rb:70-83`
+  (`on_emit` buffers the live record) + `export` (LogRecordData conversion
+  at export time). Ruling: session stitching (decision log 2026-07-26).
+- **Decision & why**: spans stamp in `on_start` (order-independent — the
+  attribute exists long before finish); logs stamp in `on_emit` on the
+  emitting thread, registered right after foam's batch processor (which
+  stays FIRST — pinned invariant). Both read `session.id` /
+  `session.previous_id` from the CONTEXT's baggage (foam's W3C propagator
+  set already extracts it), stamp verbatim, no-op when absent, never raise.
+  Door-2 taps are untouched — foam never mutates the customer's records.
+- **Test**: `spec/session_stitching_spec.rb` — span + log stamping, the
+  rack end-to-end with real `traceparent`+`baggage` headers, the no-op and
+  never-raise cases.
+
 ## General gotchas (applicable to Ruby)
 
 - **G1 — init after target import / pre-init no-op**: the API's proxy providers
@@ -521,8 +623,8 @@ Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
   mitigation (foam never rewrites or drops metric dimensions — rule 4/26);
   the mitigation is the README metrics warning with the classic bad example —
   *Documented* (README "Metrics" section). *Test*: `spec/metrics_spec.rb`
-  ("masks a secret-shaped metric attribute" — pins that non-secret attributes
-  pass through VERBATIM, the behavior this warning is about).
+  ("captures a metric attribute RAW by default; masks it only when the key is in
+  redact_keys" — pins that unlisted attributes pass through VERBATIM).
 - **G8 — never-ended spans leak memory**: a span started and never ended holds
   memory and context forever (and never exports — the batch processor only
   sees FINISHED spans, `on_finish`). `Foam::Otel.span {}` always ends the span
@@ -570,6 +672,15 @@ Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
   active", "the API entry file was loaded from exactly ONE gem copy"),
   `spec/packaging_spec.rb` ("activating a conflicting opentelemetry-api
   version raises Gem::LoadError at boot").
+- **G15 — runtime metrics are asynchronous-instrument callbacks**: the
+  hand-written GC/thread/RSS readings run on the PeriodicMetricReader's
+  thread at COLLECT time (no extra timer thread; fork recovery rides R1's
+  reader restart). A raising reading (missing GC.stat key, unreadable /proc)
+  must degrade to nil — the SDK ignores non-numeric callback results — so one
+  bad reading can never kill the collect loop or the healthy instruments
+  beside it (`lib/foam/otel/runtime_metrics.rb` `guarded_callback`).
+  *Test*: `spec/runtime_metrics_spec.rb` ("a poisoned reading is
+  fail-to-dark", the foreign-slot and idempotence cases).
 
 ---
 

data/README.md

@@ -2,9 +2,11 @@
 
 Foam's OpenTelemetry core for Ruby services. A thin, safe wrapper over the
 official OpenTelemetry libraries: foam owns the pipeline (providers, batch
-processors, OTLP export to the foam fleet endpoint, an always-on redaction
-floor), turns on automatic tier-1/2 instrumentation, and hands you a small set
-of never-throw helpers — and nothing else.
+processors, OTLP export to the foam fleet endpoint), turns on automatic
+tier-1/2 instrumentation, and hands you a small set of never-throw helpers —
+and nothing else. **Redaction is fully opt-in: by default foam captures every
+value RAW** (no secret floor, no value-pattern masking); you enumerate the
+fields to mask via `redact_keys`/`redact_pii_keys`.
 
 Built to `docs/BASE_PACKAGE_SPEC.md`. This README is the manual you integrate
 from.
@@ -19,12 +21,16 @@ Foam builds on the OpenTelemetry authors' work (https://opentelemetry.io) — se
 ```ruby
 # Gemfile
 gem "foam-otel"
-# Bundle the official instrumentation for whatever your app uses; foam
-# auto-activates each when present (presence-checked). Rails + Rack come with
-# foam-otel; add others as needed:
-gem "opentelemetry-instrumentation-pg"       # e.g. Postgres
-gem "opentelemetry-instrumentation-redis"    # e.g. Redis
-gem "opentelemetry-instrumentation-sidekiq"  # e.g. Sidekiq
+# foam-otel bundles the UNIVERSAL FLOOR and auto-activates each piece when its
+# target library is present (presence-checked, and gated on foam owning the
+# slot it produces into): Rack + the Rails family, the HTTP clients (Net::HTTP,
+# Faraday), the primary datastores (pg, mysql2, redis, mongo) with RAW
+# db.statement capture, Sidekiq, the stdlib Logger bridge, hand-written Ruby
+# runtime + GC metrics, session stitching (browser session.id via baggage),
+# and the LLM shims (OpenAI, Anthropic, Gemini, ruby_llm — activity + raw
+# content). Add only the niche long tail your app needs beyond the floor:
+gem "opentelemetry-instrumentation-graphql"  # e.g. GraphQL
+gem "opentelemetry-instrumentation-resque"   # e.g. Resque
 ```
 
 **Supported versions** (tested in CI, `spec/version_spec.rb`): Ruby **>= 3.1**;
@@ -54,10 +60,53 @@ Foam::Otel.init(
 ```
 
 **Outcome**: foam registers the tracer/meter/logger providers, exports OTLP to
-the foam fleet endpoint, and auto-activates the official rack/rails
-instrumentation (and any other bundled `opentelemetry-instrumentation-*`). Every
-inbound request, DB call, HTTP call, and job the official instrumentations cover
-now flows to foam, with the redaction floor applied on the wire.
+the foam fleet endpoint, and auto-activates the **universal floor** — the
+official rack/rails instrumentation plus the bundled HTTP (Net::HTTP/Faraday),
+datastore (pg/mysql2/redis/mongo), and Sidekiq instrumentations — each
+presence-gated, and gated on foam owning the traces slot (a foreign-owned
+tracer stands the activation down). The datastore set is activated with
+**`db_statement: :include`** — foam explicitly overrides the upstream
+`:obfuscate` default so RAW SQL / redis args / mongo commands land on the wire.
+On top of the contrib set the floor adds foam's own pieces: the **stdlib
+Logger bridge** (every host `Logger` line also lands as a trace-correlated
+OTel log record, body raw), hand-written Ruby **runtime + GC metrics**
+(GC counts + timing, heap slots, allocation, thread count, RSS — Ruby has no
+drop-in upstream metrics gem, so foam ships its own collector),
+**session stitching** (inbound `baggage: session.id` from the foam browser
+package is stamped onto every span and log record), and the **LLM shims**
+(below). Every inbound request, DB call, HTTP call, job, log line, and model
+call now flows to foam. **Redaction is opt-in: by default every value —
+attributes, URLs/query strings, DB statement text, log bodies, LLM content —
+is captured RAW.** Pass `redact_keys`/`redact_pii_keys` to mask or erase
+specific fields (see below).
+
+### The LLM surface — OpenAI, Anthropic, Gemini (and ruby_llm)
+
+The Ruby contrib registry ships no LLM instrumentation, so foam does: thin,
+presence-checked shims over the SDKs' public call sites, emitting the standard
+`gen_ai.*` semantic conventions — activity (model, response id, finish
+reasons, token usage, latency) AND prompt/response **content, RAW**
+(`gen_ai.input.messages` / `gen_ai.output.messages` /
+`gen_ai.system_instructions`). Covered: the official `openai` SDK
+(chat.completions.create + responses.create), the official `anthropic` SDK
+(messages.create), Gemini via the `gemini-ai` gem (Google ships no official
+Ruby SDK), and `ruby_llm` (one seam covering all its providers). Absent SDK =
+inert; version-guarded; fail-to-dark — a shim failure can NEVER break the
+model call, and the SDK's own error re-raises identically. One model call =
+one `gen_ai` client span (the SDK's HTTP send rides the same suppression
+context foam's exporters use). Streaming call sites (`#stream`/`#stream_raw`
+on the official SDKs) are a recorded follow-up.
+
+### Session stitching — browser `session.id` on backend telemetry
+
+The foam browser package stamps `session.id` on every browser signal and
+sends it to your API as W3C Baggage beside `traceparent`. This gem's floor
+copies `session.id` (and `session.previous_id` across a rotation) from the
+inbound baggage onto every span and log record foam emits — browser session →
+backend traces/logs, stitched with no ingest-side join. No-op when the
+baggage is absent. **CORS note (the FDE wires this on every frontend-called
+API):** the allowlist must include BOTH headers —
+`Access-Control-Allow-Headers: traceparent, baggage`.
 
 ---
 
@@ -70,8 +119,8 @@ now flows to foam, with the redaction floor applied on the wire.
 | `enabled:` | Boolean | yes | — | The config switch. `false` = fully inert (no SDK, no providers, no network, helpers no-op). `true` = export, in EVERY environment. No default — you write the logic. |
 | `token:` | String | when enabled | — | `Authorization: Bearer` for export. Required (and validated) only when `enabled: true`; wired explicitly from your secret source — never an env fallback read by the gem. **Fleet convention: read it from the `FOAM_OTEL_TOKEN` env var.** Blank while enabled → raises at boot. |
 | `version:` | String | no | nil | `service.version`, verbatim (git SHA recommended). Missing → warns and continues. Never detected at runtime. |
-| `redact_keys:` | Array<String> | no | `[]` | Extra field names treated as SECRETS (tail-masked). EXTENDS the always-on floor. |
-| `redact_pii_keys:` | Array<String> | no | `[]` | Field names treated as PII (full `[REDACTED]`, no tail). Foam ships no PII preset — this is your enumeration. |
+| `redact_keys:` | Array<String> | no | `[]` | The ONLY field names tail-masked (shape-preserving, e.g. `********f456`). Opt-in — empty (the default) means NO masking. Matches by case-insensitive substring, including keys nested in structured values and query-string keys. |
+| `redact_pii_keys:` | Array<String> | no | `[]` | Field names fully erased to `[REDACTED]` (no tail). Opt-in — empty (the default) means NO erasure. Foam ships no preset; this is your enumeration. |
 | `additional_span_processors:` | Array | no | `[]` | Tenant seam: constructed SpanProcessor instances added to foam's pipeline (additive; never replace foam's export). See coexistence. |
 | `additional_log_record_processors:` | Array | no | `[]` | Tenant seam, logs. |
 | `additional_metric_readers:` | Array | no | `[]` | Tenant seam, metrics. |
@@ -82,10 +131,10 @@ now flows to foam, with the redaction floor applied on the wire.
 Examples for the remaining options (each is runnable as-is):
 
 ```ruby
-# Customer redaction lists EXTEND the always-on floor (rule 14):
+# Redaction is OPT-IN (default: nothing is masked). List the fields to redact:
 Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"),
-                redact_keys: %w[internal_ref voucher_code],   # tail-masked like secrets
-                redact_pii_keys: %w[customer_email full_name]) # fully [REDACTED]
+                redact_keys: %w[password api_key internal_ref voucher_code], # tail-masked
+                redact_pii_keys: %w[customer_email full_name])               # fully [REDACTED]
 ```
 
 ```ruby
@@ -221,12 +270,13 @@ Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FO
                 ignored_outbound_hosts: ["ingest.eval-tool.example"])
 ```
 
-> Ruby note: foam's HELPERS mask at capture, so a tenant processor receives
-> foam-helper data (span/log helper attributes, log bodies, metric labels)
-> ALREADY masked. Because the Ruby SDK freezes span attributes at finish, a
-> tenant processor sees third-party instrumentation attributes UNMASKED (for
-> those, foam's floor runs at the exporter boundary — GOTCHAS F1). Foam's own
-> export is always masked.
+> Ruby note: when you configure `redact_keys`/`redact_pii_keys`, foam's HELPERS
+> apply the key pass at capture, so a tenant processor receives foam-helper data
+> (span/log helper attributes, log bodies, metric labels) ALREADY masked.
+> Because the Ruby SDK freezes span attributes at finish, a tenant
+> processor sees third-party instrumentation attributes UNMASKED (for those,
+> foam's key pass runs at the exporter boundary — GOTCHAS F1). With no keys
+> configured (the default) nothing is masked on either path.
 >
 > Loop-guard note: `ignored_outbound_hosts` suppresses spans for tenant/agent
 > egress made through **Net::HTTP or Excon**. A tenant exporter using
@@ -265,7 +315,8 @@ end
 **Outcome**: their pipeline keeps working exactly as before — their data,
 their resource, their export, byte-identical — and foam ALSO receives the
 signal, carrying THEIR resource identity plus foam's export-time stamp and
-the full redaction floor (details in the Door 2 section).
+any per-tap `redact_keys`/`redact_pii_keys` you set (opt-in — none by default;
+details in the Door 2 section).
 
 **Unhappy paths**:
 
@@ -351,16 +402,23 @@ how that pipeline's data ALSO reaches foam: constructed instances you add —
 one line per claimed signal — to the CUSTOMER'S OWN OTel setup. Additive
 readers only: they never mutate their data, their resource, or their export.
 
-> **Experimental posture (spec rule 22a)**: the log and metric entries ride
-> upstream's pre-1.0 SDKs (logs "development", metrics alpha) — exactly the
-> capped-range posture this gem already holds (GOTCHAS R2/R5). Availability
-> tracks upstream stability; the traces entry rides the stable 1.x SDK.
+> **All three entries are SHIPPED.** The traces entry rides the stable 1.x SDK;
+> the log and metric entries ride upstream's pre-1.0 SDKs (logs "development",
+> metrics alpha), pinned to this gem's capped ranges (GOTCHAS R2/R5) so a 0.x
+> drift is a deliberate re-prove, never a silent change. The pre-1.0 SDK
+> maturity is a version-pin caveat, not a deferral — the entries are available
+> and supported today.
+>
+> **Version-pin posture:** because the log and metric taps ride those pre-1.0
+> upstream SDKs, they are version-pinned and re-proven on every 0.x bump
+> rather than assumed stable — shipped and supported either way.
 
 ### The three entries
 
 All three share one signature (`token:` and `environment:` required; the
-redaction kwargs EXTEND the always-on floor for that tap only; `diagnostics:`
-is tap-scoped narration). Construction validates loudly at boot and NEVER
+redaction kwargs are the ONLY keys that tap redacts — opt-in, none by default,
+scoped to that tap; `diagnostics:` is tap-scoped narration). Construction
+validates loudly at boot and NEVER
 throws afterwards — a failure inside a tap can never break their pipeline.
 Fleet canon mapping (pinned by `spec/export_surface_spec.rb`):
 `create_ingest_span_processor` = `createFoamIngestSpanProcessor`,
@@ -380,9 +438,9 @@ their_tracer_provider.add_span_processor(processor)
 # raises ArgumentError at construction for a blank token/environment
 ```
 
-**Logs** — a LogRecordProcessor for THEIR LoggerProvider. The floor's
-key-match runs over record attributes AND the value-pattern pass runs over
-the free-text BODY (bodies are where raw tokens actually live):
+**Logs** — a LogRecordProcessor for THEIR LoggerProvider. The tap's
+`redact_keys`/`redact_pii_keys` (if any) match over record attributes and keys
+nested in structured bodies; free-text bodies ride RAW (no value-pattern pass):
 
 ```ruby
 provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: their_resource)
@@ -426,7 +484,7 @@ in THEIR pipeline. Three layers keep it closed:
 | | their pipeline | foam's copy |
 | --- | --- | --- |
 | `service.name` / `service.version` / `service.instance.id` | theirs | theirs, untouched (the data carries THEIR identity) |
-| all attributes / events / bodies | raw, byte-identical | redaction floor + your per-tap lists applied |
+| all attributes / events / bodies | raw, byte-identical | your per-tap `redact_keys`/`redact_pii_keys` applied (default: none → identical to theirs) |
 | `deployment.environment.name` | theirs (if any) | the tap's `environment:` argument (stamped at export time) |
 | `foam.ingest.tier` | absent | `"external"` (the wire-contract marker) |
 | `telemetry.distro.name` / `telemetry.distro.version` | absent | `"foam"` / the gem version (support reads the tap's presence and version from telemetry alone) |