foam-otel 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8650474eaaa3dec06f5500839b073d5c2b211750da4ad2a068459cbbb5feb3f1
-  data.tar.gz: 6c7b40fe1a9297f0c81547222f4ea7a36c716a9bc1eb6a2f97c5e44d49f6b9eb
+  metadata.gz: bb0ea8b43b76506cdd72000ba735c36e0bd903b26d83347779cca5fc309b716b
+  data.tar.gz: 1a35c9ee39299519c146efb826aa9c02598df6ca23e018b0d8c8e62932a9e234
 SHA512:
-  metadata.gz: 39fd5531d0478acdff0ae4e36ae901ee3975a2b2c55e84319bba959683ac3fa69dd226639f2c1c7f4682eec9d064843071209f7ed56bf149d30591cecc732ba8
-  data.tar.gz: b32886c34c0b60fd1f7751a7cb7e1a81152804c7c495078217ef7e63a83025b15b5336acffad32ebc23e730c42120aa8e32519cd3a9d1154f049130b75ad8160
+  metadata.gz: e689868d02fc414fa6d05eddbc2cb73dd9b5b13b4819a68c669c1fb183bfdea8086e75bd2468661b44e2677f381369d6c3a815e5a0135e7ed9c22a8c86a7bb95
+  data.tar.gz: fc80c105460917ad1c126604cf6c092c61d7a8c4263ce00d9296a16911f9b25412ee0d5f132619307ebb8862ff4af03c28794935f4758a3a19ad7b5894f4bbd0

data/GOTCHAS.md

