foam-otel 2.1.1 → 3.0.0.alpha.2

data/README.md

@@ -1,1145 +1,712 @@
-# foam-otel (Ruby)
-
-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 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 above two always-on exceptions:
-by default foam captures every value RAW** (no PII preset) **except (1) the
-credential floor** — a fixed list of credential/secret header and field NAMES
-always masked to `[REDACTED]` (see "The default credential denylist" below) —
-**and (2) the value-pattern secret layer** — credential-SHAPED value spans
-(cloud keys, tokens, JWTs, private-key blocks, `user:pass@` URLs…) masked to
-`[REDACTED]` regardless of field name (see "The value-pattern secret layer"
-below); you enumerate any further fields to mask via
-`redact_keys`/`redact_pii_keys`.
-
-Built to `docs/BASE_PACKAGE_SPEC.md`. This README is the manual you integrate
-from.
-
-Foam builds on the OpenTelemetry authors' work (https://opentelemetry.io) — see
-`THIRD-PARTY-NOTICES`. Licensed, not sold — see `LICENSE`.
-
----
+# Foam OpenTelemetry SDK for Ruby
+
+`foam-otel` is Foam's OpenTelemetry distribution for Ruby.
+
+## Requirements
+
+- Ruby 3.3 or newer
+- Foam ingest token, stored as `FOAM_OTEL_TOKEN`
 
 ## Install
 
+Add the gem to the `Gemfile`:
+
 ```ruby
-# Gemfile
-gem "foam-otel"
-# 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),
-# default-on HTTP header capture (a documented default header list on the
-# official rack server span; every Faraday client header — see "Header
-# capture" below), 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
+gem "foam-otel", "~> 3.0.0.alpha"
+```
+
+Then run:
+
+```sh
+bundle install
 ```
 
-**Supported versions** (tested in CI, `spec/version_spec.rb`): Ruby **>= 3.4**
-(the version the CI matrix runs — the floor follows the tested matrix);
-OpenTelemetry API **`opentelemetry-api` ~> 1.1** (1.x). The metrics and logs
-SDKs are pre-1.0 upstream (metrics alpha, logs development) and are pinned with
-pessimistic constraints; foam wraps them behind stable helpers so app code never
-touches the churning API (see GOTCHAS R2).
+## Initialize
+
+Call `init` once, before the app loads, so OpenTelemetry can instrument
+libraries as they are required. Set `enabled: false` to turn Foam off.
+
+Store the ingest token as `FOAM_OTEL_TOKEN` and pass `ENV["FOAM_OTEL_TOKEN"]`
+to `init`.
 
----
+### Rails
 
-## Quick start — scenario 1: a clean service (the common case)
+TODO(jhartquist)
 
-Put `init` FIRST, before your app boots. In Rails, that means an initializer
-(and, for cluster mode, per worker — see "Puma / Unicorn" below).
+### Plain Ruby and Rack
+
+Call `init` at the top of `config.ru`, then add the OpenTelemetry Rack
+middleware and Foam's:
 
 ```ruby
-# config/initializers/foam.rb  (the one config module you own)
 require "foam/otel"
 
-Foam::Otel.init(
-  name: "checkout-api",                       # → service.name
-  environment: ENV.fetch("APP_ENV", "development"),  # → deployment.environment.name (verbatim)
-  enabled: !%w[test ci].include?(ENV["APP_ENV"]),    # silence tests/CI; export everywhere else
-  token: ENV.fetch("FOAM_OTEL_TOKEN"),             # required WHEN enabled — wire it explicitly
-  version: ENV["GIT_SHA"]                      # → service.version (recommended; optional)
+Foam.init(
+  name: "checkout-api",
+  environment: ENV["RACK_ENV"],
+  enabled: true,
+  token: ENV["FOAM_OTEL_TOKEN"]
 )
-```
 
