foam-otel 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb5e4f91fea3170bbb206582adade6ca516824edad064a4be911ebe912ce7abf
-  data.tar.gz: 67ee9186826b4bc31c7f51deeaf8fd91bec6aaec393099f23b000384821230b9
+  metadata.gz: 3e034361554ad48530554a1bdc62d75adf1899e3ef57104a367abd2c412d2f93
+  data.tar.gz: 40b6db9d7f11ed9105b00c9998b87da51e0822480d97da52be766ddea24435ca
 SHA512:
-  metadata.gz: 4c4c7288e2b049a9f686d0eae3637a74261820bc779d6e8ec4daf14347b6ed3b423648c4c0d226982663465907465fc350a44cd52b998ad97b4766b69ecb727b
-  data.tar.gz: 7eb2f27f17fc9fcd9649b72c68b59493b366ff66950c86ff42f4baa414b7ea222b9e251f30264adbfe32400fe7851b2cf64505bf666c5385546b44f4a5714768
+  metadata.gz: 9c71df1b9ce568dabd996b659d13e0bc05e93a81e070376a77e8c09ccd6a6fc51dcaa028c19a904e78d38daae532c6bc75077e3fa5331047aa1c64e08a9609ee
+  data.tar.gz: 90623d934372eb908d8c9d13e5ddd4108faad54bea4c5a647e7934959562ff130c2cdfdc2f0c5c5cc00a1a86eb5fcc4ee03c745c69c8c258fced2caf6ceb2f31

data/GOTCHAS.md

@@ -721,6 +721,91 @@ exfiltratable — the value-pattern secret layer is the required second control
   no-op + registration idempotence; `spec/conventions_spec.rb` (rule 21:
   header capture never grows a `rack.input` body tee).
 
