foam-otel 1.9.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2e506ae900650923638df263e5775efa20dd8ab7a63540eefb9d5156c1d008c
-  data.tar.gz: 64ea4091c85c9541ec1f08dd5560608e560ec80e8ee6918f95098b976b0ec82e
+  metadata.gz: 767e21dce7e53eb8a74e430c736f2ba94e22c882022733fff7fb8edb058c118e
+  data.tar.gz: 4d9e7b6789d79daec4eb0482a22ac68520263c0a267e1b4e4def7eae97d9e642
 SHA512:
-  metadata.gz: 4c776696c10dc442394e5b023db7b47d178ec4b328addd693ba72b60e726c19f923533f0f1645e7b62ec322e63d6fcd0b39b1ca917cd9aa66403295c0b67e266
-  data.tar.gz: 615ec0ee4400e6e11baa6a6572fcafdccdeb6764f9bb2e65afcf4ff72a8185e9ba45086cd5e8e039934ea1043fe165d94784983539ac0d3e361a6b28f72a986e
+  metadata.gz: 4512202149fa0ee2b50093b7485b07373a09ed29315b6489d3e59d0c111ecf3d023e77e49f9af271ca97df33210e2028ba3376e4a43516284bd6f0fe195a8627
+  data.tar.gz: 9d15c2c183dfdac3ca20f0a3eccae5c6f2e45134206a697604a1b70e7a9046c775d0b5e805662a162aee2b0d89e62f810cdea8e43a72b9f15db783f1b07ccb0d

data/README.md

@@ -2,7 +2,7 @@
 
 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), turns on automatic
+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
@@ -42,7 +42,8 @@ gem "opentelemetry-instrumentation-graphql"  # e.g. GraphQL
 gem "opentelemetry-instrumentation-resque"   # e.g. Resque
 ```
 
-**Supported versions** (tested in CI, `spec/version_spec.rb`): Ruby **>= 3.1**;
+**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
@@ -69,7 +70,7 @@ Foam::Otel.init(
 ```
 
 **Outcome**: foam registers the tracer/meter/logger providers, exports OTLP to
-the foam fleet endpoint, and auto-activates the **universal floor** — the
+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
@@ -111,7 +112,7 @@ 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, fleet-identical with the
+`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
@@ -148,8 +149,8 @@ listed request and response headers as
 > **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 (ruling
-> 2026-07-28). A custom header outside the list is **not captured** unless
+> 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` /
@@ -321,7 +322,7 @@ not captured — inbound only.
 | `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. **Fleet convention: read it from the `FOAM_OTEL_TOKEN` env var.** Blank while enabled → raises at boot. |
+| `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). |
@@ -432,8 +433,7 @@ override is the operator-level `OTEL_EXPORTER_OTLP_ENDPOINT` env var (below).
 
 ## The default credential denylist (the always-on floor)
 
-**Fleet ruling 2026-07-26** (binding design:
-`docs/decisions/credential-denylist-design.md`; frozen fixture:
+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.
@@ -482,13 +482,13 @@ 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 — the fleet ruling carves out exactly this list (and only
-this list) as non-negotiable. The list is byte-identical in every foam core
-and gate-checked in CI against the fleet fixture
+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`).
 
-**Fleet param-name canon** (the customer options above the floor, identical
-concept in every core — the floor itself has NO init surface anywhere):
+**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 |
 |---|---|---|---|---|---|
@@ -517,8 +517,7 @@ 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 (fleet ruling 2026-07-27,
-`docs/decisions/security-fixes-design.md`):
+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,
@@ -561,8 +560,8 @@ 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 the foam cores,
-changed only by fleet ruling.
+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
@@ -589,9 +588,9 @@ 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: [...] }` (fleet ruling
-2026-07-28; frozen fixture: `contract/pii-detect.json` — the entity names and
-placeholders are byte-identical in every foam core and gate-checked in CI by
+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.
 
@@ -696,7 +695,7 @@ at-exit flush. Anything a hook needs from the request/job thread
 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 (rule 10): a non-callable — or a **lambda/Method
+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
@@ -963,7 +962,7 @@ 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.
-Fleet canon mapping (pinned by `spec/export_surface_spec.rb`):
+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`.
@@ -1098,8 +1097,8 @@ end
 
 | Var | Posture |
 | --- | --- |
-| `OTEL_SDK_DISABLED=true` | HONORED — full kill switch, supersedes `enabled: true` (matched trimmed + case-insensitive, so `TRUE` / ` true ` also kill — the fleet's one emergency switch behaves the same across languages). 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 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_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. |

data/lib/foam/otel/version.rb

@@ -186,6 +186,14 @@ module Foam
     #   ORIGINAL resource/scope are force-restored onto every survivor
     #   after the pipeline (identity is not hook-writable — the Go port's
     #   contract; README updated).
-    VERSION = "1.9.1"
+    # 2.0.0: RUNTIME FLOOR RAISE (label-follows-tested-matrix ruling
+    #   2026-07-29). required_ruby_version >= 3.1 -> >= 3.4 — the version the
+    #   CI matrix actually runs. The 3.1 floor was an unproven published
+    #   promise: no CI leg ran below 3.4, and on 3.1–3.2 (both EOL) Bundler
+    #   resolves an OLDER upstream otel gem set than the proven lockfile —
+    #   a combination never tested. MAJOR: narrowing the supported-runtime
+    #   label is breaking for installs on the dropped versions. No wire/API
+    #   change — every 1.x contract above still holds.
+    VERSION = "2.0.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foam-otel
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Foam
@@ -422,7 +422,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="