-**Outcome**: foam registers the tracer/meter/logger providers, exports OTLP to
-the foam 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 above the credential floor: by
-default every value — attributes, URLs/query strings, DB statement text, log
-bodies, LLM content — is captured RAW, except values whose NAME is on the
-always-on credential denylist (masked `[REDACTED]`; see "The default
-credential denylist" below).** Pass `redact_keys`/`redact_pii_keys` to mask
-or erase further specific fields (see below).
-
-> **Sidekiq trace shape** (GOTCHAS G16): the bundled instrumentation keeps
-> its upstream default `propagation_style: :link` — a performed job runs as
-> its OWN trace whose first span LINKS back to the enqueuing span (context is
-> always propagated across the hop; proven against a real Redis in
-> `spec/floor_sidekiq_wire_spec.rb`). Prefer one continuous web→job trace?
-> Set the standard contrib lever:
-> `OTEL_RUBY_INSTRUMENTATION_SIDEKIQ_CONFIG_OPTS='propagation_style=child'`.
-
-### The LLM surface — OpenAI, Anthropic, Gemini (plus ruby_llm, ruby-openai, and hand-rolled HTTP.rb Anthropic)
-
-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`). Agent tool loops ride in full: tool-call
-turns keep their tool names/arguments and tool-result turns keep their
-`tool_call_id` linkage inside the message content. `gen_ai.operation.name`
-(and the `{operation} {model}` span name) follows the semconv operation for
-each API shape — `chat` for the OpenAI/Anthropic/ruby_llm chat seams,
-`generate_content` for Gemini's generateContent, identical to foam's
-js/python Gemini paths (**wire change in 1.2.1**: Gemini spans previously
-said `chat`). 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), `ruby_llm` (one seam covering all its providers), the community
-`ruby-openai` gem (`client.chat` / `client.embeddings` — presence is
-discriminated from the official gem by call shape, since both reopen the
-`OpenAI` namespace; embeddings emit tokens + models, never the input
-documents), and hand-rolled HTTP.rb Anthropic clients (`HTTP.post` /
-`HTTP.persistent(...).post` to `api.anthropic.com/v1/messages` — exactly
-that endpoint; HTTP.rb's non-raising 4xx/5xx become ERROR spans with the
-observed status, and foam never consumes a response stream: SSE, chunked,
-and oversized bodies pass through untouched, and buffered JSON bodies are
-handed back readable). 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; transport gems that ignore that context, like
-the contrib `http` instrumentation, nest beneath it instead). 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`.
-
-### Header capture — request + response headers on the official spans
-
-**Inbound (default-on, no init option):** foam configures the OFFICIAL
-`opentelemetry-instrumentation-rack` gem's own header options
-(`allowed_request_headers:` / `allowed_response_headers:`) with a
-documented **default list** at init, so the rack SERVER span carries the
-listed request and response headers as
-`http.request.header.<name>` / `http.response.header.<name>` attributes
-(the gem's form: lowercase with `-` folded to `_`, e.g.
-`http.request.header.x_request_id`), on error requests too.
-
-> **Honest limit (deliberate divergence from foam's js/python cores):**
-> Ruby inbound captures the **named default list below, NOT all headers** —
-> the official gem's options are an enumerated allowlist with no
-> capture-all form, and that official option is the chosen seam.
-> A custom header outside the list is **not captured** unless
-> you extend the list (recipe below).
-
-The default lists (`Foam::Otel::HeaderCapture::DEFAULT_REQUEST_HEADERS` /
-`DEFAULT_RESPONSE_HEADERS` — frozen, documented constants):
-
-- **request** — `content-type`, `content-length`, `content-encoding`,
-  `accept`, `accept-charset`, `accept-encoding`, `accept-language`,
-  `user-agent`, `referer`, `origin`, `host`, `cache-control`, `pragma`,
-  `if-none-match`, `if-modified-since`, `range`, `via`, `forwarded`,
-  `x-forwarded-for`, `x-forwarded-proto`, `x-forwarded-host`,
-  `x-forwarded-port`, `x-real-ip`, `x-request-id`, `x-correlation-id`,
-  plus the request half of the credential floor — `authorization`,
-  `proxy-authorization`, `cookie`, `x-api-key`, `x-auth-token`;
-- **response** — `content-type`, `content-length`, `content-encoding`,
-  `content-language`, `content-range`, `cache-control`, `pragma`,
-  `expires`, `age`, `etag`, `last-modified`, `vary`, `location`,
-  `retry-after`, `x-request-id`, `x-correlation-id`, `x-runtime`,
-  `server-timing`, plus the response half of the floor — `set-cookie`,
-  `www-authenticate`.
-
-Propagation headers (`traceparent`, `tracestate`, `baggage`) are
-deliberately not listed — they are extracted as span context, not captured
-as attributes; hop-by-hop plumbing (`connection`, `keep-alive`, …) is
-skipped too.
-
-**Extending (or narrowing) the list — the gem's own standard env var,
-always respected, never overridden by foam:**
-
-```bash
-# The value REPLACES the list for that option — name every header you want:
-export OTEL_RUBY_INSTRUMENTATION_RACK_CONFIG_OPTS='allowed_request_headers=content-type,accept,x-request-id,x-tenant-id'
+use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args)
+use Foam::Rack::Middleware
+
+run App
 ```
 
-Precedence: (1) an explicit rack instrumentation instance you pass via
-`additional_instrumentations:` installs first and its header config wins
-entirely; (2) any header option you set in
-`OTEL_RUBY_INSTRUMENTATION_RACK_CONFIG_OPTS` governs that option (foam's
-default fills only the option you did not touch — a narrower operator list
-is never widened, even the narrow-to-empty `allowed_request_headers=`
-spelling); (3) otherwise foam's defaults apply. Foam never installs the
-rack instrumentation (or its header config) when a foreign SDK owns the
-traces slot.
-
-**Floor masking, zero config:** the always-on credential floor masks the
-seven credential headers (`authorization`, `proxy-authorization`, `cookie`,
-`set-cookie`, `x-api-key`, `x-auth-token`, `www-authenticate`) to
-`[REDACTED]` in the emitted attribute forms (dash/underscore-normalized
-match) — they ride the default lists deliberately so their PRESENCE is
-visible, value never (see "The default credential denylist";
-`x-forwarded-for` / `x-real-ip` are on the 52-entry key floor and arrive
-`[REDACTED]` too). **Masking further captured headers is redaction's job,
-not a capture switch:** list the emitted name form in `redact_keys` /
-`redact: { secrets: [...] }` (tail mask) or `redact_pii_keys` /
-`redact: { pii: [...] }` (full `[REDACTED]`) — the substring key match
-reaches the attribute names (inbound names are underscored by the rack gem,
-so list e.g. `x_runtime`; Faraday's outbound names keep dashes).
-
-**Outbound (Faraday):** the official faraday instrumentation has no header
-option at all, so outbound stays foam's own Faraday middleware (its
-first-class public extension API), enriching the official CLIENT span with
-**every** request header actually sent (the injected `traceparent`
-included) and every response header received — string-array attributes,
-dash-form names. It never creates a span and stands down when foam is
-disabled/killed, when a foreign SDK owns traces, or when the current span
-is not the official faraday instrumentation's own (a mis-ordered stack
-captures nothing rather than writing onto the wrong span). One line per
-connection (Faraday has no public add-to-every-connection hook — the
-middleware name is registered by init, placement is yours; ORDER MATTERS,
-the official middleware first):
+## Instrumentation
 
-```ruby
-conn = Faraday.new(url: "https://partner-api.example") do |f|
-  f.use :open_telemetry     # the official client span (explicit, so it sits OUTSIDE)
-  f.use :foam_otel_headers  # foam's header capture, directly inside it
-end
-```
+`init` installs OpenTelemetry's Ruby instrumentation bundle,
+`opentelemetry-instrumentation-all`, and the standard library logger
+bridge, `opentelemetry-instrumentation-logger`. An instrumentation
+installs only when its library is loaded before `init`, so call `init`
+after `Bundler.require` or after the app's own requires. A library loaded after
+`init` is not instrumented, and a warning is written to stderr once when
+`state` finds one. `state[:instrumentations]` lists what installed.
 
-**Deliberately out of scope** (no standard extension point exists —
-skipped, not monkey-patched): outbound **Net::HTTP / Excon / HTTP (httprb)
-/ HTTPX** headers (their official instrumentations expose no
-request/response hook or header option) and gRPC metadata. Outbound header
-coverage today is Faraday. **Bodies/payloads are not captured by header
-capture** — bodies are the separate, opt-in `capture_payloads:` capability
-below.
+The bundle covers: action_mailer, action_pack, action_view, active_job,
+active_model_serializers, active_record, active_storage, active_support,
+anthropic, aws_lambda, aws_sdk, bunny, concurrent_ruby, dalli, delayed_job,
+ethon, excon, faraday, grape, graphql, grpc, gruf, http, http_client, httpx,
+koala, lmdb, logger, mongo, mysql2, net_http, pg, que, racecar, rack, rails,
+rake, rdkafka, redis, resque, restclient, ruby_kafka, sidekiq, sinatra,
+trilogy.
 
-### Payload (body) capture — opt-in, `capture_payloads:`
+To install an instrumentation outside the bundle, list it in
+`additional_instrumentations`.
 
-**Off by default.** One init option turns on inbound HTTP **body** capture
-on the official rack SERVER span (headers stay the header-capture seam
-above — this never duplicates them):
+TODO(jhartquist): Revisit and review this compatibility guidance.
 
-```ruby
-Foam::Otel.init(
-  name: "checkout-api", environment: ENV.fetch("APP_ENV"),
-  enabled: ENV.fetch("APP_ENV") == "production", token: ENV.fetch("FOAM_OTEL_TOKEN"),
-  capture_payloads: :errors # :off (default) | :errors | :always — equivalent strings accepted
-)
-```
+### Instrumentation versions
 
-- **`:off` (default)** — zero body teeing, zero per-request allocation, and
-  **zero middleware shipped**: with the default, foam's Rails wiring
-  installs nothing at all.
-- **`:errors`** — bodies are teed per request but attributes attach to the
-  span **only when the request errored**: `Foam::Otel.record_exception`
-  called while the rack server span is current, an exception raised through
-  the middleware, or a response status **>= 500**. A clean 2xx/4xx
-  attaches **nothing**.
-- **`:always`** — attach on every request.
-
-An invalid option value raises `ArgumentError` at boot. The operator env
-clamp **`FOAM_CAPTURE_PAYLOADS=off|errors|always` overrides the option in
-both directions** (force payloads off on a misbehaving deploy, or force
-them on without a code change — one loud `[foam]` line when it changes the
-mode); an invalid env value warns and falls back to the option, never a
-crashed boot.
-
-**What lands on the span** (in `:always`, or in `:errors` on an errored
-request): `http.request.body` / `http.response.body` for **textual**
-payloads (`text/*`, JSON/`+json`, urlencoded forms, XML/`+xml`, GraphQL;
-skipped when `Content-Encoding` is not identity), capped at **8192 chars**
-with an `…[truncated]` marker, plus `http.request.body.size` /
-`http.response.body.size` — **true byte sizes** when known (declared
-`Content-Length`, else the bytes actually observed). Non-textual payloads
-contribute sizes only.
-
-**Stream safety (GOTCHAS F15):** bodies are TEED, never consumed — foam
-records exactly what your app reads from `rack.input` (an app that never
-reads its body captures nothing; a re-read form body — rewound, or
-repositioned via `seek`/`pos=` — is captured and counted once), and
-streaming/SSE responses pass through
-unbuffered chunk-by-chunk with `close` preserved. Rack 3 `#call`-only
-streaming bodies are never wrapped. The request and response are never
-altered, and an app exception re-raises identically.
-
-**Redaction stays central, on export:** a JSON-shaped body is
-**deep-redacted by field name** at the exporter boundary — the credential
-floor (`password`, `authorization`, …) and your `redact_keys` /
-`redact: {secrets:/pii:}` lists reach *inside* the body JSON; urlencoded
-bodies get their `k=v` pair names masked by the same tokenizer that covers
-query strings; and the value-pattern secret layer scans all captured body
-text. (A body truncated at the cap no longer parses as JSON, so field-name
-deep-redaction cannot apply to it — the value-shape scans still run.)
-
-**Wiring:** in **Rails**, automatic when the mode is not `:off` (foam's
-railtie inserts `Foam::Otel::PayloadCapture` directly inside the official
-rack middleware after your initializers run; when foam-otel loads before
-rails, `init` wires it instead, as long as init runs during boot — the
-standard `config/initializers/foam.rb` recipe). **Plain Rack / Sinatra**
-apps add one line under the official middleware:
+Bundler keeps one version of each gem in the application. By the time Foam
+starts, those versions are already fixed. `additional_instrumentations` only
+configures an instrumentation that Bundler installed and Ruby loaded; it
+cannot choose or install another version.
 
-```ruby
-# config.ru
-use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args)
-use Foam::Otel::PayloadCapture   # opt-in body capture (inert while capture_payloads is :off)
-run MyApp
-```
+If a bundled instrumentation does not support the library version your app
+uses, pin a compatible `opentelemetry-instrumentation-*` gem in the `Gemfile`
+and run `bundle install` again.
 
-The middleware enriches only: it never creates a span, and it stands down
-per request when foam is disabled/killed, when the span is not recording,
-or when a foreign SDK owns the traces slot. Outbound (client) bodies are
-not captured — inbound only.
-
----
-
-## The `init` options
-
-| Option | Type | Required | Default | What it does |
-| --- | --- | --- | --- | --- |
-| `name:` | String | yes | — | `service.name`. Blank → raises at boot. |
-| `environment:` | String | yes | — | `deployment.environment.name`, exported verbatim. A value outside `{production, staging, development, test}` warns but is never rewritten. Blank → raises. |
-| `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. **The convention across all foam SDKs: 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:` | Hash | no | nil | The grouped redaction object (1.5.0, the preferred surface): `{ secrets: [...], pii: [...], detect: [...] }` — symbol or string keys. `secrets:` has `redact_keys` semantics (tail mask) and `pii:` has `redact_pii_keys` semantics (full `[REDACTED]`); when both a legacy option and its `redact` field are set, the lists UNION. `detect:` is the opt-in PII detection tier's entity list — value-shape detection with typed placeholders (see "PII detection (opt-in)" below). An unknown field, a non-Array value, or an unknown `detect` entity name raises at boot. Absent (the default) → behavior byte-identical to before. |
-| `redact_keys:` | Array<String> | no | `[]` | Alias — the preferred spelling is `redact: { secrets: [...] }` (same semantics; the lists union when both are set). The ONLY field names tail-masked (shape-preserving, e.g. `********f456`). Opt-in and ADDITIVE on top of the always-on credential floor — empty (the default) means no masking beyond the floor. Matches by case-insensitive substring, including keys nested in structured values and query-string keys. A key that is also on the floor stays fully `[REDACTED]` (the floor wins; it is never downgraded to a tail). |
-| `redact_pii_keys:` | Array<String> | no | `[]` | Alias — the preferred spelling is `redact: { pii: [...] }` (same semantics; the lists union when both are set). Field names fully erased to `[REDACTED]` (no tail). Opt-in and additive above the floor — empty (the default) means no erasure beyond the floor. Foam ships no PII 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. |
-| `additional_instrumentations:` | Array | no | `[]` | Constructed tier-2 instrumentation instances to register (fault-isolated: one that throws is skipped with a `[foam]` warning). |
-| `ignored_outbound_hosts:` | Array<String> | no | `[]` | Hosts whose outbound calls produce no spans — EXTENDS the built-in export-loop guard. For a co-resident agent's intake or a tenant exporter's endpoint. Applies to the clients whose official instrumentation supports host suppression: **Net::HTTP and Excon**. Faraday/HTTP (httprb)/HTTPX have no upstream `untraced_hosts` option — foam warns loudly at init when one of those is bundled (GOTCHAS G13); foam's own export loop is guarded for every client regardless. |
-| `before_send:` | Proc/Array | no | `[]` | Export hook (1.8.0): one callable — or an Array run as a pipeline — called with every **span and log record** at the export boundary, after batching and BEFORE foam's redaction pass and serialization, so nothing a hook drops ever leaves the process. Return the record (or a same-type replacement) to export it — in-place mutation supported; return `nil` to drop it; a raise or foreign return drops **that record** loudly, fail-closed, never a raise into your threads. Runs BEFORE redaction — a hook can never widen what ships. Spans and logs only; door 1 only. A non-callable (or a one-arg-incompatible lambda) raises at boot. Process-global. Hooks run on the export thread — keep them non-blocking. Full contract: "The `before_send` hook" below. |
-| `capture_payloads:` | Symbol/String | no | `:off` | Inbound HTTP **body** capture on the rack server span (see "Payload (body) capture"). `:off` = zero teeing, zero middleware (the default); `:errors` = tee per request, attach only on exception/5xx; `:always` = attach on every request. Equivalent strings accepted; anything else raises at boot. Overridden in both directions by the `FOAM_CAPTURE_PAYLOADS` env clamp (env table below). Textual payloads only, 8192-char cap + `…[truncated]`, true `.size` attributes; sizes-only for binary/compressed. |
-| `diagnostics:` | Boolean | no | false | Verbose `[foam]` self-reporting of init/health. Warnings and errors are always loud regardless. |
-| `secret_heuristics:` | Boolean | no | true | The value-pattern secret layer's HEURISTIC tier (generic keyword+entropy detection, see "The value-pattern secret layer"). `false` disables ONLY the heuristics — the named provider patterns, the credential floor and the redaction-coverage contract have no off switch. Disabling logs one loud `[foam]` line at init (an explicit, audited decision for telemetry whose legitimate values collide with the heuristics). |
-
-Examples for the remaining options (each is runnable as-is):
+If Bundler accepts the pin, restart the app and the whole bundle will use that
+instrumentation version. If it conflicts with `foam-otel` or
+`opentelemetry-instrumentation-all`, those versions cannot live in the same
+bundle. At that point, change the application library, use a compatible Foam
+release, or accept the telemetry gap: the app can keep running, but Foam will
+not receive the spans that instrumentation would have produced.
 
-```ruby
-# 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[password api_key internal_ref voucher_code], # tail-masked
-                redact_pii_keys: %w[customer_email full_name])               # fully [REDACTED]
-```
+Even a successful `bundle install` only means the declared gem dependencies
+agree. The instrumentation checks the target library when `init` runs. If the
+target is unsupported, Foam leaves that instrumentation out of
+`state[:instrumentations]`. `additional_instrumentations` cannot bypass the
+check or load a second version of the gem.
 
-```ruby
-# The grouped redact object (1.5.0, preferred — the flat options above are
-# aliases and UNION with it when both are set), plus the opt-in PII
-# detection tier (typed placeholders; see "PII detection (opt-in)"):
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"),
-                redact: {
-                  secrets: %w[internal_ref voucher_code],   # == redact_keys (tail mask)
-                  pii: %w[customer_email full_name],        # == redact_pii_keys (full [REDACTED])
-                  detect: %w[email phone ssn credit_card ip], # value-shape detection → [EMAIL], [PHONE], …
-                })
-# An unknown field, a non-Array value, or an unknown detect entity raises at boot:
-# Foam::Otel.init(..., redact: { detect: ["name"] })
-# => raises ArgumentError: Foam::Otel.init redact: unknown detect entity "name" — the valid
-#    entity names are exactly {email, phone, ssn, credit_card, ip} (contract/pii-detect.json)
-```
+The `pg`, `mysql2`, and `trilogy` instrumentations send the full SQL
+statement (`db_statement: :include`); the others keep their upstream
+defaults. To disable one instrumentation or change its options, pass it
+in `additional_instrumentations` or use the upstream environment
+variables, which take precedence:
+`OTEL_RUBY_INSTRUMENTATION_<NAME>_ENABLED=false` and
+`OTEL_RUBY_INSTRUMENTATION_<NAME>_CONFIG_OPTS`, where `<NAME>` is the
+instrumentation's class name after `OpenTelemetry::Instrumentation::`,
+upper-cased, with `::` replaced by `_`: `PG`, `NET_HTTP`, `ACTIVERECORD`.
 
-```ruby
-# Only if your legitimate telemetry collides with the generic secret
-# heuristics (e.g. base64 content-addressed ids masked as high-entropy
-# tokens): disable the HEURISTIC tier only. The named provider patterns and
-# the credential floor stay on — they have no off switch. Logs one loud
-# [foam] line.
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"),
-                secret_heuristics: false)
-```
+## Public API
 
-```ruby
-# Constructed tier-2 instrumentation instances (fault-isolated; one that
-# throws is skipped with a [foam] warning, never a crashed boot):
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"),
-                additional_instrumentations: [
-                  OpenTelemetry::Instrumentation::Sidekiq::Instrumentation.instance,
-                  [OpenTelemetry::Instrumentation::PG::Instrumentation.instance, { db_statement: :omit }],
-                ])
-```
+Every method lives on the `Foam` module. Every helper is a no-op
+before `init` and never raises.
+
+### `init`
+
+Sets up tracing, metrics, logs, automatic instrumentation, W3C
+`tracecontext` and `baggage` propagation, and OTLP export to Foam.
+
+Call this once. Use it when Foam should run OpenTelemetry for the process.
 
 ```ruby
-# Tenant seam, logs + metrics (spans are shown in scenario 3 below):
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"),
-                additional_log_record_processors: [EvalTool::LogRecordProcessor.new],
-                additional_metric_readers: [EvalTool::MetricReader.new],
-                ignored_outbound_hosts: ["ingest.eval-tool.example"]) # the tenant loop guard — required
+require "foam/otel"
+
+Foam.init(
+  name: "checkout-api",
+  environment: "production",
+  enabled: true,
+  token: ENV["FOAM_OTEL_TOKEN"],
+  version: "1.0.0"
+)
 ```
 
 ```ruby
-# The before_send export hook (1.8.0): transform or drop spans/logs right
-# before they are exported to foam — after batching, BEFORE redaction and
-# serialization (a dropped record never leaves the process). Return the
-# record (mutate in place freely) or nil to drop; a raising hook drops ONLY
-# its record, loudly, and never raises into your threads (fail-closed).
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"),
-                before_send: lambda { |record|
-                  next nil if record.respond_to?(:name) && record.name == "GET /healthz" # drop noise
-
-                  record.attributes.delete("internal.debug.blob") # trim before it ships
-                  record
-                })
-# Or an Array pipeline — hooks run in order, each receiving the previous
-# hook's return; the first nil drops the record and short-circuits:
-# Foam::Otel.init(..., before_send: [DropHealthchecks, TrimDebugAttrs, StampTeam])
+Foam.init(
+  name:,
+  environment:,
+  enabled: true,
+  token: nil,
+  version: nil,
+  sample_rate: 1.0,
+  additional_instrumentations: [],
+  additional_span_processors: [],
+  additional_log_record_processors: [],
+  additional_metric_readers: [],
+  additional_resource_attributes: {},
+  disable_log_sending: false,
+  network_capture: :basic,
+  ignored_outbound_hosts: [],
+  redact: nil,
+  before_send: nil
+)
 ```
 
-```ruby
-# Verbose self-reporting while wiring foam up (warnings are loud regardless):
-Foam::Otel.init(name: "checkout-api", environment: "development", enabled: true,
-                token: ENV.fetch("FOAM_OTEL_TOKEN"), diagnostics: true)
+`name` and `environment` are required. `token` is required only when Foam
+is enabled; store it as `FOAM_OTEL_TOKEN` and pass it in.
+
+- `name` - the service name, sent as `service.name`.
+- `environment` - the deployment environment, sent as
+  `deployment.environment.name`.
+- `enabled` - `false` turns Foam off; `init` returns without configuring
+  OpenTelemetry.
+- `token` - the Foam ingest token, sent as a bearer token on every export.
+  Required; a missing token is reported on stderr and leaves Foam
+  uninitialized.
+- `version` - the service version, sent as `service.version` when given.
+- `sample_rate` - a number from `0.0` to `1.0`. Rarely if ever updated.
+  Only change it for services sending telemetry in the petabytes range.
+  `OTEL_TRACES_SAMPLER` is not consulted.
+- `additional_span_processors`, `additional_log_record_processors`,
+  `additional_metric_readers` - the app's own OpenTelemetry components, added
+  to Foam's providers after Foam's own exporters.
+- `additional_resource_attributes` - attributes merged into the resource
+  of every signal. `service.name`, `service.version`, and
+  `deployment.environment.name` come from the options above; a value for
+  one of them here is reported on stderr and ignored.
+- `additional_instrumentations` - instrumentations to install next to the
+  bundle. An entry is an instrumentation's registry name, its class name
+  without the trailing `::Instrumentation`
+  (`"OpenTelemetry::Instrumentation::Logger"`), or a `[name, config]` pair
+  to install it with options
+  (`["OpenTelemetry::Instrumentation::PG", {db_statement: :obfuscate}]`).
+  Require the instrumentation's gem before `init`; an entry whose
+  instrumentation is not loaded fails `init`. An entry naming a bundled
+  instrumentation replaces Foam's configuration for it.
+- `ignored_outbound_hosts` - skips tracing of outbound HTTP requests to
+  these hostnames. The endpoint host is always skipped. Use it for hosts
+  whose traffic would drown the traces, such as a sidecar health check on
+  `localhost` or another vendor's OTLP ingest host. Hosts are compared as
+  written; `localhost` and `127.0.0.1` are different hosts. A request to a
+  skipped host still carries a `traceparent` marked not sampled, so an
+  OpenTelemetry service behind it records nothing for that request.
+- `disable_log_sending` - `true` stops shipping the app's `Logger` lines to
+  Foam. `Foam.log` is unaffected. See Loggers.
+- `network_capture` - `:off`, `:basic`, or `:advanced`. See Network
+  capture.
+- `redact` - keys to mask beyond the built-in list, as
+  `{secrets: [...], pii: [...]}`. A value under a `secrets` key keeps its
+  last four characters when it is 12 characters or longer; a value under
+  a `pii` key is fully masked. See Redaction.
+- `before_send` - a callable that receives each span and log record before
+  export and returns it, edited or not, to send it, or `nil` to drop it.
+  See Before send.
+
+Every signal carries a resource with the service identity from the options
+above, `telemetry.distro.name` and `telemetry.distro.version` naming this
+gem, `host.name`, `host.arch`, `host.id`, `os.type`, and `os.version`, and
+the process and SDK attributes the OpenTelemetry SDK adds.
+`OTEL_RESOURCE_ATTRIBUTES` can add further attributes. It cannot override
+any of the attributes above, and `OTEL_SERVICE_NAME` cannot override
+`name`.
+
+`init` never raises. A failure or an option holding an invalid value is
+reported on stderr with a `[foam-otel]` prefix and leaves `state`
+uninitialized.
+
+`init` also reports its outcome to Foam: one log record with the message
+and the `state`, sent straight to the endpoint with the token. It is sent
+in the background, never blocks the app, and is dropped when it cannot be
+delivered. Nothing is sent without a token.
+
+### `set_endpoint(url)`
+
+For tests and local development only. Sets the OTLP/HTTP base URL,
+without a signal path, that every export and report goes to, such as a
+local collector. Production apps do not call it: the default is Foam's
+ingest endpoint, `https://otel.api.foam.ai`.
+
+Call it before `init` or before creating an ingest component. Exporters
+keep the endpoint they were built with: a call after `init` is reported on
+stderr, and only later reports follow the new value.
+`OTEL_EXPORTER_OTLP_ENDPOINT` and the per-signal endpoint variables are not
+consulted.
+
+### `create_foam_ingest_span_processor(name, environment, token, redact: nil, before_send: nil)`
+
+Returns a span processor that exports traces to Foam without taking over
+the global tracer provider.
+
+Use it when another OpenTelemetry SDK already owns traces and Foam is
+only an extra export destination. Attach it to that provider.
+
+```ruby
+processor = Foam.create_foam_ingest_span_processor(
+  "checkout-api",
+  "production",
+  ENV["FOAM_OTEL_TOKEN"]
+)
+tracer_provider.add_span_processor(processor)
 ```
 
-And the unhappy path — a blank required argument fails AT BOOT, on your
-machine, never silently:
+### `create_foam_ingest_log_record_processor(name, environment, token, redact: nil, before_send: nil)`
+
+Returns a log record processor that exports logs to Foam without taking
+over the global logger provider. It also gives `log` a provider of its
+own, so `log` delivers without `init`.
 
 ```ruby
-Foam::Otel.init(name: "", environment: "production", enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"))
-# => raises ArgumentError: Foam::Otel.init requires a non-empty name
+processor = Foam.create_foam_ingest_log_record_processor(
+  "checkout-api",
+  "production",
+  ENV["FOAM_OTEL_TOKEN"]
+)
+logger_provider.add_log_record_processor(processor)
 ```
 
-**Deliberately absent** (and why): `endpoint`, `cadence`/`sampling`,
-`is_production`, `force_export`, `disabled_environments`, and any
-processor/exporter injection beyond the tenant seam. Customers identify their
-service and turn foam on or off; they can never drop a share of the data, inject
-their own pipeline pieces, or redirect export from code. The only endpoint
-override is the operator-level `OTEL_EXPORTER_OTLP_ENDPOINT` env var (below).
-
----
-
-## The default credential denylist (the always-on floor)
-
-Always on in every foam SDK, identical everywhere (frozen fixture:
-`contract/credential-denylist.json`). This is the ONE exception to foam's
-raw-by-default capture, and it has **no off switch** — no init option, no env
-var, and no door-2 parameter can disable, shrink, or re-spell it.
-
-**What is masked.** The VALUE of every header/attribute/field whose NAME is on
-the frozen list, in every signal (spans — events and links included — logs,
-metrics), on door 1, on all three door-2 ingest taps, and in the view handed
-to tenant `additional_*` processors:
-
-- **(a) the seven credential headers**, matched as header names wherever
-  headers are captured — including the semconv
-  `http.request.header.<name>` / `http.response.header.<name>` span-attribute
-  forms: `authorization`, `proxy-authorization`, `cookie`, `set-cookie`,
-  `x-api-key`, `x-auth-token`, `www-authenticate`;
-- **(b) the frozen 52-entry key list** of
-  `contract/credential-denylist.json` (the deduplicated union of those seven,
-  sentry-python's default denylists, and foam's documented reference roots —
-  `password`, `token`, `secret`, `api_key`, `ssn`, `jwt`, `private_key`,
-  `connect.sid`, `phpsessid`, …), matched as attribute/field names at every
-  depth the engine walks, and per-key in URL query strings
-  (`?token=x&user=bob` → `token=[REDACTED]&user=bob`).
-
-**The matching rule.** Case-insensitive, dash/underscore-normalized **EXACT
-name-equality — never substring**: `authorization` masks the header/field
-`authorization` (any casing, `-`≡`_`) and nothing else — `authorization_url`,
-`x_api_key_id`, `secretary`, and `session_count` all ride RAW. Dotted entries
-match verbatim and whole (`connect.sid` masks; `user.session` does not). This
-is deliberately STRICTER matching than your own `redact_keys` lists, which
-keep their documented substring behavior.
-
-**The mask.** The full literal `[REDACTED]` — no tail, no length
-preservation. These are credentials, not debug aids. Semconv header
-attributes (string arrays) mask per element, preserving arity.
-
-**Precedence.** The floor runs unconditionally BEFORE your
-`redact_keys`/`redact_pii_keys`, which stay purely additive on top. Listing a
-floor name in `redact_keys` does NOT downgrade it to a tail mask — the floor
-is terminal. `enabled: false` stays fully inert exactly as before (nothing
-exports at all — the floor masks data that leaves; inert mode has none).
-
-**Everything else stays RAW — above the floor and the value layer.** The
-floor matches NAMES only, never values. Credential-SHAPED value spans are the
-value-pattern secret layer's job (next section); UNSHAPED values — bodies,
-query values, SQL text, LLM content, and PII under unlisted names — export
-byte-identical raw, exactly as documented everywhere else in this README.
-
-**Why.** Coverage-over-masking remains the mission, but raw `Authorization`
-headers, cookies, and API keys on the wire are a breach in waiting for every
-customer at once — foam carves out exactly this list (and only
-this list) as non-negotiable. The list is byte-identical in every foam SDK
-and gate-checked in CI against the shipped fixture
-(`spec/credential_floor_spec.rb`).
-
-**Param names across the foam SDKs** (the customer options above the floor,
-identical concept in every SDK — the floor itself has NO init surface anywhere):
-
-| Concept | js/otel | js/browser | python | ruby | java |
-|---|---|---|---|---|---|
-| secret keys (tail-mask) | `redactKeys` | `redactKeys` | `redact_keys` | `redact_keys:` | `.redactKeys(String…)` |
-| PII keys (full `[REDACTED]`) | `redactPiiKeys` | `redactPiiKeys` | `redact_pii_keys` | `redact_pii_keys:` | `.redactPiiKeys(String…)` |
-
-> **Migration note — 1.3.0 (minor): always-on credential masking.** As of
-> this version foam masks, by default and in every signal, the VALUES of a
-> fixed list of credential/secret header and field NAMES (`authorization`,
-> `cookie`, `set-cookie`, `proxy-authorization`, `x-api-key`, `x-auth-token`,
-> `www-authenticate`, and the 52-name key list in
-> `contract/credential-denylist.json` — Sentry-parity plus foam's documented
-> roots) to the literal `[REDACTED]`. Matching is exact name-equality,
-> case-insensitive, dash/underscore-insensitive — never substring:
-> `authorization_url` is untouched. Everything else still exports RAW exactly
-> as before; `redact_keys`/`redact_pii_keys` are unchanged and additive.
-> There is no off switch — if a dashboard keyed off a raw credential value
-> (it should not have), it will now see `[REDACTED]`. Customers who
-> previously received these header/field values raw stop receiving them.
-
----
-
-## The value-pattern secret layer (always-on)
-
-The credential floor masks by NAME and is deliberately value-shape-blind — a
-live AWS key under the field name `note` would sail past it. Foam telemetry is
-read downstream by LLMs, so a leaked credential is exfiltratable by prompt
-injection; "no leakage at all" is the bar. The value-pattern secret layer is
-the second always-on control:
-
-**What it masks.** Credential-SHAPED value spans, regardless of the field
-name they hide under: AWS access-key ids and keyword-anchored AWS secrets,
-GCP API keys, Azure client/storage secrets, GitHub tokens and fine-grained
-PATs, GitLab tokens, Slack tokens + webhooks, Stripe secret keys
-(publishable `pk_` keys are deliberately NOT masked), JWTs, PEM private-key
-blocks (`-----BEGIN … PRIVATE KEY` — a truncated block masks to the end of
-the value, fail-closed; `PUBLIC KEY`/`CERTIFICATE` blocks never match) and
-PuTTY PPK keys, `scheme://user:pass@` URI credentials (the whole userinfo,
-username included), `Bearer`/`Basic` auth values, and Anthropic/OpenAI API
-keys. The matched span becomes the literal `[REDACTED]` — no tail, no
-prefix, zero reconstructable bytes; surrounding text keeps its diagnostic
-value (`conn to postgres://[REDACTED]@db:5432 refused`).
-
-**The heuristic tier** additionally catches the long tail: a
-keyword-anchored generic pass (`password = hunter2SecretXyz99` inside a log
-body masks its value — gitleaks-derived, entropy-gated, with placeholder/
-stopword/key-context false-positive suppression) and a whole-value
-high-entropy base64 token pass (detect-secrets-derived; pure hex and UUIDs
-are deliberately exempt — trace ids and digests are telemetry's ambient
-vocabulary). Only this tier is disableable: `secret_heuristics: false`
-(one loud `[foam]` line; the named patterns above are not configurable).
-
-**Where it runs.** Every value-bearing string on every export path, both
-doors: span/event/link attribute values, `status.message`, exception
-messages, log bodies (string and structured leaves), SQL (`db.statement`),
-LLM content (BEFORE serialization and again at the boundary), URL query AND
-fragment pair values, baggage-derived attributes, exemplar
-`filtered_attributes`, and resource identity strings (once, at init).
-Metric datapoint attributes (metric labels) are the one exempt surface —
-low-cardinality by construction; a value mask there would break your
-aggregation dimensions.
-
-**Bounded by design.** Compile-once rules, a literal-anchor pre-filter (no
-anchor in the value → zero regexes run), a 256 KiB value cap (an oversized
-value with an anchor hit anywhere masks WHOLE, fail-closed; without one it
-passes untouched), a match-flood cap, a 256-pair query/fragment tokenizer
-cap, and a per-Regexp timeout on Ruby ≥ 3.2. ANY scanner fault masks the
-value rather than shipping it raw.
-
-**Provenance.** The ruleset derives from MIT/Apache-licensed OSS secret
-scanners (gitleaks, detect-secrets, secretlint) — see `THIRD-PARTY-NOTICES`.
-Rules are frozen module constants, byte-consistent across all foam SDKs —
-not configurable per app.
-
-> **Migration note — 1.4.0 (minor): value-pattern secret masking + redaction
-> coverage fix + TLS pin.** foam now masks credential-SHAPED values
-> (AWS/GCP/Azure keys, GitHub/GitLab tokens, Slack, Stripe, Anthropic/OpenAI
-> keys, JWTs, private-key blocks, `user:pass@` URI credentials, bearer/basic
-> tokens) to `[REDACTED]` in every exported string value — regardless of
-> field name — plus a generic keyword+entropy heuristic you can disable with
-> `secret_heuristics: false` (the named patterns and the credential floor
-> cannot be disabled). Redaction now also reaches URL FRAGMENTS (OAuth
-> implicit-flow tokens, hash-router params), bare `k=v` pair lists, nested
-> attribute containers (fail-closed), and structured LLM content BEFORE
-> serialization. Query/fragment tokenizing is capped at 256 pairs (the
-> overflow remainder masks whole). Metric labels are not value-scanned. TLS
-> peer verification is now PINNED on every exporter:
-> `OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE` is INERT and loudly warned about.
-> If a dashboard keyed off a raw token value (it should not have), it will
-> now see `[REDACTED]`.
-
----
-
-## PII detection (opt-in)
-
-The floor and the secret layer protect credentials. PII in VALUES — an email
-address inside a log line, a card number inside an exception message — still
-exports RAW by default, because coverage-over-masking is the mission and only
-you know your privacy posture. As of 1.5.0 you can opt into value-shape PII
-detection per entity, via `redact: { detect: [...] }` (frozen fixture:
-`contract/pii-detect.json` — the entity names and
-placeholders are byte-identical in every foam SDK and gate-checked in CI by
-`spec/pii_detect_spec.rb`). Nothing detects unless you list the entity —
-an empty/absent `detect` list is exactly today's behavior.
-
-**The exact entity set** (these five, nothing else — an unknown name raises
-at boot):
-
-| Entity | Placeholder | Catches |
-| --- | --- | --- |
-| `email` | `[EMAIL]` | `john.smith+test@example.co.uk` — requires a real TLD (`user@localhost` rides raw) |
-| `phone` | `[PHONE]` | `+1 (415) 555-0142`, `415-555-0199` — separated groups; bare digit runs, dotted versions (`2024.10.05`) and clock times ride raw |
-| `ssn` | `[SSN]` | `536-90-4399`, `536 90 4399` — delimited 3-2-4 only; structurally invalid SSNs (`000-…`, group `00`, serial `0000`) and undelimited runs ride raw |
-| `credit_card` | `[CREDIT_CARD]` | 13–19 digit PANs (spaced/dashed/contiguous) that pass **Luhn** — a card-shaped tracking id failing the checksum is never masked |
-| `ip` | `[IP]` | IPv4 (octet-validated — `999.1.1.1` and `10.4.1.2000` ride raw) and IPv6, `::`-compressed included |
-
-**How it masks.** Only the matched character span is replaced with the
-entity's typed placeholder — surrounding text keeps its diagnostic value
-(`login from [IP] flagged`). It runs everywhere the value-pattern secret
-layer runs (span/event/link attributes, `status.message`, log bodies, URL
-query and fragment leaves, nested structures, both doors), immediately AFTER
-the secret layer (a shaped credential still becomes `[REDACTED]` — detect
-never weakens it) and BEFORE your key lists; metric datapoint attributes stay
-exempt exactly like the secret layer. Detection is idempotent (placeholders
-never re-match), rides the same execution caps and fail-closed discipline
-(any detector fault masks the whole value to `[REDACTED]`, loudly), and the
-patterns follow the same bounded-quantifier authoring rules.
-
-**What it can NOT do — read this before relying on it.** This is value-SHAPE
-detection, nothing more: **person names and free-text prose are NOT
-detectable** — recognizing "the patient, John Smith, reported…" takes
-server-side NER, which is platform scope, not an SDK regex. Field-NAME-keyed
-PII (`patient_name`) is what `redact: { pii: [...] }` is for; enumerate those
-keys yourself. Foam still ships no PII preset — the detect list is your
-explicit, audited enumeration.
+### `create_foam_ingest_metric_reader(name, environment, token, redact: nil)`
+
+Returns a metric reader that exports metrics to Foam without taking over
+the global meter provider.
 
 ```ruby
-# Door-2 taps take the same redact object, scoped to that tap:
-processor = Foam::Otel.create_ingest_span_processor(
-  token: ENV.fetch("FOAM_OTEL_TOKEN"), environment: ENV.fetch("APP_ENV"),
-  redact: { pii: %w[customer_email], detect: %w[email credit_card] })
+reader = Foam.create_foam_ingest_metric_reader(
+  "checkout-api",
+  "production",
+  ENV["FOAM_OTEL_TOKEN"]
+)
+meter_provider.add_metric_reader(reader)
 ```
 
----
+All three export to the endpoint set by `set_endpoint` and take the same
+`redact` option as `init`. The span processor and the log record processor
+also take the same `before_send` option; the metric reader does not. Each
+one records its signal as `ingest` in `state` and reports the attachment
+to Foam.
 
-## The `before_send` hook
+Foam identifies the service by the `name` and `environment` passed in: on
+the copy sent to Foam they overwrite the provider's `service.name` and
+`deployment.environment.name`, and `foam.ingest.host` names the host of
+the endpoint the copy goes to. The provider's own telemetry is left
+unchanged. Pass the same values to all three.
 
-`before_send:` is the last word your code gets on every span and log record
-before it is exported to foam. It runs at the **export boundary** — after the
-batch processor hands foam the finished records, immediately **before**
-foam's redaction pass and the OTLP serialization — so a record your hook
-drops is never serialized and never leaves the process. (This is the same
-seam redaction lives at, and for the same Ruby SDK reason: a span's
-attributes freeze at finish before any `on_finish` processor runs, so a
-`SpanProcessor` could neither mutate nor drop. The export boundary is the
-first point where the record is a mutable struct.)
+Unlike every other public method, these raise `ArgumentError` when `name`,
+`environment`, or `token` is blank or `redact` or `before_send` is invalid.
 
-The pipeline order is pinned:
+Do not combine `init` and an ingest component for the same signal. The
+ingest components do not install instrumentations; register the ones the
+app needs with the OpenTelemetry SDK directly.
 
-```
-BatchProcessor → before_send hooks → redaction (floor + your lists) → OTLP wire
-```
+### `inject_trace_context(carrier)`
+
+Writes the W3C `traceparent`, `tracestate`, and `baggage` headers for the
+current span into `carrier`, a hash of string keys.
 
-Your hooks run **first**, on the raw record (it is your own data, still
-in-process), and redaction runs on whatever they return — so `before_send`
-can never widen what ships: an attribute a hook adds is masked by the
-credential floor and your redact lists exactly like one an instrumentation
-set.
-
-The per-record contract (Sentry `beforeSend` semantics):
-
-* **return the record — or a replacement of the same type** → it continues
-  to the next hook / to export. Mutating it in place is supported —
-  `record.attributes` arrives as your own unfrozen copy (values included),
-  so `record.attributes["k"] = v`, `record.attributes.delete("k")`,
-  `record.attributes["k"].gsub!(...)` and (for logs) editing `record.body`
-  all just work without bleeding into the span your app still holds or the
-  view a tenant processor saw. Events, links and status are the exception:
-  **replace them wholesale** (`record.events = [...]`) — never mutate them
-  in place, they are shared structures. Foam re-normalizes the record's
-  `total_recorded_*` bookkeeping after your hooks run, so adding/deleting
-  attributes never corrupts the wire's dropped-count accounting.
-  `record.resource` and `record.instrumentation_scope` are **identity, not
-  payload**: read them freely, but edits and replacements are discarded —
-  the original identity objects always ship (they are process-global and
-  the encoder groups by them; a writable resource would also bypass
-  redaction, which never masks resource attributes).
-* **return `nil`** → the record is dropped, silently (that is the filter
-  mechanism, not an error).
-* **raise, or return a foreign object** → that record is dropped
-  **loudly** — one aggregated `[foam]` warning per batch, error classes
-  only (messages can carry your data) — and the batch reports failure:
-  fail-closed, a faulted hook never ships a record you may have meant to
-  scrub, and never raises into your application or export threads. Healthy
-  records in the same batch still export. Because a fault marks the whole
-  batch failed, a hook that faults **deterministically** also makes the
-  at-exit flush report failure — fix faulting hooks promptly (GOTCHAS F16).
-
-**Hooks run on foam's export thread, inside the batch processor's export
-lock.** Keep them fast and non-blocking: no network calls, no DB lookups,
-no sleeping — a blocked hook stalls the export pipeline and can wedge the
-at-exit flush. Anything a hook needs from the request/job thread
-(tenant context, user identity) must be stamped onto the record as an
-attribute at capture time (see the `additional_span_processors` stamper
-pattern); thread-locals are gone by the time the hook runs.
-
-Boot validation is strict: a non-callable — or a **lambda/Method
-whose signature cannot accept one positional argument** (e.g. a Sentry-port
-`->(event, hint) { ... }` with two required params, or a required keyword)
-— raises `ArgumentError` at `init`, because it would otherwise fault on
-every record and ship zero telemetry from a green boot. Make the extra
-Sentry `hint` param optional (`->(event, hint = nil)`) and it is accepted.
-
-Scope: **spans and log records** (the two record-shaped signals — the hook
-receives `SpanData` or `LogRecordData`; distinguish them with `is_a?` or
-`respond_to?`). Metrics are aggregated state, not discrete records, and are
-deliberately not routed through `before_send`. Door-2 ingest taps are
-unchanged. Like `enabled:` and the endpoint, `before_send` is process-global:
-the exporter chain is built at the first `init`, and a second `init` never
-changes it.
-
----
-
-## The helpers
-
-All helpers never raise, and no-op silently before `init` and when disabled.
-
-**Lifecycle**
+Use it when the app sends a message itself (a Kafka record, a queue payload,
+a custom socket). The HTTP instrumentations already inject these headers;
+do not call it on ordinary HTTP requests. Writes nothing when no span is
+active.
 
 ```ruby
-Foam::Otel.flush       # force-flush buffered pipelines (call at handler/worker exit)
-Foam::Otel.shutdown    # flush + shut down providers (normal exit is auto via at_exit)
-Foam::Otel.after_fork! # restart metric-reader threads after a fork (see cluster mode)
+headers = {}
+Foam.inject_trace_context(headers)
+producer.publish(topic, payload, headers: headers)
 ```
 
-**Traces**
+### `extract_trace_context(carrier)`
+
+Reads those headers from `carrier` and returns an OpenTelemetry context.
+Run the receiving work inside it so its spans continue the sender's trace.
+Returns the current context when the carrier has no trace headers.
 
 ```ruby
-result = Foam::Otel.span("nightly-sync") do |span|
-  # ... work ...  the span always ends; a raised error is recorded + re-raised
+context = Foam.extract_trace_context(message.headers)
+OpenTelemetry::Context.with_current(context) do
+  tracer.in_span("consume") { handle(message) }
 end
+```
+
+Foam's helpers always speak W3C, whichever propagator the SDK configured
+globally (see `OTEL_PROPAGATORS`).
 
-Foam::Otel.set_attribute("user.tier", "pro")           # on the active span; false if none recording
-Foam::Otel.set_attributes("a" => 1, "b" => 2)
-Foam::Otel.add_event("cache.miss")
-Foam::Otel.record_exception(e)                          # records on active span; never notifies a tracker
-ctx = Foam::Otel.get_trace_context                      # {trace_id:, span_id:} hex, or nil — never fabricated
+### `set_baggage(key, value)`
+
+Adds a key-value pair to the current context's baggage. Baggage travels
+with the trace context to every downstream service, where `baggage(key)`
+reads it; it is not written onto spans. The value lasts for the rest of
+the current scope, for example the rest of the request when called from a
+Rails controller, and is dropped when that scope ends. Outside any span or
+context scope the call is ignored and warned about once, so a value can
+never outlive the work it belongs to. No-op before `init`.
+
+```ruby
+Foam.set_baggage("tenant", current_tenant.id)
 ```
 
-**Metrics** (one helper per synchronous instrument; names pass through verbatim)
+### `baggage(key)`
+
+Returns the baggage value for `key`, whether set in this process or
+received from an upstream service, or `nil`.
+
+### Metric helpers
 
 ```ruby
-Foam::Otel.increment_counter("checkout.completed", by: 1, attributes: { "plan" => "pro" })
-Foam::Otel.record_histogram("checkout.duration_ms", 428)
-Foam::Otel.add_up_down_counter("queue.depth", by: -1)
-Foam::Otel.set_metric("cache.size_bytes", 10_485_760)   # gauge (last value wins)
+Foam.increment_counter("orders.placed", attributes: {"plan" => "pro"})
+Foam.record_histogram("checkout.duration", 0.42, unit: "s")
+Foam.add_up_down_counter("queue.depth", -1)
+Foam.set_metric("cache.size", 1024, unit: "By", description: "Entries in the cache")
 ```
 
-> ⚠️ Metric attributes are a loaded gun: an UNBOUNDED value (user id, raw path,
-> full URL) creates one metric stream per value — a memory leak that the SDK's
-> cardinality cap then turns into silently flat dashboards. Use bounded,
-> low-cardinality attribute values only.
+- `increment_counter(name, value = 1, ...)` adds to a counter that only
+  goes up.
+- `record_histogram(name, value, ...)` records one value in a histogram.
+- `add_up_down_counter(name, value, ...)` adds to a counter that can go
+  down; pass a negative value to decrement.
+- `set_metric(name, value, ...)` sets a gauge to its latest value.
+
+Every helper takes `attributes: {}`, `unit: nil`, and `description: nil`.
+The instrument is created on the first call for a name, and `unit` and
+`description` apply then; later calls reuse it. Values are exported on
+Foam's metrics pipeline under the `foam-otel` scope. Calls before `init`,
+or when Foam is disabled, are dropped.
+
+### `log(body, severity: :info, attributes: {})`
+
+Sends a log record to Foam on Foam's own export path. The record goes only
+to Foam: nothing is written to the app's log output, and nothing is emitted
+through a logger provider Foam does not own. A record emitted inside a
+request carries the trace and span ids of the current span.
+
+Use it to send a log directly, for example when the app's logger is not
+captured automatically (see Loggers).
 
-**Logs**
+`severity` is one of `:trace`, `:debug`, `:info`, `:warn`, `:error`,
+`:fatal`. Calls before `init`, or when Foam is disabled, are dropped.
 
 ```ruby
-Foam::Otel.log(:info, "checkout finished", attributes: { "order.id" => id })
-# severity is a level symbol (:trace :debug :info :warn :error :fatal) or an
-# OTel severity number (1..24). Trace-correlated when a span is active.
+Foam.log("checkout failed")
+Foam.log("checkout failed", severity: :error, attributes: {"order.id" => order.id})
 ```
 
-**Redaction**
+### `record_exception(exception, attributes: nil)`
+
+Records an exception on the active span and marks the span as errored,
+for exceptions the app rescues and handles itself. Unhandled exceptions
+are recorded by the instrumentation already.
 
 ```ruby
-Foam::Otel.redact(user_supplied_token)  # tail-masks a scalar you know is sensitive; [REDACTED] for structures
+begin
+  charge(order)
+rescue PaymentError => e
+  Foam.record_exception(e, attributes: {"order.id" => order.id})
+  render_retry_page
+end
 ```
 
-**Passthroughs** (the real OTel objects on foam's pipeline — links, span kinds,
-observable instruments, baggage all reachable here)
+The span gets an `exception` event with the type, message, and stack
+trace, plus any `attributes`, and its status becomes error with the
+exception's message. The active span is used whichever SDK started it.
+Without an active span nothing is recorded.
+
+### `flush(timeout: 30)`
+
+Exports everything Foam's providers still hold. Call it before a point
+where the process may be killed without a normal exit, for example at the
+end of a job on a runner that stops the process.
 
 ```ruby
-Foam::Otel.get_tracer("my.lib")
-Foam::Otel.get_meter("my.lib")
-Foam::Otel.get_logger("my.lib")
+Foam.flush(timeout: 5)
 ```
 
----
+`timeout` is in seconds and bounds the whole call. A provider that runs
+out of time is reported on stderr.
+
+### `shutdown(timeout: 30)`
+
+Flushes and shuts down Foam's providers, including the one behind `log`
+when an ingest component created it. Both `init` and the ingest log
+factory register it with `at_exit`, so most apps never call it. Call it
+yourself before a process is killed without a normal exit.
 
-## Coexistence — foam arriving in a monitored service
+`timeout` is in seconds and bounds the whole call. A provider that runs
+out of time is reported on stderr.
 
-`init` classifies each signal's global slot independently and does the right,
-non-destructive thing. The classifier's output is information for you, never a
-decision it makes for you.
+### `state`
 
-### Scenario 2 — beside a proprietary APM agent
+Returns whether Foam initialized, which instrumentations registered, which
+signals have an export path, and the identity `init` was given.
 
-Disjoint pipelines: foam runs its own beside the agent, touching nothing. Add the
-agent's intake host so foam's outbound instrumentation doesn't shadow its egress.
+Use it in health checks, tests, or diagnostics to confirm Foam is running.
 
 ```ruby
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FOAM_OTEL_TOKEN,
-                ignored_outbound_hosts: ["agent-intake.vendor.example"])
+Foam.state
+# {
+#   initialized: true,
+#   instrumentations: ["net_http@3.4.2", "pg@1.5.9", "rack@3.1.8", "rails@8.0.2", ...],
+#   signals: {
+#     traces: :global,
+#     metrics: :global,
+#     logs: :global,
+#     baggage: :global,
+#     profile: :none
+#   },
+#   params: {name: "checkout", environment: "production"}
+# }
 ```
 
-### Scenario 3 — a scoped tenant rides foam's pipeline (LLM-eval, AI-observability)
+`instrumentations` lists the instrumentations that installed, by gem name
+without the `opentelemetry-instrumentation-` prefix, with the version of
+the library each one instruments (`net_http` reports the Ruby version;
+`aws_lambda` has no version). An instrumentation whose library is absent
+or unsupported is left out.
 
-Attach the tenant's processor via the seam, and add its exporter host to the
-ignore list (its exports would otherwise be shadow-spanned into a loop).
+A library loaded after `init` is not instrumented and stays out of the
+list; a warning is written to stderr the first time a `state` call finds
+one. See Instrumentation for the bundle.
 
-```ruby
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FOAM_OTEL_TOKEN,
-                additional_span_processors: [EvalTool::SpanProcessor.new(project: "prod")],
-                ignored_outbound_hosts: ["ingest.eval-tool.example"])
-```
+`params` holds the `name` and `environment` passed to `init`, never the
+token, and is empty before `init`.
 
-> 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.
-> The Ruby SDK freezes span attributes at finish, so historically a tenant
-> processor saw third-party instrumentation attributes UNMASKED — as of 1.3.0
-> that gap is closed: tenant span/log processors are handed a READ-ONLY MASKED
-> VIEW (the credential floor plus your configured keys, the same pass foam's
-> own export applies — GOTCHAS F1). A tenant never sees a raw floor value.
-> With no keys configured (the default) only the credential floor 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
-> Faraday/HTTP (httprb)/HTTPX cannot be host-suppressed today (no upstream
-> `untraced_hosts` option — foam warns at init; GOTCHAS G13).
-
-### Scenario 4 — a foreign OTel SDK already owns a signal (door 2)
-
-If another OTel SDK registered (say) the tracer before foam, foam does NOT
-displace it. `init` warns once, naming the owner, and foam is dark for that
-signal — your tier-3 telemetry for it rides the foreign SDK to ITS backend.
-To ALSO send that pipeline to foam, add ONE LINE per claimed signal in THEIR
-setup — the ingest entries (see "Door 2 — the ingest entries" below). YOU
-place the tap: foam never attaches itself to a pipeline it does not own
-(their data moves only when a human says so), and the placement line doubles
-as the off-switch — gate it on the same condition you would give `enabled:`.
+Each `signals` value names the source of the Foam export path for that
+signal:
 
-```ruby
-# config/initializers/opentelemetry.rb — THEIR setup, plus the foam lines
-require "opentelemetry/sdk"
-require "foam/otel"
+- `:global` - `init` registered Foam's provider as the global provider.
+- `:ingest` - a `create_foam_ingest_*` object was built for another SDK's
+  pipeline.
+- `:local` - logs only: another SDK owns the global provider and Foam keeps
+  its own so `log` still delivers.
+- `:none` - no Foam export path.
 
-OpenTelemetry::SDK.configure do |c|
-  c.service_name = "their-service"
-  c.use_all
-  # REQUIRED loop step (see "Door 2 — the required loop step" below):
-  c.use "OpenTelemetry::Instrumentation::Net::HTTP", { untraced_hosts: ["otel.api.foam.ai"] }
-  c.add_span_processor(their_vendor_processor)           # their export, untouched
-  if ENV["APP_ENV"] == "production"                       # your consent AND your off-switch
-    c.add_span_processor(Foam::Otel.create_ingest_span_processor(
-      token: ENV.fetch("FOAM_OTEL_TOKEN"), environment: ENV.fetch("APP_ENV")))
-  end
-end
-```
+`:global` is checked against the live OpenTelemetry global at each call.
+When another SDK takes a slot after `init`, that signal reports `:none`
+(`:local` for logs) and a warning is written to stderr once. Only the slot
+is affected: the Foam helpers keep their own references and keep working.
+`profile` is not supported and always reports `:none`.
 
-**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, the
-always-on credential floor applied to foam's copy, and any per-tap
-`redact_keys`/`redact_pii_keys` you set (opt-in — none by default; details in
-the Door 2 section).
+## Custom spans and other OpenTelemetry APIs
 
-**Unhappy paths**:
+TODO(jhartquist)
 
-```ruby
-Foam::Otel.create_ingest_span_processor(token: "", environment: "production")
-# => raises ArgumentError: [foam] Foam::Otel.create_ingest_span_processor requires a non-empty token
-```
+## Network capture
 
-- `OTEL_SDK_DISABLED=true` at construction → the factory returns an inert
-  no-op instance (their setup line keeps working, nothing is sent) and warns:
-  `[foam] OTEL_SDK_DISABLED=true — this foam ingest entry is disabled by the
-  operator kill switch and will send nothing.`
-- Tap wired onto FOAM'S OWN pipeline (self-ingest wiring bug) → one loud
-  warning and the tap STANDS DOWN — door 1 already exports that data, so
-  nothing is lost and nothing is doubled.
-- `init()` already exports a signal AND a tap sits on a separate foreign
-  pipeline for the same signal → one loud warning; BOTH keep flowing
-  (different pipelines; `foam.ingest.tier` distinguishes the copies).
-
-When the TRACES slot is foreign-owned, foam also skips its automatic
-tier-1/2 instrumentation activation (it never adds span producers or Rack
-middleware to a pipeline it does not own) and warns once;
-`additional_instrumentations` you pass explicitly are still installed. The
-same holds for the process-wide propagator: a propagator the incumbent
-installed first is KEPT (foam installs its W3C set only over the API default),
-with one warning.
-
-### Scenario 5 — per-signal composition
-
-Signals are independent. A foreign SDK owning only traces still gets foam for
-metrics and logs on the full contract:
+`network_capture` defaults to `:basic` and controls extra HTTP detail on
+server and client spans.
 
-```ruby
-Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FOAM_OTEL_TOKEN)
-# → warns: traces foreign-owned (foam dark for traces); metrics + logs → foam, full contract.
-
-# The doors COMPOSE: add the traces tap in THEIR setup and foam receives
-# traces too — the tap rides THEIR tracer, and trace ids correlate with
-# foam-exported logs/metrics through the shared context:
-their_provider.add_span_processor(Foam::Otel.create_ingest_span_processor(
-  token: ENV.fetch("FOAM_OTEL_TOKEN"), environment: ENV.fetch("APP_ENV")))
-# (no double-claim warning: init() serves metrics+logs, the tap serves traces)
-```
+- `:off` keeps the standard OpenTelemetry HTTP telemetry, with no extra
+  capture.
+- `:basic` adds the `content-type`, `content-length`, and
+  `content-encoding` headers of the request and the response as span
+  attributes. No other header attribute is added.
+- `:advanced` adds the request and response bodies as well.
 
-### Scenario 6 — tests / CI (fully inert, no token needed)
+TODO(jhartquist): `:basic` headers on client spans.
 
-```ruby
-Foam::Otel.init(name: "checkout-api", environment: "test", enabled: false)
-```
+Header capture is applied through the Rack instrumentation. An
+`additional_instrumentations` entry naming it replaces this
+configuration.
 
-### Scenario 7 — serverless / short-lived (flush at the end)
+### Body capture
 
-```ruby
-Foam::Otel.init(name: "orders-fn", environment: "production", enabled: true, token: FOAM_OTEL_TOKEN)
+In `:advanced` mode each captured body arrives as `foam.http.body.chunk`
+log records correlated to the span, and the span carries the body's size
+and content.
 
-def handler(event:, context:)
-  run(event)
-ensure
-  Foam::Otel.flush   # the platform freezes the process before the batch timer fires
-end
-```
+- Bodies with a textual content type are captured. gzip and deflate are
+  decoded. Other encodings and binary types yield one record with the size
+  only.
+- At most 1 MiB of a body is kept, in chunks of at most 64 KiB. The rest
+  counts toward the size.
+- Bodies are redacted by content type with the same keys as span
+  attributes.
 
-### Puma / Unicorn (cluster mode) — CRITICAL
+### Rack bodies
 
-Exporter threads do not survive `fork`. Foam auto-recovers metric readers via a
-`Process._fork` hook, but the cleanest pattern is to `init` PER WORKER so each
-worker gets its own pipeline and a unique `service.instance.id`:
+Server bodies need `Foam::Rack::Middleware` directly after the
+OpenTelemetry Rack middleware, as shown under "Plain Ruby and Rack". A
+Rails app is not covered yet.
 
-```ruby
-# config/puma.rb
-on_worker_boot do
-  Foam::Otel.init(name: "checkout-api", environment: ENV["APP_ENV"], enabled: true, token: ENV["FOAM_OTEL_TOKEN"])
-  # or, if you init in an initializer: Foam::Otel.after_fork!
-end
-```
+- The request body is captured whether or not the app reads it when the
+  server buffers request bodies, as Puma does. Otherwise what the app reads
+  is captured.
+- A streamed response is captured chunk by chunk as the server sends it.
+- A streaming body (`call`), a file sent by path (`to_path`), and a hijacked
+  connection are not captured.
 
----
-
-## Door 2 — the ingest entries
-
-When a foreign OTel SDK owns a signal (scenario 4), the ingest entries are
-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.
-
-> **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 — the grouped `redact:` object and its legacy aliases
-`redact_keys:`/`redact_pii_keys:`, union semantics exactly as on `init` —
-are the only CUSTOMER redaction that tap applies — opt-in, none by
-default, scoped to that tap, additive above the always-on credential floor,
-which every tap applies with zero configuration; `diagnostics:` is tap-scoped
-narration). Construction
-validates loudly at boot and NEVER
-throws afterwards — a failure inside a tap can never break their pipeline.
-Naming across the foam SDKs (pinned by `spec/export_surface_spec.rb`):
-`create_ingest_span_processor` = `createFoamIngestSpanProcessor`,
-`create_ingest_log_record_processor` = `createFoamIngestLogRecordProcessor`,
-`create_ingest_metric_reader` = `createFoamIngestMetricReader`.
-
-**Traces** — a SpanProcessor for THEIR TracerProvider (scenario 4 snippet):
+### Client bodies
+
+Client bodies are captured on the client span of `Net::HTTP`, Faraday,
+Excon, and HTTPClient. Each client is patched in `:advanced` mode only, and
+only when its OpenTelemetry instrumentation installed. Other clients are
+not captured.
+
+- `Net::HTTP`: a request sent through `body_stream` and a response read in
+  a block or into an IO are not captured.
+- Faraday: bodies are captured on the Faraday span. A request sent from an
+  IO and a response streamed with `on_data` are not captured.
+- Excon: a request sent with `request_block` and a response received with
+  `response_block` are not captured.
+- HTTPClient: a request sent from an IO or as multipart parts is not
+  captured. A response read in a block is captured.
 