+## F15: Opt-in payload (body) capture must TEE, never consume — and the rack span's lifetime decides when body attributes can land
+
+- **Trap**: five ways foam's opt-in body capture (`payload_capture.rb`,
+  behind `capture_payloads:` — default `:off`) could break the customer or
+  silently lose data. (1) Reading `env['rack.input']` ahead of the app —
+  or rewinding it — breaks Rack 3 apps: inputs are no longer required to
+  be rewindable, and a consumed stream starves the framework's own parser.
+  (2) Buffering the response to capture it breaks streaming (SSE, large
+  downloads), and Rack 3 `#call`-only streaming bodies must not be wrapped
+  at all — defining `#each` on the wrapper would change how the server
+  drives the response. (3) The official rack instrumentation ends its span
+  at DIFFERENT times per mode: the default `Rack::Events` handler finishes
+  it when the response body is CLOSED (`EventedBodyProxy` fires
+  `on_finish` after the inner body's close — so a tee flushing at close
+  writes in time), but the non-events `TracerMiddleware` ends it when
+  `@app.call` RETURNS — attributes flushed from a streamed body's close
+  there would hit an ENDED span (upstream logs a warning per write). (4)
+  An OUTER middleware (`Rack::MethodOverride`) reads the form body,
+  rewinds — or repositions via `seek(0)`/`pos=`, equivalent idioms on the
+  rewindable inputs real servers hand out — and the framework re-reads it:
+  a naive tee (or one that dedupes `rewind` alone) captures and counts it
+  twice. (5) The `:errors` mode needs "an exception was recorded on the
+  span" — re-implementing that check would duplicate
+  `Errors.record_once`'s dedupe registry and drift from it.
+- **Sources**: installed source — rack `body_proxy.rb:28-35` (`close`
+  closes the inner body BEFORE the proxy's block) and `:47-53` (`to_ary`
+  auto-closes), rack `events.rb:140-142` (the body proxy that fires
+  `on_finish` on close); opentelemetry-instrumentation-rack-0.31.1 stable
+  `event_handler.rb:109-117,199-205` (`on_finish`/`detach_context` finish
+  the span at body close) vs stable `tracer_middleware.rb:78-90`
+  (`in_span` ends the span when the block — `@app.call(env).tap` —
+  returns); Rack SPEC (input `gets`/`read`/`each`; `to_ary` bodies;
+  streaming `#call` bodies); `errors.rb:17-43` (the span-carried
+  `@__foam_otel_recorded` ivar registry).
+- **Decision & why**: delegating tees only, on BOTH directions, behind the
+  ONE mode switch. `:off` (the default) ships ZERO middleware (the Railtie
+  hook runs after `:load_config_initializers` — when init has resolved the
+  mode — and stands down; a manual `use` line is a one-branch
+  passthrough). The input tee observes exactly what the APP reads
+  (read/gets/each), delegates everything else with truthful `respond_to?`
+  (a non-rewindable input stays non-rewindable), and dedupes across EVERY
+  repositioning method — `rewind`, `seek`, `pos=` — with a
+  position/high-water scheme — bytes are captured and counted once no
+  matter how often an outer middleware repositions the stream. The response side
+  captures `to_ary`-able (buffered) bodies SYNCHRONOUSLY at middleware
+  return — the span is provably alive in both official modes — returning
+  the array as the new body (the Rack spec's sanctioned move;
+  `BodyProxy#to_ary` closes the original). Genuinely streaming `#each`
+  bodies are teed chunk-by-chunk, unbuffered, flushing attributes on
+  iteration-complete/close: that lands in the default `Rack::Events` mode
+  and is silently skipped (a `recording?` gate, no upstream warn-spam) in
+  `TracerMiddleware` mode — a recorded, documented loss shape, never a
+  broken stream. `#call`-only bodies are never wrapped (sizes ride the
+  declared Content-Length when present). `:errors` reads the SAME ivar
+  registry `Errors.record_once` stamps, through the thin
+  `Errors.recorded?` seam — one registry, no duplicated dedupe — plus the
+  status >= 500 triplet check; an exception raised through the middleware
+  attaches the request side before the IDENTICAL re-raise. Capture is
+  gated on foam OWNING the traces slot (rule 18 B — a foreign SDK's rack
+  span is never enriched) and on a recording span; every path is
+  individually rescued (rule 9). Redaction stays central: JSON-shaped body
+  strings are deep-masked BY FIELD NAME at the exporter boundary
+  (`redaction.rb` `BODY_ATTRIBUTE_NAMES` — floor + customer lists reach
+  inside the body JSON; a cap-truncated body no longer parses, so only the
+  value-shape scans cover it — documented limit).
+- **Mitigation**: `lib/foam/otel/payload_capture.rb` (the whole module:
+  the mode gate + FOAM_CAPTURE_PAYLOADS clamp plumbing, ownership/
+  recording gates, tees, `to_ary`/streaming discrimination,
+  textual/identity classification, the 8192-char cap + fleet truncation
+  marker); `lib/foam/otel/init.rb` (option validation + env clamp,
+  mode-gated Railtie-fallback wiring); `lib/foam/otel/errors.rb`
+  (`recorded?`); `lib/foam/otel/redaction.rb` (`mask_body_attribute`).
+- **Test**: `spec/payload_capture_spec.rb` — all three modes on the real
+  redacting wire path (`:off` ships zero middleware and zero attrs;
+  `:errors` attaches on exception AND 5xx and on the record_exception ivar
+  seam, NOT on 200/404; `:always` attaches on 200), env-clamp precedence
+  both directions + invalid-env fallback, the streaming-body proof (chunks
+  intact, close preserved, attributes landed), the rewind/seek/pos=
+  re-read dedupe, the
+  never-reads case, cap/true-size/truncation, binary/gzip sizes-only,
+  concurrent-request isolation, the foreign-provider and non-recording
+  no-ops, the hostile-input battery, the error-path capture, and the
+  JSON-body deep-redaction wire proof; `spec/conventions_spec.rb` (rule 21
+  as amended: `rack.input` touched ONLY by payload_capture.rb).
+
 ---
 
 ## General gotchas (applicable to Ruby)

data/README.md

@@ -231,8 +231,86 @@ end
 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** — a