@@ -0,0 +1,225 @@
+# GOTCHAS — foam-otel (Ruby)
+
+Language traps that silently break telemetry or the host app, and the
+non-obvious decisions this package made about them (BASE_PACKAGE_SPEC rule 37).
+Every entry carries: the Trap, the SOURCES (links / installed-source refs), the
+Decision & why, the Mitigation, and the NAME OF THE TEST that proves it. CI runs
+those tests.
+
+Installed-source refs are rooted at the lockfile-pinned gems (opentelemetry-sdk
+1.13.0, -logs-sdk 0.6.1, -metrics-sdk 0.15.0, -api 1.11.0, -exporter-otlp 0.34.1,
+-instrumentation-rack 0.31.1, -instrumentation-rails 0.42.0).
+
+---
+
+## R1: Puma/Unicorn preload fork — exporter threads do not survive fork (CRITICAL)
+
+- **Trap**: In cluster-mode servers the SDK boots in the master and `fork`s
+  workers. Background exporter/reader threads are not copied into the children;
+  the parent exports while workers are dark (or a child inherits a mutex held at
+  fork and deadlocks). The default production topology fails while a non-forking
+  test app shows green.
+- **Sources**:
+  - Upstream: "BatchSpanProcessor should not spawn a thread during boot" —
+    https://github.com/open-telemetry/opentelemetry-ruby/issues/462
+  - Upstream: SDK fork safety — https://github.com/open-telemetry/opentelemetry-ruby/issues/7
+  - Installed source — traces/logs SELF-HEAL: `BatchSpanProcessor#reset_on_fork`
+    (opentelemetry-sdk `trace/export/batch_span_processor.rb:174-184`, invoked
+    from `on_finish`); `BatchLogRecordProcessor#reset_on_fork`
+    (opentelemetry-logs-sdk `logs/export/batch_log_record_processor.rb:174-182`).
+  - Installed source — metrics DO NOT self-heal: `PeriodicMetricReader` starts
+    its thread in `initialize` and only restarts via `after_fork`
+    (opentelemetry-metrics-sdk `metrics/export/periodic_metric_reader.rb:40,82-87`);
+    the `ForkHooks` that drive it are attached ONLY inside `SDK.configure`
+    (`metrics/configurator_patch.rb:57`), which foam bypasses.
+- **Decision & why**: The trace/log batch processors self-heal on their first
+  span/log in the child — foam relies on upstream and never reimplements it. The
+  PeriodicMetricReader does not, and foam bypasses `SDK.configure`, so foam
+  installs its OWN `Process._fork` hook to restart foam's readers in the child.
+- **Mitigation**: `lib/foam/otel/fork_hooks.rb` prepends `Process._fork` and
+  calls `Foam::Otel.after_fork!` in the child (restarts tracked metric readers,
+  `lib/foam/otel/api.rb`). Also exposed for `Puma on_worker_boot` /
+  `Unicorn after_fork`. The README's cluster-mode recipe calls `init` per worker
+  so each worker also mints a fresh `service.instance.id`.
+- **Test**: `spec/fork_spec.rb` — "a real fork does not crash and the child can
+  flush", "restarts every tracked metric reader and never raises".
+
+## R2: Signal maturity is uneven — logs & metrics SDKs are pre-1.0
+
+- **Trap**: Ruby OTel is stable for traces only; the metrics SDK is alpha and the
+  logs SDK is "development". APIs and defaults can change under a patch bump.
+- **Sources**: OTel Ruby signal status (Traces stable, Metrics/Logs development)
+  — https://opentelemetry.io/docs/languages/ruby/ ; the metrics-sdk README states
+  "alpha … things may break and APIs may change". Installed versions:
+  logs-sdk 0.6.1, metrics-sdk 0.15.0.
+- **Decision & why**: Pin with pessimistic constraints (`~> 0.6`, `~> 0.15`) and
+  wrap both signals behind stable foam helpers (`log`, the four metric helpers)
+  so app code never touches the churning API directly.
+- **Mitigation**: gemspec pins + the helper wrappers (`lib/foam/otel/api.rb`,
+  `lib/foam/otel/metrics.rb`); the lockfile freezes exact versions.
+- **Test**: `spec/version_spec.rb` — pins the supported SDK lines and proves the
+  helpers work over the pinned pre-1.0 SDKs.
+
+## R3: Contrib instrumentations can themselves raise
+
+- **Trap**: Auto-instrumentation patches third-party libraries; a patched method
+  or an install block can raise. The "never-throw" convention is not enforced.
+- **Sources**: Registry rescues each install (`StandardError` only) —
+  opentelemetry-registry `instrumentation/registry.rb:62-91`; `Base#install`
+  itself does not rescue (`instrumentation-base base.rb:218-227`), so a
+  non-StandardError escapes. Runtime-raise discussion:
+  https://github.com/open-telemetry/opentelemetry-ruby-contrib/discussions/241
+- **Decision & why**: foam's never-throw wraps FOAM's helpers, not tier-2
+  internals. foam installs contrib gems through the official registry (inheriting
+  its per-instrumentation rescue) and adds its own guard around activation; a
+  contrib patch that raises at request time is the contrib's responsibility and
+  is not swallowed (an app-visible request error must not be hidden).
+- **Mitigation**: `lib/foam/otel/init.rb` (`activate_instrumentations` rescues;
+  each `require` guards `LoadError`; `install_additional` is fault-isolated per
+  instance). Tenant/`additional_*` instances are wrapped by
+  `GuardedSpanProcessor` / `GuardedLogRecordProcessor` (`lib/foam/otel/pipelines.rb`).
+- **Test**: `spec/tenant_seam_spec.rb` — "fault-isolates a throwing
+  additional_instrumentations instance", "skips a THROWING additional span
+  processor without breaking the app or foam".
+
+## R4: Rails initializer / Zeitwerk / middleware ordering
+
+- **Trap**: `init` racing Zeitwerk autoload, and the official rack middleware not
+  being inserted, silently misorder or omit hooks. A known contrib bug: the
+  action_pack railtie installs `-rack` with an EMPTY config, overriding rack
+  options.
+- **Sources**: contrib #88 (action_pack overrides rack config) —
+  https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues/88 ;
+  action_pack railtie inserts the rack middleware
+  (`opentelemetry-instrumentation-action_pack .../railtie.rb`).
+- **Decision & why**: foam ships NO middleware — the official
+  `-rack`/`-action_pack` own the inbound span and the middleware insertion. foam
+  is insulated from contrib #88 because its redaction is at the EXPORTER boundary,
+  not rack config (so an overridden rack config cannot defeat masking). The
+  integration calls `init` before `Rails.application.initialize!` so
+  `install_all` registers the instrumentation before the middleware stack
+  finalizes.
+- **Mitigation**: the README recipe places `init` before `initialize!`; the
+  conformance app demonstrates it.
+- **Test**: `test-apps/ruby-rails` conformance gate (`--dialect official`) — a
+  real Rails app boots with foam and the official rack span carries the inbound
+  telemetry (`/ok`, `/fail`, `/reject` assertions).
+
+---
+
+## F1: Span attributes freeze at finish — the redaction floor cannot be a processor
+
+- **Trap**: The obvious place to mask attributes is a SpanProcessor, but the Ruby
+  SDK freezes a span's attributes at `finish` BEFORE any `on_finish` processor
+  runs — so a processor cannot mutate them, and neither can a tenant processor
+  see a masked view.
+- **Sources**: installed source — `Span#finish` does
+  `@attributes = validated_attributes(@attributes).freeze` then sets `@ended`
+  (opentelemetry-sdk `trace/span.rb:277,280`); `to_span_data` returns the frozen
+  `@attributes` by reference (`trace/span.rb:296-307`).
+- **Decision & why**: foam runs the always-on floor (rule 14) at the EXPORTER
+  boundary — a `RedactingSpanExporter`/`RedactingLogRecordExporter` that rebuilds
+  the mutable `SpanData`/`LogRecordData` Structs with masked attributes/events/
+  body before serialization. This guarantees no raw secret leaves the process in
+  foam's own export.
+- **Divergence (TODO pcga11)**: because attributes freeze at finish, a tenant
+  `additional_span_processor` receives span attributes UNMASKED. Masking is
+  EXPORT-only in Ruby, so the rule-18 C "tenant sees already-masked" guarantee
+  holds ONLY for values the caller pre-masks with `redact()` — NOT for
+  third-party instrumentation attributes AND NOT for values passed to
+  `set_attribute`/`set_attributes`. Foam's own export is always masked. Recorded
+  honestly, not papered over; surfaced to pcga11 as spec-gap material (Ruby
+  offers no safe pre-freeze hook — the `on_finishing` hook runs inside the span
+  mutex, so a processor calling `set_attribute` there would deadlock).
+- **Mitigation**: `lib/foam/otel/redacting_exporter.rb` + `lib/foam/otel/redaction.rb`.
+- **Test**: `spec/redacting_exporter_spec.rb` (masking on the wire),
+  `spec/redaction_spec.rb` (the floor, tested exhaustively).
+
+## F2: OTEL_SDK_DISABLED and OTEL_PROPAGATORS are only honored by SDK.configure
+
+- **Trap**: Operators expect `OTEL_SDK_DISABLED=true` and `OTEL_PROPAGATORS=none`
+  to work. The Ruby SDK reads them ONLY inside `SDK.configure`, which foam
+  bypasses — so foam would silently ignore both.
+- **Sources**: `OTEL_SDK_DISABLED` checked only in `SDK.configure`
+  (opentelemetry-sdk `sdk.rb:63-67`, exact string `'true'`); `OTEL_PROPAGATORS`
+  read only by `Configurator#configure_propagation`
+  (`sdk/configurator.rb:209-225`, `none` → NoopTextMapPropagator). Spec:
+  https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+- **Decision & why**: foam implements both itself. `OTEL_SDK_DISABLED=true`
+  (exact string) supersedes `enabled: true` and goes fully inert.
+  `OTEL_PROPAGATORS=none` installs a no-op propagator (injection off, telemetry
+  keeps flowing); any other value warns-and-ignores (foam's propagator set is
+  fixed).
+- **Mitigation**: `lib/foam/otel/init.rb` (`killed = ENV["OTEL_SDK_DISABLED"] == "true"`,
+  `configure_propagation`).
+- **Test**: `spec/init_spec.rb` (OTEL_SDK_DISABLED precedence + exact-string),
+  `spec/env_vars_spec.rb` (OTEL_PROPAGATORS none / default / ignored).
+
+---
+
+## F3: Last-write-wins globals — foam cannot defend a slot claimed AFTER init
+
+- **Trap**: Ruby's OTel global setters are last-write-wins — a foreign SDK that
+  calls `OpenTelemetry.tracer_provider = …` AFTER foam's init silently
+  overwrites foam's provider, and foam's helpers then emit through the foreign
+  provider instead of to foam, with no error.
+- **Sources**: the setter assigns unconditionally —
+  `opentelemetry-api opentelemetry.rb:52-60` (`@tracer_provider = provider` runs
+  regardless of the current occupant); same shape for meter/logger.
+- **Decision & why**: there is no setter callback to intercept the displacement,
+  so foam re-checks LAZILY: whenever a passthrough/helper reads the live provider
+  (`get_tracer`/`get_meter`/`get_logger`, and the metric cache rebind), if the
+  slot no longer holds the provider foam registered, foam warns ONCE per signal
+  (rule 11 / 18 step 5). Foam cannot *defend* the slot — this is a genuine Ruby
+  divergence from the spec's "foam-first → not displaced" test-case (surfaced to
+  pcga11). The durable answer is load-order discipline: init per worker, and load
+  foam last.
+- **Mitigation**: `Foam::Otel.warn_if_displaced` (`lib/foam/otel/init.rb`), called
+  from the passthroughs (`lib/foam/otel/api.rb`) and the metric path
+  (`lib/foam/otel/metrics.rb`).
+- **Test**: `spec/coexistence_spec.rb` — "warns ONCE when a foreign SDK displaces
+  a slot after init".
+
+## General gotchas (applicable to Ruby)
+
+- **G1 — init after target import / pre-init no-op**: the API's proxy providers
+  make every helper a silent no-op before `init`, and instruments rebind on the
+  provider swap; `init` installs instrumentation before app code runs.
+  *Test*: `spec/public_api_spec.rb` ("before init — silent no-ops").
+- **G2 — process ends before flush**: batch processors buffer; `flush` is public
+  and the README wires it at handler end / worker exit.
+  *Test*: `spec/fork_spec.rb` (child flush).
+- **G4 — exporter self-tracing loop**: the OTLP exporter sends inside an
+  `OpenTelemetry::Common::Utilities.untraced` context the official
+  instrumentation respects (opentelemetry-exporter-otlp `exporter.rb:147`), so
+  export never traces itself; `ignored_outbound_hosts` + the endpoint host also
+  feed the http-client instrumentations' `untraced_hosts`
+  (`lib/foam/otel/init.rb` `configure_loop_guard`).
+  *Test*: `test-apps/ruby-rails` gate (no feedback spans appear).
+- **G5 — context across async boundaries**: `Context.current` is fiber-local; a
+  raw `Thread.new` loses the span. foam relies on the official
+  `-concurrent_ruby` and `-active_job` instrumentations (bundled via `-rails`) to
+  carry context across Rails' pools and jobs; a hand-rolled thread is the FDE's
+  to wrap. *Documented*; conformance covers the rack-context path.
+- **G7 — metric cardinality explosion**: the metric helpers forward
+  caller-supplied `attributes` verbatim; an unbounded attribute value (user id,
+  raw path) explodes the series count. The README carries the warning with the
+  classic bad example. *Test*: `spec/metrics_spec.rb` (attribute passthrough).
+- **G9 — a second SDK / injected agent**: the classifier detects a foreign
+  provider per signal and warns by name; foam registers only into free slots.
+  *Test*: `spec/coexistence_spec.rb` (8-permutation matrix), `spec/classifier_spec.rb`.
+- **G12 — two copies of the OTel API**: two gem copies → two global registries →
+  silent no-op or doubled telemetry. Cannot be seen at build time; the README
+  troubleshooting entry says to check `bundle list | grep opentelemetry-api` for
+  one copy first. *Documented* (README).
+
+---
+
+## Signatures
+
+A human review appends a row here (name, date, package version). A missing or
+stale signature blocks review (rule 37).
+
+| Reviewer | Date | Package version | Notes |
+| --- | --- | --- | --- |
+| @telaviv | 2026-07-24 | 1.0.0 | initial BASE_PACKAGE_SPEC pass — reviewed |