-```ruby
-processor = Foam::Otel.create_ingest_span_processor(
-  token: ENV.fetch("FOAM_OTEL_TOKEN"), environment: ENV.fetch("APP_ENV"),
-  redact_keys: %w[voucher_code],          # optional: extra secret keys, this tap only
-  redact_pii_keys: %w[customer_email],    # optional: your PII enumeration, this tap only
-  diagnostics: false)                     # optional: per-tap [foam] narration
-their_tracer_provider.add_span_processor(processor)
-# returns a new instance per call; no-op inert instance under OTEL_SDK_DISABLED=true;
-# raises ArgumentError at construction for a blank token/environment
-```
+## Loggers
 
-**Logs** — a LogRecordProcessor for THEIR LoggerProvider. The credential
-floor and 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):
+Every line written through the standard library `Logger` is sent to Foam
+as a log record carrying the current trace and span IDs. The record's body
+is the formatted line and its severity follows the `Logger` level. The
+app's log output is unchanged. A `Logger` created before `init` is
+covered. `Rails.logger` lines are sent once each. `puts` and direct
+writes to `$stdout` are not captured.
 
-```ruby
-provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: their_resource)
-provider.add_log_record_processor(their_log_processor)
-provider.add_log_record_processor(Foam::Otel.create_ingest_log_record_processor(
-  token: ENV.fetch("FOAM_OTEL_TOKEN"), environment: ENV.fetch("APP_ENV")))
-OpenTelemetry.logger_provider = provider
-```
+If the app already sends its logs through its own OpenTelemetry pipeline,
+set `disable_log_sending: true` so records do not arrive twice. If another
+SDK owns logs, set it and attach `create_foam_ingest_log_record_processor`
+to that SDK's provider. `Foam.log` delivers either way.
 