-separate, future capability, not part of header capture.
+coverage today is Faraday. **Bodies/payloads are not captured by header
+capture** — bodies are the separate, opt-in `capture_payloads:` capability
+below.
+
+### Payload (body) capture — opt-in, `capture_payloads:`
+
+**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):
+
+```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
+)
+```
+
+- **`: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:
+
+```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
+```
+
+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.
 
 ---
 
@@ -253,6 +331,8 @@ separate, future capability, not part of header capture.
 | `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 to export it (mutating it in place is supported — `record.attributes` arrives unfrozen), or `nil` to drop it. A hook that raises (or returns anything else) drops **that record** loudly and the batch reports failure — fail-closed, never a raise into your threads. Runs BEFORE redaction, so the credential floor and your redact lists still apply to whatever the hook returns. Spans and logs only (metrics are aggregated state, not records). A non-callable raises at boot. Process-global: a second `init` never changes it. See "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). |
 
@@ -309,6 +389,24 @@ Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: EN
                 ignored_outbound_hosts: ["ingest.eval-tool.example"]) # the tenant loop guard — required
 ```
 
+```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])
+```
+
 ```ruby
 # Verbose self-reporting while wiring foam up (warnings are loud regardless):
 Foam::Otel.init(name: "checkout-api", environment: "development", enabled: true,
@@ -537,6 +635,54 @@ processor = Foam::Otel.create_ingest_span_processor(
 
 ---
 
+## The `before_send` hook
+
+`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.)
+
+The pipeline order is pinned:
+
+```
+BatchProcessor → before_send hooks → redaction (floor + your lists) → OTLP wire
+```
+
+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** → it continues to the next hook / to export.
+  Mutating it in place is supported — `record.attributes` arrives as an
+  unfrozen copy, so `record.attributes["k"] = v` and
+  `record.attributes.delete("k")` just work.
+* **return `nil`** → the record is dropped, silently (that is the filter
+  mechanism, not an error).
+* **raise, or return anything else** → that record is dropped **loudly**
+  (`[foam]` warning) 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.
+
+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.
@@ -926,6 +1072,7 @@ end
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | HONORED — the one operator-level override of the pinned fleet 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). |

data/lib/foam/otel/before_send.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "diagnostics"
+
+module Foam
+  module Otel
+    # The customer's `before_send:` hook(s) (1.8.0), run at the EXPORT
+    # BOUNDARY — after batching, immediately BEFORE foam's redaction pass and
+    # the OTLP serialization, so a record a hook drops is never serialized
+    # and never leaves the process. Why not a SpanProcessor: the same Ruby
+    # SDK constraint that forced redaction to the exporter boundary — a span
+    # freezes its attributes at finish BEFORE any on_finish processor runs
+    # (GOTCHAS F1), so a processor could neither mutate nor reliably drop.
+    # The mutable SpanData / LogRecordData Structs the batch processors hand
+    # the exporter are the first (and last) point where per-record transform
+    # + drop is possible before the wire.
+    #
+    # Composition order (pinned, pipelines.rb):
+    #   BatchProcessor -> BeforeSend::*Exporter -> Redacting*Exporter -> OTLP
+    # The hooks run FIRST so the credential floor, the value-pattern secret
+    # layer and the customer's key lists still apply to whatever a hook
+    # returns — before_send can never widen what ships past redaction (an
+    # attribute a hook ADDS is masked exactly like one an instrumentation
+    # set).
+    #
+    # Contract per record (Sentry beforeSend semantics — the spec's named
+    # fail-closed precedent, BASE_PACKAGE_SPEC D6):
+    #   * return the record (mutating it in place is fine) → next hook /
+    #     export;
+    #   * return nil → record DROPPED (the intentional filter mechanism —
+    #     success, not a failure);
+    #   * raise, or return a foreign object → record DROPPED, loudly, and
+    #     the batch reports FAILURE (fail-closed: a hook fault must never
+    #     ship a record the customer may have meant to scrub, and must never
+    #     raise into the export thread — rules 9/14/15). SystemStackError is
+    #     rescued explicitly (not a StandardError): a hook recursing on a
+    #     poisoned payload kills neither the batch thread nor the caller.
+    # The record reaches the first hook as a shallow dup with an UNFROZEN
+    # attributes copy (span attributes freeze at finish — GOTCHAS F1), so
+    # `record.attributes["k"] = v` just works; the dup also keeps the
+    # customer's mutations off the struct any other consumer might hold.
+    #
+    # Scope: spans and logs (the two record-shaped signals). Metric data is
+    # aggregated state, not records — deliberately NOT routed through
+    # before_send (documented in the README).
+    module BeforeSend
+      # Internal sentinel distinguishing a FAULTED drop (counts toward batch
+      # FAILURE) from an intentional nil drop. A hook can never return it
+      # legitimately — any non-record return is itself classified a fault.
+      ERROR = Object.new.freeze
+
+      module_function
+
+      # Run the hook pipeline over one record: each hook receives the
+      # previous hook's return. Returns the surviving record, nil for an
+      # intentional drop, or ERROR for a faulted one.
+      def run(hooks, record, signal)
+        current = thaw(record)
+        hooks.each do |hook|
+          result = hook.call(current)
+          return nil if result.nil?
+
+          unless result.is_a?(record.class)
+            Diagnostics.warn("before_send returned a #{result.class} for a #{signal} record — record " \
+                             "dropped (return the record, a replacement of the same type, or nil to drop; " \
+                             "fail-closed, rule 14)")
+            return ERROR
+          end
+          current = result
+        end
+        current
+      rescue StandardError, SystemStackError => e
+        Diagnostics.warn("before_send raised for a #{signal} record — record dropped, never exported " \
+                         "half-transformed (fail-closed, rule 14): #{e.class}: #{e.message}")
+        ERROR
+      end
+
+      # A shallow dup with an unfrozen attributes copy — the hook gets its
+      # own mutable record (span attributes arrive frozen; GOTCHAS F1).
+      def thaw(record)
+        copy = record.dup
+        if copy.respond_to?(:attributes) && copy.respond_to?(:attributes=)
+          attributes = copy.attributes
+          copy.attributes = attributes.nil? ? {} : attributes.dup
+        end
+        copy
+      end
+
+      # The span-side wrapper (composition over the redacting exporter, same
+      # wrap-never-subclass posture as redacting_exporter.rb: only the public
+      # export/force_flush/shutdown contract the batch processors call).
+      class SpanExporter
+        def initialize(inner, config)
+          @inner = inner
+          @hooks = config.before_send
+        end
+
+        def export(span_data, timeout: nil)
+          batch = span_data.to_a
+          faulted = 0
+          kept = batch.filter_map do |sd|
+            result = BeforeSend.run(@hooks, sd, :span)
+            if result.equal?(ERROR)
+              faulted += 1
+              nil
+            else
+              result
+            end
+          end
+          status = kept.empty? ? OpenTelemetry::SDK::Trace::Export::SUCCESS : @inner.export(kept, timeout: timeout)
+          faulted.positive? ? OpenTelemetry::SDK::Trace::Export::FAILURE : status
+        rescue StandardError, SystemStackError
+          # Fail closed past the per-record guards, loudly (rule 15) —
+          # never raise into the batch thread.
+          Diagnostics.warn("before_send pass raised past its guards — span batch dropped (fail-closed, rule 14/15)")
+          OpenTelemetry::SDK::Trace::Export::FAILURE
+        end
+
+        def force_flush(timeout: nil) = @inner.force_flush(timeout: timeout)
+        def shutdown(timeout: nil) = @inner.shutdown(timeout: timeout)
+      end
+
+      class LogRecordExporter
+        def initialize(inner, config)
+          @inner = inner
+          @hooks = config.before_send
+        end
+
+        def export(log_record_data, timeout: nil)
+          batch = log_record_data.to_a
+          faulted = 0
+          kept = batch.filter_map do |lrd|
+            result = BeforeSend.run(@hooks, lrd, :log)
+            if result.equal?(ERROR)
+              faulted += 1
+              nil
+            else
+              result
+            end
+          end
+          status = kept.empty? ? OpenTelemetry::SDK::Logs::Export::SUCCESS : @inner.export(kept, timeout: timeout)
+          faulted.positive? ? OpenTelemetry::SDK::Logs::Export::FAILURE : status
+        rescue StandardError, SystemStackError
+          Diagnostics.warn("before_send pass raised past its guards — log batch dropped (fail-closed, rule 14/15)")
+          OpenTelemetry::SDK::Logs::Export::FAILURE
+        end
+
+        def force_flush(timeout: nil) = @inner.force_flush(timeout: timeout)
+        def shutdown(timeout: nil) = @inner.shutdown(timeout: timeout)
+      end
+    end
+  end
+end

data/lib/foam/otel/config.rb

@@ -12,7 +12,8 @@ module Foam
     Config = Struct.new(
       :name, :environment, :version, :enabled,
       :redact_keys, :redact_pii_keys, :redact_detect, :ignored_outbound_hosts,
-      :diagnostics, :endpoint, :secret_heuristics,
+      :diagnostics, :endpoint, :secret_heuristics, :capture_payloads,
+      :before_send,
       keyword_init: true
     )
 
@@ -22,6 +23,14 @@ module Foam
     # opts into the PII detection tier. Anything else raises at boot.
     REDACT_OPTION_FIELDS = %w[secrets pii detect].freeze
 
+    # The exact modes the `capture_payloads:` init option accepts
+    # (payload-capture mandate 2026-07-28; equivalent strings — trimmed,
+    # case-insensitive — are accepted and canonicalized to these symbols).
+    # :off is the default: zero body teeing, zero per-request allocation, no
+    # middleware shipped. The FOAM_CAPTURE_PAYLOADS operator env clamp
+    # (init.rb) accepts the same spellings and overrides the option.
+    CAPTURE_PAYLOAD_MODES = %i[off errors always].freeze
+
     class << self
       # The inert config the helpers read before init() runs (everything a
       # no-op needs: empty redaction lists, export disabled).
@@ -32,7 +41,8 @@ module Foam
           redact_detect: [].freeze,
           ignored_outbound_hosts: [].freeze,
           diagnostics: false, endpoint: FOAM_OTEL_ENDPOINT,
-          secret_heuristics: true
+          secret_heuristics: true, capture_payloads: :off,
+          before_send: [].freeze
         ).freeze
       end
 
@@ -44,8 +54,13 @@ module Foam
 
       def resolve_config(name:, environment:, version:, enabled:,
                          redact_keys:, redact_pii_keys:, ignored_outbound_hosts:,
-                         diagnostics:, endpoint:, secret_heuristics: true, redact: nil)
+                         diagnostics:, endpoint:, secret_heuristics: true, redact: nil,
+                         capture_payloads: :off, before_send: nil)
         keys, pii, detect = merged_redact_lists(redact_keys, redact_pii_keys, redact)
+        # capture_payloads is validated LOUDLY at boot (rule 10, exactly like
+        # the redact: object): a value outside CAPTURE_PAYLOAD_MODES (or its
+        # string spellings) raises here — never a silent :off.
+        capture_mode = validate_capture_payloads!(capture_payloads)
         Config.new(
           name: name,
           environment: environment,
@@ -71,12 +86,71 @@ module Foam
           # module-constant machinery no config shape can narrow. Anything
           # but literal false means ON (default-on preserves the fleet's
           # no-leakage bar; disabling is an explicit, audited decision).
-          secret_heuristics: secret_heuristics == false ? false : true
+          secret_heuristics: secret_heuristics == false ? false : true,
+          # The payload-capture mode (2026-07-28 mandate): :off (the default
+          # — zero teeing, zero middleware) | :errors | :always, canonical
+          # symbol form. init.rb applies the FOAM_CAPTURE_PAYLOADS operator
+          # env clamp BEFORE this resolves.
+          capture_payloads: capture_mode,
+          # The customer's export hook(s) (1.8.0): one callable or an Array
+          # pipeline, validated LOUDLY at boot (rule 10 — a non-callable is a
+          # programming error). Stored as a frozen Array; empty (the default)
+          # means the exporter chain gains no before_send stage at all.
+          before_send: validate_before_send!(before_send)
         ).freeze
       end
 
       private
 
+      # ---- the before_send option (1.8.0) ------------------------------------
+      # Loud at boot (rule 10, same posture as capture_payloads and the
+      # redact: object): before_send must be one callable (responds to
+      # #call — a lambda, a Proc, a Method, or any hook object) or an Array
+      # of callables run as a pipeline. Anything else — including a nil or
+      # non-callable INSIDE the array — raises here, never a silent no-op
+      # that leaves the customer believing their filter runs.
+      def validate_before_send!(value, context: "Foam::Otel.init")
+        hooks = if value.nil?
+                  []
+                else
+                  value.is_a?(Array) ? value : [value]
+                end
+        hooks.each_with_index do |hook, index|
+          next if hook.respond_to?(:call)
+
+          raise ArgumentError, "#{context} before_send: must be a callable (responds to #call) or an " \
+                               "Array of callables, got #{hook.class} at position #{index}"
+        end
+        hooks.freeze
+      end
+
+      # ---- the capture_payloads option (payload-capture mandate 2026-07-28)
+      # Canonicalize a mode value: the three symbols, or their string
+      # spellings trimmed + case-insensitive, map to the canonical symbol;
+      # anything else is nil (the callers decide raise-vs-fallback).
+      def normalize_capture_payloads(value)
+        return value if CAPTURE_PAYLOAD_MODES.include?(value)
+        return nil unless value.is_a?(String) || value.is_a?(Symbol)
+
+        mode = value.to_s.strip.downcase.to_sym
+        CAPTURE_PAYLOAD_MODES.include?(mode) ? mode : nil
+      rescue StandardError
+        nil
+      end
+
+      # The loud-at-boot door (rule 10): an invalid INIT value is a
+      # programming error the engineer must catch on their machine.
+      # (The env clamp's invalid values warn + fall back instead — init.rb.)
+      def validate_capture_payloads!(value, context: "Foam::Otel.init")
+        mode = normalize_capture_payloads(value)
+        if mode.nil?
+          raise ArgumentError, "#{context} capture_payloads: must be one of " \
+                               "#{CAPTURE_PAYLOAD_MODES.map(&:inspect).join(', ')} " \
+                               "(equivalent strings accepted), got #{value.inspect}"
+        end
+        mode
+      end
+
       def downcase_list(list)
         Array(list).map { |k| k.to_s.downcase }.reject(&:empty?).uniq.freeze
       end
@@ -162,7 +236,16 @@ module Foam
           ignored_outbound_hosts: existing.ignored_outbound_hosts,
           diagnostics: diagnostics ? true : false,
           endpoint: existing.endpoint,
-          secret_heuristics: secret_heuristics == false ? false : true
+          secret_heuristics: secret_heuristics == false ? false : true,
+          # Like enabled/endpoint, capture_payloads is process-global after
+          # the first init: middleware insertion already happened (or
+          # deliberately did not — an :off boot shipped none), so a second
+          # init cannot meaningfully flip it. Carried forward unchanged.
+          capture_payloads: existing.capture_payloads,
+          # before_send is process-global too: the exporter chain was built
+          # (with or without its before_send stage) at the first init and a
+          # second init never rebuilds pipelines. Carried forward unchanged.
+          before_send: existing.before_send
         ).freeze
       end
     end

data/lib/foam/otel/errors.rb

@@ -41,6 +41,18 @@ module Foam
         # exception" into a host-thread crash (rule 9).
         false
       end
+
+      # Read-only view of the registry above (the payload-capture :errors
+      # mode's thin seam, mandate 2026-07-28): true when at least one
+      # exception was recorded on this span via record_once. Reads the SAME
+      # span-carried ivar — never a second registry, never duplicated dedupe
+      # logic. Never raises (rule 9).
+      def recorded?(span)
+        seen = span.instance_variable_get(IVAR)
+        seen.is_a?(Array) && !seen.empty?
+      rescue StandardError
+        false
+      end
     end
   end
 end