data/LICENSE

@@ -0,0 +1,24 @@
+Foam Proprietary License
+
+Copyright (c) 2026 Foam AI, Inc. All rights reserved.
+
+This software is licensed, not sold. Use is permitted only by Foam
+and by customers with an active Foam agreement, solely to instrument
+their own services for the Foam platform. No other person or entity
+may use, copy, modify, redistribute, or sublicense this software.
+This license terminates automatically when the agreement ends.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL FOAM BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR ITS USE, EXCEPT AS EXPRESSLY PROVIDED IN THE
+APPLICABLE FOAM AGREEMENT.
+
+If you have a separate written agreement with Foam covering this
+software, that agreement governs over this file.
+
+Third-party open-source components this software depends on are
+listed in THIRD-PARTY-NOTICES and remain under their own licenses;
+nothing in this file restricts the rights those licenses grant.

data/README.md

@@ -1,76 +1,278 @@
-# foam-otel
+# foam-otel (Ruby)
 
-The shared foam OpenTelemetry core for Ruby services — traces, logs, and
-metrics over OTLP HTTP, implementing the fleet wire contract
-([`contract/SPEC.md`](../../contract/SPEC.md)). Verified end-to-end by the
-`test-apps/ruby-rails` conformance gate on every PR.
+Foam's OpenTelemetry core for Ruby services. A thin, safe wrapper over the
+official OpenTelemetry libraries: foam owns the pipeline (providers, batch
+processors, OTLP export to the foam fleet endpoint, an always-on redaction
+floor), turns on automatic tier-1/2 instrumentation, and hands you a small set
+of never-throw helpers — and nothing else.
+
+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`.
+
+---
+
+## Install
 
 ```ruby
 # Gemfile
 gem "foam-otel"
