opentel-mcp 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,214 @@
 # Changelog
 
+## 0.14.0
+
+Adds `errorRecording.redactor`: a host-supplied hook for content
+`normalizeMessage()`/`parseAndNormalizeStack()` don't recognize — a
+proprietary API key format, an internal account id shape, a customer name
+in prose or in a multi-tenant stack frame path. Full design: ADR 020
+(`docs/adr/020-redactor-hook.md`). Ships in the same release as the
+0.13.1 fix/docs items below (0.13.1 itself was never tagged/published —
+see that section's own note), but is a logically separate, purely
+additive change from both of them; kept in its own section here rather
+than folded into 0.13.1's for that reason.
+
+### Added — `errorRecording.redactor` hook (ADR 020)
+
+- New optional `errorRecording.redactor` field: a synchronous
+  `(input: { message, stack }) => { message, stack }` function, consulted
+  only under `mode: 'normalized'`, that runs on the raw, uncoerced
+  `message`/`stack` — via the same coercion this library's own pipeline
+  already uses — **before** `normalizeMessage()`/`parseAndNormalizeStack()`
+  ever see them, never the reverse. This library's own scrubbing still
+  runs second, over your redactor's output, as a defense-in-depth
+  backstop.
+- Configuring a redactor alongside `mode: 'full'` or `'none'` is accepted
+  but never invoked — those two modes' entire meaning is "byte-identical,
+  regardless of what else is configured" — and produces a one-time
+  `diag.warn()` at `instrumentMcpServer()` setup naming the no-op, since
+  forgetting to also flip `mode` is an easy, otherwise-silent
+  misconfiguration.
+- A redactor that throws, returns a non-string `message`, or returns a
+  `stack` that's neither a string nor `undefined` falls back to
+  `'none'`-equivalent span output for that one event — status set, no
+  `exception` event — **never** to raw/unredacted content, plus a
+  one-time, content-free `diag.warn()` naming the failure shape (never
+  the message/stack content itself). The returned `message`/`stack` are
+  also length-capped defensively before use (reusing
+  `normalizeMessage()`'s existing 2048-character limit).
+- **Never reaches `computeFingerprint()`'s hash input, in any
+  configuration.** `mcp.failure.fingerprint`/`signature` are computed
+  from the real, unmodified thrown error, identically whether or not a
+  redactor is configured — a deliberate, non-negotiable design decision
+  (ADR 020 Decision 3): the fingerprint is a SHA-256 hash, never a
+  plaintext channel, so redacting it would buy no privacy while tying
+  fingerprint stability to unversioned host code. Any existing dashboard
+  filter or alert keyed on `mcp.failure.fingerprint` keeps working
+  unchanged after adding a redactor.
+- **Timing caveat, not just a telemetry one:** the redactor runs
+  synchronously, inline, on the error path, before the span ends — there
+  is no timeout, and JavaScript's single-threaded execution model means
+  one can't be added without a `worker_threads`/`vm.Script` boundary this
+  feature deliberately doesn't pay for. A slow redactor (catastrophic
+  regex backtracking, an accidental blocking call) adds directly to that
+  tool call's own response latency, not just to what shows up in traces.
+  See the README's "The redactor hook" section, "Timing," for the full
+  writeup, and ADR 020's own "Timing" section for why this is an accepted
+  risk rather than a solved one.
+- No environment-variable equivalent — a function can't be expressed as
+  an `OTEL_MCP_*` string, same as `costTracking.extractor`/
+  `thrashDetection`'s classifier-shaped options already are.
+- New exported types `ErrorRecordingRedactor` and
+  `ErrorRecordingRedactorFields` (`src/error-recording/types.d.ts`,
+  re-exported from the package root) — a consumer can type a redactor
+  function on its own, the same way `UsageExtractor`/`Classifier` already
+  let a consumer type an extractor/classifier independently of the option
+  object that carries it.
+- Purely additive and default-off: a deployment that never sets
+  `errorRecording.redactor` observes zero behavior change.
+
+## 0.13.1
+
+Never tagged or published as its own release — ships bundled into
+0.14.0 above instead, since the redactor work started before this patch
+went out the door. Kept as its own section here (rather than merged into
+0.14.0's) because both items below are logically independent of the
+redactor: one's a bug fix to existing `'normalized'`-mode behavior, the
+other's a documentation-only correction, and neither has anything to do
+with the new hook.
+
+### Fixed — `'normalized'` mode dropped `exception.message`/status message for non-`Error` throws
+
+- Before this fix, `recordThrownException()`'s `'normalized'` branch
+  independently re-derived `message`/`stack` via a plain `err?.message`/
+  `err?.stack` read — which silently returned `undefined` for a thrown
+  **string** or a plain non-`Error` object (neither has a `.message`
+  property the way a real `Error` instance does), while
+  `computeFingerprint()`'s own, richer `coerceError()` correctly
+  recognized those same shapes and still produced a real
+  `mcp.failure.fingerprint`. Net effect: a thrown string or non-`Error`
+  throw got real fingerprinting but a completely empty `exception.message`
+  / status message on the span under `'normalized'` mode — same `err`,
+  two independent readers, two different answers, silently.
+- Fixed by extracting the shared `normalizeException()`/`coerceError()`
+  pair into their own module (`src/fingerprint/normalize/exception.js`)
+  and routing **both** `computeFingerprint()` and `recordThrownException()`
+  through the same one computation for the same `err` — the span's
+  exception content and the fingerprint's hashed inputs can no longer
+  independently drift apart, by construction, not by convention. This is
+  the same consolidation ADR 020 (the redactor's own design doc, above)
+  repeatedly cites as precedent for keeping the fingerprint path
+  structurally isolated from the span-writing path going forward.
+- `'full'` and `'none'` modes were never affected — this bug was specific
+  to `'normalized'` mode's own inline coercion.
+
+### Documentation — `errorRecording.mode` scoping correction
+
+- Clarified that `errorRecording.mode` controls only the span this
+  library creates for the current `tools/call`/`tools/list` — it has no
+  effect on exception content any other instrumentation in the same
+  process (an APM agent, HTTP or framework auto-instrumentation, anything
+  else wrapping the handler) independently records onto its own span for
+  the same rethrown error. Since no mode mutates the original `err`, that
+  raw content can still land in the same trace, one span up, regardless
+  of mode — including `'none'`, which was previously worded in a way that
+  could read as a trace-wide guarantee rather than a span-scoped one.
+  Confirmed empirically (a real ambient context manager, an outer span
+  recording the rethrown error, `InMemorySpanExporter`) — see
+  `docs/known-gaps.md` entry 10's 2026-09-01 update for the full
+  reproduction and reasoning. README's "Error recording" and "What this
+  library records" sections updated accordingly. No code changed — the
+  underlying behavior (and the exposure at the default `'full'` mode) was
+  already accurate and unchanged; only the description of what
+  `errorRecording.mode` scopes to was incomplete.
+
+## 0.13.0
+
+Closes the two open items from `docs/known-gaps.md` entry 10 (a
+raw-content audit of every attribute/span event this package emits) that
+needed a design decision before a fix — raw exception content on
+`recordException`/`setStatus`, and an unvalidated tool-result model field
+reaching `mcp.tool.model`/`gen_ai.response.model` — plus the two
+lower-risk fixes from the same entry that didn't need one. Full design:
+ADR 019 (`docs/adr/019-raw-content-on-spans.md`). See the README's new
+"What this library records" and "Error recording" sections for the
+operator-facing consequence of each.
+
+### Added — `errorRecording.mode` config (ADR 019 Part 1)
+
+- New top-level `errorRecording` option, sibling to `fingerprinting` /
+  `costTracking` / `thrashDetection` / `schemaDrift`: `'full'` (default,
+  byte-for-byte unchanged from every prior release —
+  `recordException(err)` + `setStatus({ message: err.message })` with the
+  raw error), `'normalized'` (reuses the existing
+  `normalizeMessage()`/`parseAndNormalizeStack()` fingerprinting pipeline
+  — no new scrubbing logic — to strip known-sensitive-shaped substrings
+  from the message and the local `cwd` prefix from the stack, without
+  mutating the original `err`, which both call sites still rethrow), or
+  `'none'` (records neither — the same `setStatus({ code: ERROR })`
+  no-message pattern already used for tool-level `isError: true`
+  failures). Applies to both thrown-exception paths, `tools/call` and
+  `tools/list`.
+- New `OTEL_MCP_ERROR_RECORDING_MODE` env var — same
+  option-then-env-then-default precedence, and the same silent fallback
+  to the default on an unrecognized value, as every other `OTEL_MCP_*`
+  config.
+- `error.type`/`exception.type` (both read from `err.name`) are now
+  capped at 128 characters unconditionally, in every mode — the same cap
+  `mcp.failure.error_class` uses below, reusing its exported constant
+  rather than a second, possibly-drifting copy.
+- Default stays `'full'` for all of `0.x`; ADR 019 Part 1 records the
+  intent to flip it to `'normalized'` at `1.0`, not before — not decided
+  in this release.
+
+### Added — `mcp.tool.model` / `gen_ai.response.model` validation (ADR 019 Part 2)
+
+**This is new behavior that can change what a call reports, not just a
+new diagnostic.** Before this release, a tool result's `model` field
+reached the span completely unvalidated, whatever it was. If you have a
+provider/deployment whose model identifiers use a character outside
+`[A-Za-z0-9._:/@-]`, or that (implausibly, but possibly) exceed 256
+characters, upgrading will make `mcp.tool.model`/`gen_ai.response.model`
+disappear from those calls' spans and `mcp.tool.pricing_status` flip from
+whatever it was to `"unknown"` — even for an otherwise-legitimate, real
+model id. The allowlist was deliberately built generous (see below) and
+verified against known provider conventions, but it's still new, and a
+one-time `diag.warn()` names when this happens (shape only, never the
+value) so it's discoverable rather than a silent metric/span change.
+
+- A tool result's declared model field is now checked against a 256-
+  character length cap and a `[A-Za-z0-9._:/@-]` allowlist — verified
+  against every `DEFAULT_PRICING` key and `normalizeModelName()`'s
+  documented `provider/model` input contract, deliberately generous —
+  before it can reach `mcp.tool.model`, `gen_ai.response.model`,
+  `calculateCost()`, or either metric label
+  (`mcp.tool.tokens.total`/`mcp.tool.cost.total`).
+- A rejected value is never a silent drop: `mcp.tool.pricing_status` is
+  set to `"unknown"` (the same status a legitimately unrecognized model
+  already produces), and a one-time `diag.warn()` fires per
+  `instrumentMcpServer()` call, reporting shape only — length, and which
+  check failed — never the rejected value itself.
+- `budgetTracker.recordUnpriced()` now receives the validated (possibly
+  `undefined`) model rather than the raw tool-result value, closing a
+  second leak path through its own pre-existing warning that would
+  otherwise have echoed a rejected value verbatim.
+- `costTracking.pricing`/`pricingTable` override keys are unaffected —
+  operator-authored config, never subject to this gate.
+
+### Fixed — `mcp.failure.error_class` uncapped length, `mcp.failure.validation_paths` dynamic-key leak (known-gaps entry 10)
+
+- `mcp.failure.error_class` is now capped at 128 characters
+  (`fingerprint/compose.js`'s new `MAX_ERROR_CLASS_LENGTH`) — length-
+  bounded only, not pattern-scrubbed; a non-string `.name` is coerced to
+  a string before capping rather than thrown. ADR 004's note calling the
+  underlying value "low-cardinality" is updated to flag that as an
+  assumption, not an enforced property.
+- `mcp.failure.validation_paths` format 1 (the raw Zod issues array, SDK
+  ≤1.29.0) now redacts a non-identifier-shaped path segment — a
+  `z.record()` schema's runtime key — to the placeholder `<KEY>` instead
+  of surfacing it verbatim, matching the identifier-only gate formats 2/3
+  already applied. Numeric (array-index) segments are never redacted.
+
 ## 0.12.0
 
 Agent Thrash Detection gains a new, narrower session-identity fallback for