foam-otel 1.9.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d27bb6b38712364503503fecd37ea383f9a7e3fb3648da8ef41524c575ef9302
-  data.tar.gz: 0c9fee962999043120904c8ffe85621e32ae04fcb300280ec8af0b2c77291a0d
+  metadata.gz: 767e21dce7e53eb8a74e430c736f2ba94e22c882022733fff7fb8edb058c118e
+  data.tar.gz: 4d9e7b6789d79daec4eb0482a22ac68520263c0a267e1b4e4def7eae97d9e642
 SHA512:
-  metadata.gz: 8bdcb84ca5d9becc44e9a181512ac19c9c8c24f5035e7da9da09a1ab59a4c09cd96b9cde80a8b5d073001ae6f36d9f4e1b3e1a3e640c4eafa6d30ac34800e47c
-  data.tar.gz: b09d59343870e8d16ef9e4c0794e7ec78486d5ab9c3eea339d99c4f8b4fa46f58ca5246ca3df70ed8a82c795fd4108c296c3bb19e720640c5acce080f0e90a98
+  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.
 
@@ -672,6 +671,11 @@ The per-record contract (Sentry `beforeSend` semantics):
   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
@@ -691,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
@@ -958,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`.
@@ -1093,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/before_send.rb

@@ -62,6 +62,7 @@ module Foam
       # flood an adversary-shaped record stream controls — rule 15's
       # "loud but never a flood" posture).
       def run(hooks, record, signal, faults)
+        identity = identity_of(record)
         current, counters = thaw(record)
         hooks.each do |hook|
           result = hook.call(current)
@@ -74,6 +75,7 @@ module Foam
           current = result
         end
         restore_counters!(current, counters)
+        restore_identity!(current, identity)
         current
       rescue StandardError, SystemStackError => e
         faults << e.class.name
@@ -110,9 +112,43 @@ module Foam
           copy.attributes = attributes.nil? ? {} : attributes.transform_values { |v| thaw_value(v) }
         end
         copy.body = thaw_body(copy.body) if copy.respond_to?(:body) && copy.respond_to?(:body=)
+        # The scope handed to the hook is a COPY: InstrumentationScope is a
+        # mutable Struct, and an in-place `scope.name =` on the shared
+        # object would corrupt process-global identity (see identity_of).
+        if copy.respond_to?(:instrumentation_scope) && copy.respond_to?(:instrumentation_scope=)
+          copy.instrumentation_scope = copy.instrumentation_scope&.dup
+        end
         [copy, sdk_drop_counters(record)]
       end
 
+      # resource / instrumentation_scope are process-global IDENTITY objects
+      # shared by every record the tracer/logger emits — and Ruby's
+      # InstrumentationScope is a plain MUTABLE Struct. A hook that renames
+      # the scope would corrupt the identity of EVERY subsequent span/log
+      # from that instrument (proven live in the 2026-07-29 retro-probe),
+      # and a wholesale `record.resource =` replacement would ship
+      # hook-authored resource attributes RAW — redaction never masks
+      # resource, so that path could widen what ships. Both are closed the
+      # way the Go port does it: identity always comes from the ORIGINAL
+      # record — captured here, force-restored onto the survivor after the
+      # pipeline (hook edits to identity are discarded; the encoder's
+      # group-by-identity stays intact). Documented in the README:
+      # resource/instrumentation_scope are informational, not hook-writable.
+      def identity_of(record)
+        {
+          resource: (record.resource if record.respond_to?(:resource)),
+          scope: (record.instrumentation_scope if record.respond_to?(:instrumentation_scope)),
+        }
+      end
+
+      def restore_identity!(record, identity)
+        record.resource = identity[:resource] if record.respond_to?(:resource=)
+        if record.respond_to?(:instrumentation_scope=)
+          record.instrumentation_scope = identity[:scope]
+        end
+        record
+      end
+
       def thaw_value(value)
         case value
         when String then value.dup

data/lib/foam/otel/version.rb

@@ -175,6 +175,25 @@ module Foam
     #   case) install NOTHING. Proven against the real agents in
     #   test-apps/ruby-coexistence (six vendors, both patch mechanisms,
     #   patched-client probe REQUIRED green).
-    VERSION = "1.9.0"
+    # 1.9.1: before_send IDENTITY RESTORE (retro-probe class 14; PATCH —
+    #   bugfix-only). resource / instrumentation_scope are process-global
+    #   identity objects, and InstrumentationScope is a MUTABLE Struct: a
+    #   hook renaming it corrupted the identity of every subsequent
+    #   span/log from that instrument (proven live), and a wholesale
+    #   `record.resource =` replacement shipped hook-authored resource
+    #   attributes RAW (redaction never masks resource — the one
+    #   can-never-widen gap). Hooks now receive a COPIED scope, and the
+    #   ORIGINAL resource/scope are force-restored onto every survivor
+    #   after the pipeline (identity is not hook-writable — the Go port's
+    #   contract; README updated).
+    # 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.0
+  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:
   - - ">="