+# Bundle the official instrumentation for whatever your app uses; foam
+# auto-activates each when present (presence-checked). Rails + Rack come with
+# foam-otel; add others as needed:
+gem "opentelemetry-instrumentation-pg"       # e.g. Postgres
+gem "opentelemetry-instrumentation-redis"    # e.g. Redis
+gem "opentelemetry-instrumentation-sidekiq"  # e.g. Sidekiq
+```
+
+**Supported versions** (tested in CI, `spec/version_spec.rb`): Ruby **>= 3.1**;
+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).
+
+---
+
+## Quick start — scenario 1: a clean service (the common case)
+
+Put `init` FIRST, before your app boots. In Rails, that means an initializer
+(and, for cluster mode, per worker — see "Puma / Unicorn" below).
+
+```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_TOKEN"),             # required WHEN enabled — wire it explicitly
+  version: ENV["GIT_SHA"]                      # → service.version (recommended; optional)
+)
+```
+
+**Outcome**: foam registers the tracer/meter/logger providers, exports OTLP to
+the foam fleet endpoint, and auto-activates the official rack/rails
+instrumentation (and any other bundled `opentelemetry-instrumentation-*`). Every
+inbound request, DB call, HTTP call, and job the official instrumentations cover
+now flows to foam, with the redaction floor applied on the wire.
+
+---
+
+## The `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. Blank while enabled → raises at boot. |
+| `version:` | String | no | nil | `service.version`, verbatim (git SHA recommended). Missing → warns and continues. Never detected at runtime. |
+| `redact_keys:` | Array<String> | no | `[]` | Extra field names treated as SECRETS (tail-masked). EXTENDS the always-on floor. |
+| `redact_pii_keys:` | Array<String> | no | `[]` | Field names treated as PII (full `[REDACTED]`, no tail). Foam ships no PII preset — this is your enumeration. |
+| `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. |
+| `diagnostics:` | Boolean | no | false | Verbose `[foam]` self-reporting of init/health. Warnings and errors are always loud regardless. |
+
+**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 helpers
+
+All helpers never raise, and no-op silently before `init` and when disabled.
 
-# config/initializers/foam.rb (or before Rails loads)
-Foam::Otel.init(service_name: "my-service")
+**Lifecycle**
+
+```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)
 ```
 
-That's the whole integration. Everything else self-wires by presence
-detection (zero customer effort):
-
-- **Rails**: railtie inserts the Rack middleware at position 0, captures
-  controller exceptions that `rescue_from` swallows (via
-  `process_action.action_controller`), and broadcasts `Rails.logger` lines to
-  foam as `log.rails` records — the app's own logger chain is never touched.
-- **Sidekiq**: server middleware auto-registers; one `sidekiq.consume <queue>`
-  consumer span per job, failures re-raised identically (retries untouched).
-- **Datadog** (SPEC §7.3): foam spans and logs carry `dd.trace_id`/`dd.span_id`
-  verbatim from the DD correlation API when a DD trace is active. Foam never
-  patches, parents from, or reconfigures the DD tracer.
-- **Rollbar** (SPEC §12): exceptions the app reports to Rollbar (e.g. inside
-  `rescue_from` handlers) are also recorded on the active foam span — Rollbar
-  itself is untouched, and each exception records at most once per span.
-
-| option | default | |
-|---|---|---|
-| `service_name:` | (required) | resource `service.name` |
-| `token:` | `FOAM_OTEL_TOKEN` env | missing → warn + inert |
-| `endpoint:` | `OTEL_EXPORTER_OTLP_ENDPOINT` env → `https://otel.api.foam.ai` | |
-| `force_export:` | `false` | export outside production |
-| `redact_contact_info:` | `false` | append email/phone/telefono/celular to redaction |
-| `redact_keys:` | `[]` | extra redacted keys |
-| `health_routes:` | `[]` | routes exempted from request-context capture (none by default — health checks are captured) |
-| `sidekiq:` / `rollbar:` / `rails:` | `true` | opt out of auto-wiring that adapter |
-
-Export is production-gated (`RAILS_ENV`/`RACK_ENV`/`ENVIRONMENT`/`ENV`/
-`NODE_ENV` ∈ {production, prod}) unless `force_export`. Batch cadence comes
-from the standard OTel env vars (`OTEL_BSP_SCHEDULE_DELAY`,
-`OTEL_BLRP_SCHEDULE_DELAY`, `OTEL_METRIC_EXPORT_INTERVAL`).
-
-**Route names**: span names and `http.route` use Rails' route template
-(`action_dispatch.route_uri_pattern`, e.g. `/users/:id`) when available. On
-older Rails or bare Rack where it isn't populated, the raw path is used —
-which raises span-name cardinality for routes with dynamic segments; prefer
-Rails 7.1+ for automatic low-cardinality route names.
-
-**Forked servers** (Puma workers, Sidekiq): span/log pipelines self-heal
-after fork; the metrics reader is re-armed automatically by the first
-request/job in the child via a pid check. Belt-and-braces:
-`on_worker_boot { Foam::Otel.after_fork! }`.
-
-Custom telemetry passthrough (stamped `app.custom` automatically). Create
-each instrument ONCE and reuse it — creating an instrument per call
-re-registers it under a mutex and logs a duplicate-registration warning:
+**Traces**
 
 ```ruby
-Foam::Otel.tracer.in_span("work") { |span| ... }
+result = Foam::Otel.span("nightly-sync") do |span|
+  # ... work ...  the span always ends; a raised error is recorded + re-raised
+end
+
+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
+```
 