-**Metrics** — a PeriodicMetricReader for THEIR MeterProvider. Attach order is
-forgiving: `add_metric_reader` back-fills instruments created before the tap
-attached. Foam's reader collects on its own schedule beside theirs:
+TODO(jhartquist): working alongside other popular Ruby loggers.
 
-```ruby
-OpenTelemetry.meter_provider.add_metric_reader(Foam::Otel.create_ingest_metric_reader(
-  token: ENV.fetch("FOAM_OTEL_TOKEN"), environment: ENV.fetch("APP_ENV")))
-```
+## Pre-forking servers and threads
+
+TODO(jhartquist)
 
-### Door 2 — the required loop step
-
-The tap's exports to foam are outbound HTTP calls THEIR instrumentation will
-span, and their pipeline hands those spans back to the tap — a feedback loop
-in THEIR pipeline. Three layers keep it closed:
-
-1. **The SDK suppression context** (automatic): foam's exporters send inside
-   `untraced`, which the official http instrumentations respect.
-2. **REQUIRED — suppress foam's endpoint host in THEIR http instrumentation**
-   (belt for non-contrib patches and older contrib versions): add
-   `untraced_hosts: ["otel.api.foam.ai"]` to their Net::HTTP/Excon config
-   (scenario 4 snippet). When the `OTEL_EXPORTER_OTLP_ENDPOINT` override is
-   active, list THAT host instead. Faraday/HTTP (httprb)/HTTPX cannot take
-   the option, but they also never see the tap's exports — foam's exporters
-   use Net::HTTP only.
-3. **The echo filter** (structural backstop): a client-kind span naming the
-   ACTIVE foam export host is telemetry about foam's own export call — the
-   tap refuses to re-export its own echo, with one loud warning naming the
-   missing step. Their pipeline keeps that span untouched.
-
-### Identity on the wire
-
-| | 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 | the credential floor + your per-tap `redact_keys`/`redact_pii_keys` applied (default: floor only — everything off the frozen list 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) |
-
-The stamp is merged onto FOAM'S COPY at export serialization — never onto
-the shared objects; it changes exactly those four keys and nothing else.
-
-### External-tier caveats (recorded, never fought)
-
-- THEIR sampler gates what the traces tap sees (unsampled spans never reach
-  processors).
-- THEIR Views shape what the metrics tap receives; per-reader temporality is
-  not a Ruby knob — aggregations default cumulative (or the operator's
-  `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`), and cumulative totals
-  start at attach time.
-- Lifecycle rides THEIR pipeline: their provider's `shutdown`/`force_flush`
-  drives the tap's. Serverless mirror: flush THEIR provider at handler end
-  (the platform freezes the process before batch timers fire).
-- Kill switch and endpoint override apply to taps exactly as to `init`:
-  `OTEL_SDK_DISABLED=true` at construction → inert instance + one warning;
-  `OTEL_EXPORTER_OTLP_ENDPOINT` honored with the loud warning; per-signal
-  OTLP endpoint variants stay INERT + warned.
-
-### Puma / Unicorn note (door 2)
-
-Construct taps where THEIR setup runs — with `SDK.configure` in an
-initializer under cluster preload, taps are inherited by workers. The span
-and log taps self-heal in the child (the stock batch processors reset on
-first use after a fork); the metrics tap is restarted by foam's own
-`Process._fork` hook, which the factory installs (a separate registry from
-`init`'s own readers, so a per-worker re-init never orphans a tap — GOTCHAS
-R7). `Foam::Otel.after_fork!` covers both if you wire it manually.
-
-### Tests / CI
-
-Gate the add-line on the same condition you would give `enabled:` — the
-placement line IS the switch (no foam-invented env var):
+The current span and baggage are stored per fiber. A `Thread.new` or
+`Fiber.new` starts with none, so spans started inside it begin a new trace.
+To continue the trace, capture the context first and make it current
+inside the thread:
 
 ```ruby
-if ENV["APP_ENV"] == "production"
-  c.add_span_processor(Foam::Otel.create_ingest_span_processor(
-    token: ENV.fetch("FOAM_OTEL_TOKEN"), environment: ENV.fetch("APP_ENV")))
+context = OpenTelemetry::Context.current
+Thread.new do
+  OpenTelemetry::Context.with_current(context) { work }
 end
 ```
 