-JOBS_DONE = Foam::Otel.meter.create_counter("jobs_done")   # once, at load
-JOBS_DONE.add(1)                                            # per event
+**Metrics** (one helper per synchronous instrument; names pass through verbatim)
 
-Foam::Otel.logger.on_emit(severity_number: 9, body: "hi", context: OpenTelemetry::Context.current)
-Foam::Otel.record_exception(error)   # foam span only; never notifies a tracker
+```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)
 ```
 
-```sh
-bundle exec rspec           # unit suite
-bash ../../test-apps/ruby-rails/run-verify.sh   # full conformance gate
+> ⚠️ 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.
+
+**Logs**
+
+```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.
 ```
+
+**Redaction**
+
+```ruby
+Foam::Otel.redact(user_supplied_token)  # tail-masks a scalar you know is sensitive; [REDACTED] for structures
+```
+
+**Passthroughs** (the real OTel objects on foam's pipeline — links, span kinds,
+observable instruments, baggage all reachable here)
+
+```ruby
+Foam::Otel.get_tracer("my.lib")
+Foam::Otel.get_meter("my.lib")
+Foam::Otel.get_logger("my.lib")
+```
+
+---
+
+## Coexistence — foam arriving in a monitored service
+
+`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.
+
+### Scenario 2 — beside a proprietary APM agent (e.g. Datadog)
+
+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.
+
+```ruby
+Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FOAM_TOKEN,
+                ignored_outbound_hosts: ["trace.agent.datadoghq.com"])
+```
+
+### Scenario 3 — a scoped tenant rides foam's pipeline (LLM-eval, AI-observability)
+
+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).
+
+```ruby
+Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FOAM_TOKEN,
+                additional_span_processors: [EvalTool::SpanProcessor.new(project: "prod")],
+                ignored_outbound_hosts: ["ingest.eval-tool.example"])
+```
+
+> Ruby note: because the Ruby SDK freezes span attributes at finish, a tenant
+> processor sees third-party instrumentation attributes UNMASKED (foam's floor
+> runs at the exporter boundary). Foam's own export is always masked.
+
+### Scenario 4 — a foreign OTel SDK already owns a signal
+
+If another OTel SDK registered (say) the tracer before foam, foam does NOT
+displace it. It warns once, naming the owner, and is DARK for that signal — your
+tier-3 telemetry for it flows through that SDK, not to foam. Foam ingest for a
+claimed signal is not yet available; feed foam server-side from that pipeline, or
+file the need.
+
+### 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:
+
+```ruby
+Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FOAM_TOKEN)
+# → warns: traces foreign-owned (foam dark for traces); metrics + logs → foam, full contract.
+```
+
+### Scenario 6 — tests / CI (fully inert, no token needed)
+
+```ruby
+Foam::Otel.init(name: "checkout-api", environment: "test", enabled: false)
+```
+
+### Scenario 7 — serverless / short-lived (flush at the end)
+
+```ruby
+Foam::Otel.init(name: "orders-fn", environment: "production", enabled: true, token: FOAM_TOKEN)
+
+def handler(event:, context:)
+  run(event)
+ensure
+  Foam::Otel.flush   # the platform freezes the process before the batch timer fires
+end
+```
+
+### Puma / Unicorn (cluster mode) — CRITICAL
+
+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`:
+
+```ruby
+# config/puma.rb
+on_worker_boot do
+  Foam::Otel.init(name: "checkout-api", environment: ENV["APP_ENV"], enabled: true, token: ENV["FOAM_TOKEN"])
+  # or, if you init in an initializer: Foam::Otel.after_fork!
+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; foam dark for that signal |
+| `init` called twice | `[foam]` warning; returns the first instance (providers are process-global) |
+
+---
+
+## Environment variables
+
+| Var | Posture |
+| --- | --- |
+| `OTEL_SDK_DISABLED=true` | HONORED — full kill switch, supersedes `enabled: true` (exact string `true`). |
+| `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. |
+| `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. |
+| every other `OTEL_*` | INERT — `OTEL_SERVICE_NAME` / `OTEL_RESOURCE_ATTRIBUTES` never override the init-declared identity; sampler/exporter 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.
+- **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).