----
-
-## Failure modes — what happens and where the warning appears
-
-| Situation | Behavior |
-| --- | --- |
-| blank `name`/`environment`, or `enabled` omitted | raises `ArgumentError` at boot (on your machine) |
-| `enabled: true` but blank `token` | raises `ArgumentError` at boot |
-| `enabled: false` | fully inert; helpers no-op silently |
-| missing `version` | `[foam]` warning, continues |
-| a foreign OTel SDK owns a signal | `[foam]` warning once, naming the owner AND the matching door-2 ingest entry; foam dark for that signal |
-| `init` called twice | `[foam]` warning; returns the first instance (providers are process-global) |
-| ingest entry with blank `token:`/`environment:` | raises `ArgumentError` at construction (on your machine) |
-| ingest entry under `OTEL_SDK_DISABLED=true` | inert no-op instance + one `[foam]` warning; their setup line never crashes |
-| ingest tap wired onto foam's OWN pipeline | `[foam]` wiring-bug warning once; the tap STANDS DOWN (zero duplicates) |
-| `init()` exports a signal AND a tap on a separate foreign pipeline | `[foam]` wiring-bug warning once; both keep flowing (`foam.ingest.tier` distinguishes them) |
-| their instrumentation traces foam's export calls (missing loop step) | echo filter refuses foam's own echo + one `[foam]` warning naming the required `untraced_hosts` step |
-
----
-
-## Environment variables
-
-| Var | Posture |
-| --- | --- |
-| `OTEL_SDK_DISABLED=true` | HONORED — full kill switch, supersedes `enabled: true` (matched trimmed + case-insensitive, so `TRUE` / ` true ` also kill — this one emergency switch behaves the same in every foam SDK). Door-2 ingest entries honor it too: construction returns an inert instance (read once at construction; changing it implies a restart). |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | HONORED — the one operator-level override of the pinned foam endpoint (for foam's own conformance rig / enterprise egress). Active → loud `[foam]` warning naming the destination. Applies to door-2 taps identically (and moves the host the required loop step must name). |
-| `OTEL_PROPAGATORS=none` | HONORED — turns trace propagation OFF (links lost) while telemetry keeps flowing; warns. Any other value warns and is ignored (foam's propagator set is fixed: W3C tracecontext + baggage). |
-| `OTEL_BSP_SCHEDULE_DELAY` / `OTEL_BLRP_SCHEDULE_DELAY` / `OTEL_METRIC_EXPORT_INTERVAL` | HONORED — batch cadence, read natively by the upstream SDK. |
-| `FOAM_CAPTURE_PAYLOADS` | HONORED — the operator clamp over the `capture_payloads:` init option (`off`/`errors`/`always`, case-insensitive), overriding it in BOTH directions with one loud `[foam]` line when it changes the mode. An invalid value warns and falls back to the init option (never crashes a boot). This is the ONE foam-named env var the gem reads — an override valve over an init-declared option, never an on/off switch, token, or config fallback (those still arrive only through `init`'s explicit arguments). Read once at init; changing it implies a restart. |
-| `OTEL_RUBY_INSTRUMENTATION_RACK_CONFIG_OPTS` | HONORED (by the contrib rack gem itself) and RESPECTED by foam — a header option you set here (`allowed_request_headers=…` / `allowed_response_headers=…`) governs that option; foam's default header list fills only the option you did not touch (never widened, never overridden — see "Header capture"). The other `OTEL_RUBY_INSTRUMENTATION_<NAME>_CONFIG_OPTS` vars are likewise the contrib gems' own standard levers (e.g. the Sidekiq `propagation_style` note above). |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | INERT — foam wires ONE resolved endpoint into all three exporters explicitly, so per-signal endpoint vars never redirect (or split) foam's export. Set → loud `[foam]` warning that it is inert. |
-| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | INERT — as above (warns when set). |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | INERT — as above (warns when set). |
-| `OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE` | INERT — foam pins TLS peer verification (`ssl_verify_mode: VERIFY_PEER`) on every exporter constructor, both doors, so this vendored-exporter knob can never strip certificate verification off the credential-bearing export connection (1.4.0 security fix, CWE-295). Set → loud `[foam]` warning that it is inert; fix the trust chain (CA bundle) instead. |
-| every other `OTEL_*` | INERT — `OTEL_SERVICE_NAME` / `OTEL_RESOURCE_ATTRIBUTES` never override the init-declared identity; sampler/exporter/span-limit vars are ignored. |
-
----
-
-## Troubleshooting
-
-- **Telemetry halved or doubled after a dependency bump** → check for a second
-  copy of the OTel API first: `bundle list | grep opentelemetry-api` must show
-  ONE. Two copies mean two global registries (silent no-op or doubled data).
-- **No data at all** → set `diagnostics: true` and read the `[foam]` lines; check
-  `init` runs before your app code, that `enabled` is true, and that a token is
-  wired.
-- **No door-2 data** → check, in order: `OTEL_SDK_DISABLED` unset (a killed tap
-  is inert and warned once at boot); the tap is on the RIGHT provider (the one
-  their setup actually registers — a wiring-bug warning at first traffic means
-  self-ingest stand-down); the `[foam]` wiring-bug/echo warnings in the boot
-  log; construct with `diagnostics: true` for per-export narration; for
-  metrics under Puma, see the Door 2 Puma note.
-- **A downstream rejects `traceparent`** → set `OTEL_PROPAGATORS=none` to stop
-  injection while keeping telemetry flowing.
-
----
-
-See `GOTCHAS.md` (the traps and how foam handles them) and `RESEARCH.md` (the
-primitive audit, instrumentation census, and redaction provenance).
+## Redaction
+
+Foam masks the values of sensitive keys in everything it exports: span,
+span event, and span link attributes; log bodies and attributes; metric
+data point attributes; and resource attributes. A built-in list of
+credential and personal-data keys always applies, matched by exact name
+or by a sensitive segment of the key (`legacy_api_key_2`, `stripeToken`).
+Keys match after normalization: case, `-`, `.`, and camelCase boundaries
+are folded, so `apiKey`, `api-key`, and `API_KEY` are one key. Header
+attributes match on the header name. The sensitive pairs of a query
+string are masked in `url.query` and in any string value holding one.
+Captured HTTP bodies are masked by content type with the same keys, with
+their framing kept; a body the masking fails on is replaced whole.
+
+The `redact` option adds the app's own keys, matched exactly after the
+same normalization. A value under a built-in or `pii` key becomes
+`[REDACTED]`. A value under a `secrets` key becomes `********`, followed
+by its last four characters when it is 12 characters or longer.
+
+Masking changes values only: keys stay present, and span names, event
+names, and severity are untouched. It is applied after `before_send`, to
+the copy sent to Foam, through `init` and through the ingest components
+alike. The app's own span and log objects, and the copies handed to other
+processors and exporters, are unchanged.
+
+## Before send
+
+`before_send` is the app's last look at each span and log record before
+it is sent to Foam. The hook receives an event and returns it, edited or
+not, to send it, or `nil` to drop it. Metrics and Foam's own reports never
+pass through it.
+
+```ruby
+Foam.init(
+  # ...
+  before_send: ->(event) {
+    event unless event[:type] == :span && event[:attributes]["url.path"] == "/health"
+  }
+)
+```
+
+For a span, the event is a Hash with these keys:
+
+```ruby
+{
+  type: :span,
+  name: "GET /users",
+  attributes: {"url.path" => "/users"},
+  events: [{name: "exception", attributes: {"exception.type" => "..."}, timestamp: 1788538831415926535}],
+  links: [{span_context: span_context, attributes: {}}],
+  # Read-only
+  kind: :server,
+  status: status,
+  start_timestamp: 1788538831415926535,
+  end_timestamp: 1788538831417126534,
+  trace_id: trace_id,
+  span_id: span_id,
+  parent_span_id: parent_span_id,
+  instrumentation_scope: instrumentation_scope
+}
+```
+
+For a log record:
+
+```ruby
+{
+  type: :log,
+  body: "signed in",
+  severity_text: "INFO",
+  severity_number: 9,
+  attributes: {"user.id" => "42"},
+  # Read-only
+  timestamp: 1788538831415926535,
+  observed_timestamp: 1788538831415940102,
+  trace_id: trace_id,
+  span_id: span_id,
+  trace_flags: trace_flags,
+  instrumentation_scope: instrumentation_scope
+}
+```
+
+`name`, `attributes`, `events`, and `links` of a span and `body`,
+`severity_text`, `severity_number`, and `attributes` of a log record are
+sent as returned. The read-only fields hold what the SDK recorded, as the
+SDK holds it; edits to them are ignored. Timestamps are Integer
+nanoseconds since the epoch. An event added without a
+`timestamp` gets the span's start time. A link added needs a
+`span_context`.
+
+The hook receives a copy: edits reach Foam only through the return value,
+and the app's own span and log objects are unchanged. Redaction runs after
+the hook, so the hook sees values before masking and what it returns is
+masked before export. A hook that raises, or returns anything other than
+an event of the same type, leaves the event as it was, without a
+diagnostic. An event holding a value that cannot be copied is sent as it
+was without calling the hook. A span or log record emitted inside the
+hook passes through the hook itself.
+
+## OpenTelemetry configuration and compliance
+
+TODO(jhartquist)
+
+## OpenTelemetry Profiling
+
+Not supported. `state` reports `profile: :none`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec             # unit tests
+bundle exec rake e2e          # end-to-end tests
+bundle exec standardrb --fix  # lint and autoformat
+bundle exec rake              # unit, e2e, then lint (what CI checks)
+```
+
+The end-to-end tests run a real OTLP collector and the fixture apps under
+`e2e/apps/` with puma, then assert on what the collector received.
+`rake e2e` downloads the pinned `otelcol-contrib` release to
+`~/.cache/foam-otel` the first time (about 350 MB; set `FOAM_OTELCOL_DIR`
+to cache it elsewhere) and installs the fixture apps' bundles. Run one file
+with `bundle exec rspec e2e/spec/rack_init_spec.rb`.
+
+Each run writes the collector config, the received telemetry, and the
+output of both processes to `tmp/e2e/`. A failure prints the tail of both
+stderr files.