opentel-mcp 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # 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

package/README.md

@@ -463,12 +463,26 @@ per-call-site wrapping; tracked in the roadmap below.
 
 ## Error recording (v0.13.0+)
 
-Every thrown `tools/call`/`tools/list` error goes through
-`span.recordException(err)` (an OpenTelemetry SDK method, not one of this
-library's own attributes) plus `span.setStatus({ code: ERROR, message:
-err.message })` — unconditionally, whether or not `fingerprinting` is
-enabled. By default that means `err.message` and `err.stack` land on the
-span exactly as thrown. `errorRecording.mode` controls this:
+**What this controls, and who needs it.** Whenever a `tools/call`/
+`tools/list` handler throws, this library records the thrown error's
+message and stack trace onto the span it creates for that call — by
+default, exactly as the tool wrote them, no redaction. If your tools call
+third-party services, wrap unaudited dependencies, or you otherwise don't
+control every string a tool might throw, that's a real channel for
+whatever those errors happen to contain (an email address, an internal
+hostname, a connection string a driver embedded in its own error message)
+to reach wherever your traces get exported. `errorRecording.mode` lets
+you scrub or drop that content instead of recording it verbatim — read
+both caveats below before treating it as a privacy control, though: it
+has two distinct limits, and neither is obvious from the option name
+alone.
+
+Mechanically: every thrown error goes through `span.recordException(err)`
+(an OpenTelemetry SDK method, not one of this library's own attributes)
+plus `span.setStatus({ code: ERROR, message: err.message })` —
+unconditionally, whether or not `fingerprinting` is enabled.
+`errorRecording.mode` controls what those two calls actually put on the
+span:
 
 | Mode | `exception.message` / status message | `exception.stacktrace` | When to use |
 |---|---|---|---|
@@ -476,30 +490,197 @@ span exactly as thrown. `errorRecording.mode` controls this:
 | `'normalized'` | `normalizeMessage(err.message)` — the exact scrubbing pipeline (`src/fingerprint/normalize/message.js`) fingerprinting already runs before hashing: UUIDs, emails, URLs, IPs, timestamps, filesystem paths, hex runs, quoted ids | Reconstructed from `parseAndNormalizeStack()` (`src/fingerprint/normalize/stack.js`) — keeps every function name/file/line, strips only the local `cwd` prefix (and collapses `node_modules` package versions) | Tool results come from third-party or unaudited MCP servers and you want the same scrubbing fingerprinting already trusts, applied to the raw exception content too |
 | `'none'` | Not set — `span.setStatus({ code: ERROR })` with no message, the same pattern already used for tool-level `isError: true` failures | Not set | You rely entirely on `mcp.failure.*` (category/fingerprint/signature — already hashed/normalized) and don't want any free-text exception content on the span at all |
 
-No mode mutates the original `err` — both call sites rethrow it
-afterward, so `'normalized'`/`'none'` build the exception event
-independently rather than editing `err.message`/`err.stack` in place.
-`error.type`/`exception.type` (`err.name`) is capped at 128 characters
-unconditionally in every mode — the same cap `mcp.failure.error_class`
-uses — since a length cap on a class-identifier field costs a
-well-behaved tool nothing, unlike message/stack content.
-
-**`'normalized'` is targeted scrubbing, not general-purpose redaction —
-read this before treating it as a PII filter.** `normalizeMessage()`
-matches specific, structured shapes: UUIDs, email addresses, URLs,
+**Caveat 1 — `'normalized'` is targeted scrubbing, not general-purpose
+redaction. Do not treat it as a PII filter.** `normalizeMessage()`
+matches specific, structured shapes only: UUIDs, email addresses, URLs,
 IPv4/IPv6 addresses, ISO-8601/Unix timestamps, filesystem paths, long hex
 runs, and quoted alphanumeric ids (8–64 chars, mixed letters/digits). It
-does not recognize sensitive content in general. An API key in a format
+does not recognize sensitive content in general — an API key in a format
 none of those patterns match (a bare, unquoted token with no digit in it,
 or a custom prefix scheme), or a customer's name embedded in ordinary
 prose ("could not process request for Jane Smith"), passes through
-`'normalized'` mode completely unchanged — identical to what `'full'`
-mode would put on the span. Treat `'normalized'` as "the same scrubbing
+`'normalized'` mode completely unchanged, identical to what `'full'`
+would put on the span. Treat `'normalized'` as "the same scrubbing
 fingerprinting already trusts for hashing," not as a guarantee that
-whatever a tool's error messages contain is safe to record; if a tool's
-errors routinely carry sensitive free text these patterns don't happen to
-match, `'none'` is the only mode that keeps message/stack content off the
-span entirely.
+whatever a tool's error messages contain is safe to record.
+
+**Example — the same thrown error, `'full'` vs. `'normalized'`:**
+
+```js
+throw new Error('upstream lookup failed for user jane.doe@example.com');
+```
+
+| Mode | `exception.message` on the span |
+|---|---|
+| `'full'` | `upstream lookup failed for user jane.doe@example.com` |
+| `'normalized'` | `upstream lookup failed for user <EMAIL>` |
+| `'none'` | *(not set — only the ERROR status code is)* |
+
+The stack trace scrubs the same way: `'full'` keeps every frame's
+absolute path; `'normalized'` keeps every frame (function name, file,
+line) but strips the local `cwd` prefix.
+
+### The redactor hook (v0.14.0+)
+
+Caveat 1 above is the reason this exists: `normalizeMessage()` matches
+eight specific, structured shapes (UUIDs, emails, URLs, IPv4/IPv6,
+timestamps, paths, hex runs, quoted ids), and that is where its
+competence ends. An API key in your own proprietary format
+(`ACME_KEY_[a-f0-9]{8}`), an internal account id shape
+(`ACCT-\d{9}`), or a customer's name embedded in ordinary prose are not
+structurally distinguishable from ordinary text by any pattern this
+library could ship — no ninth built-in pattern fixes that. Only the host
+running the tool knows what their own data looks like.
+`errorRecording.redactor` is a synchronous function you supply that runs
+as part of `mode: 'normalized'`, so you can close that gap without
+forking this library or falling back to `'none'`'s blunt "drop
+everything." See ADR 020 (`docs/adr/020-redactor-hook.md`) for the full
+design rationale; the operator-facing behavior is summarized below.
+
+**Worked example:**
+
+```js
+instrumentMcpServer(server, {
+  errorRecording: {
+    mode: 'normalized',
+    redactor: ({ message, stack }) => ({
+      message: message
+        .replace(/ACME_KEY_[a-f0-9]{8}/g, '[API_KEY]')
+        .replace(/ACCT-\d{9}/g, '[ACCOUNT_ID]'),
+      stack, // unchanged — this redactor only needs to touch the message
+    }),
+  },
+});
+```
+
+```js
+throw new Error(
+  'auth failed for ACME_KEY_7f3a9c2e, ' +
+  'account ACCT-123456789, contact jane.doe@example.com',
+);
+```
+
+| Step | `exception.message` |
+|---|---|
+| Raw, as thrown | `auth failed for ACME_KEY_7f3a9c2e, account ACCT-123456789, contact jane.doe@example.com` |
+| After your redactor (runs first, on the raw text) | `auth failed for [API_KEY], account [ACCOUNT_ID], contact jane.doe@example.com` |
+| After this library's own patterns (run second, on YOUR output) | `auth failed for [API_KEY], account [ACCOUNT_ID], contact <EMAIL>` |
+
+**Ordering matters, and it's fixed, not configurable:** your redactor
+always runs first, on the raw, uncoerced `message`/`stack` — before
+`normalizeMessage()`/`parseAndNormalizeStack()` ever see them, never the
+reverse. Two consequences follow directly: (1) this library's own
+scrubbing is still the last thing that touches the content before it
+reaches the span — a defense-in-depth backstop if your redactor misses a
+shape its own patterns don't cover (see the API key example above:
+notice `<EMAIL>` still gets scrubbed even though your redactor never
+mentioned email addresses), and (2) your redactor sees the full,
+untruncated original message — `normalizeMessage()`'s 2048-character
+truncation applies afterward, to your output, not before you ever see the
+content.
+
+**Only consulted under `mode: 'normalized'`.** Configure a redactor
+alongside `'full'` or `'none'` and it's accepted but never called — those
+two modes' entire meaning is "byte-identical to their own fixed
+behavior, regardless of what else is configured." Since forgetting to
+also flip `mode` away from its `'full'` default is an easy way to end up
+with a redactor that's silently never invoked, `instrumentMcpServer()`
+logs a one-time `diag.warn()` at setup naming exactly that.
+
+**Failure never falls back to raw content.** If your redactor throws,
+returns a non-string `message`, or returns a `stack` that's neither a
+string nor `undefined`, that one event falls back to `'none'`-equivalent
+output — `span.setStatus({ code: ERROR })` only, no `exception` event at
+all — never to `'full'`-equivalent (raw, unredacted) content. A redactor
+you configured specifically to keep something off the span must never
+silently fail open; the safe direction here is *more* redacted, not
+less. This fires a one-time, content-free `diag.warn()` naming the
+failure shape (`threw` / `returned a non-string message` / `returned an
+invalid stack`) — never the message/stack content that triggered it,
+so the warning itself can't become a second, undocumented leak channel.
+Your redactor's returned `message`/`stack` are also length-capped
+defensively before use (reusing `normalizeMessage()`'s own 2048-character
+limit), regardless of what a well-behaved redactor is expected to
+return.
+
+**Timing — read this before you write a regex.** The redactor runs
+*synchronously*, inline, on the error path — inside the still-open
+span's own callback, before `span.end()` is called. There is no timeout,
+and there cannot be one: JavaScript is single-threaded, and nothing in
+this library (or in Node itself, short of a `worker_threads` boundary
+this feature deliberately doesn't pay for) can interrupt a synchronous
+function that's already running. **This means a slow redactor doesn't
+just delay telemetry — it delays the tool call's own response to
+whoever's waiting on it.** Catastrophic backtracking in a regex (the
+classic `(a+)+$`-shaped footgun), an accidental synchronous file read, or
+any blocking call inside your redactor adds directly to that tool call's
+latency, on every single call that throws under `'normalized'` mode,
+for as long as the redactor stays slow. Test your redactor's regexes
+against adversarial input the same way you would for any other
+user-facing regex, not just against the examples you had in mind when
+you wrote it.
+
+**The fingerprint is completely unaffected — on purpose, always.**
+`mcp.failure.fingerprint`/`mcp.failure.signature` and the values hashed
+into them are computed from the real, unmodified thrown error, identically
+whether or not a redactor is configured. A redactor has no way to reach
+that computation at all — it only ever touches what lands on the span.
+This is deliberate: the fingerprint is a SHA-256 hash, never a plaintext
+channel, so redacting it would buy no privacy while tying fingerprint
+stability to your own, unversioned redactor code. Practically, this means
+any saved dashboard filter or alert keyed on `mcp.failure.fingerprint`
+keeps working exactly as before the moment you add a redactor — nothing
+about adding or changing one ever reshuffles a fingerprint value.
+
+The redactor is still scoped to this library's own span, the same as
+every other `mode` value — see Caveat 2 below for what that does and
+doesn't cover; nothing about the redactor changes that boundary.
+
+**Caveat 2 — every mode is scoped to the span this library creates, not
+to your trace as a whole.** No mode mutates the original `err` — both
+call sites rethrow it afterward, so `'normalized'`/`'none'` build the
+exception event independently rather than editing `err.message`/
+`err.stack` in place. The consequence: the unmodified, fully raw `err` is
+exactly what propagates to whatever called this handler. If any other
+instrumentation further out in the call stack — an APM agent, HTTP or
+framework auto-instrumentation, anything else wrapping this handler —
+independently calls `recordException(err)`/`setStatus({ message:
+err.message })` on its OWN span when it observes the rethrow, the raw,
+unscrubbed message and stack land in the SAME TRACE as this library's
+(scrubbed) span, one span up, not on it. `'none'` buys no more protection
+here than `'normalized'`: neither mutates `err`, so an outer recorder
+sees the identical raw content either way. Someone choosing `'none'`
+specifically to keep sensitive content out of their tracing backend needs
+to know that protection stops at this library's own span, not at the
+trace boundary.
+
+Confirmed directly, not just reasoned about: an instrumented server run
+under a real ambient context manager (`AsyncLocalStorageContextManager` —
+the propagation mechanism production deployments actually use, unlike
+this project's own test suite, which registers most test files with
+`contextManager: null` and therefore can't exercise this path — see
+`docs/known-gaps.md` entry 10's latest update for why that's fine for
+those specific tests), wrapped in an outer span that calls
+`recordException(err)` on catch, with `errorRecording.mode: 'normalized'`
+set and an `InMemorySpanExporter` attached: the tool span's exception
+event carries the scrubbed message, and the ancestor span's exception
+event and status message both carry the original, raw one — same trace
+ID, parent/child span relationship confirmed, no mutation anywhere in
+between.
+
+**This is not fixable from inside this library.** The only way to close
+it here would be mutating `err.message`/`err.stack` in place before
+rethrowing — which would corrupt whatever error-handling the host
+application does with that same object afterward, a correctness hazard
+this library isn't willing to trade for a telemetry one. It has authority
+over one span; it has no visibility into, and no control over, what other
+instrumentation attached to the same process does with the error once
+rethrown. See `docs/known-gaps.md` entry 10 for the full writeup.
+
+`error.type`/`exception.type` (`err.name`) is capped at 128 characters
+unconditionally in every mode — the same cap `mcp.failure.error_class`
+uses — since a length cap on a class-identifier field costs a
+well-behaved tool nothing, unlike message/stack content.
 
 **Default stays `'full'` through all of `0.x`.** Changing it would alter
 what every trace backend renders for the single highest-traffic failure
@@ -513,6 +694,7 @@ for the full argument, including why the default is expected to flip to
 | Option | Env var | Type | Default | Description |
 |---|---|---|---|---|
 | `mode` | `OTEL_MCP_ERROR_RECORDING_MODE` | `'full'` \| `'normalized'` \| `'none'` | `'full'` | See table above. An unrecognized value falls back to `'full'` silently, same as every other `OTEL_MCP_*` env var |
+| `redactor` | *(none — a function can't be expressed as an env var string)* | `(input: { message: string, stack: string \| undefined }) => { message: string, stack: string \| undefined }` | `undefined` | See "The redactor hook" above. Only consulted when `mode` is `'normalized'`; a non-function value is treated as absent, silently |
 
 ## Cost & Token Attribution (v0.5.0)
 
@@ -1863,23 +2045,145 @@ sensitive information" and still specify recording it by default —
 every other OTel-instrumented library sharing the same trace (an HTTP
 client, a DB driver, a queue consumer) records `err.message`/`err.stack`
 the same way, unscrubbed, through the same `recordException()` call.
-opentel-mcp matches that ecosystem default rather than silently diverging
-from it. What it adds on top: `errorRecording.mode` lets you choose
-`'normalized'` (targeted scrubbing — the same structured patterns
-fingerprinting matches: UUIDs, emails, URLs, IPs, timestamps, paths,
-quoted ids; **not** a general-purpose PII filter, so freeform sensitive
-text — a customer's name in prose, an API key in a format none of those
-patterns match — still reaches the span unchanged, see "Error recording"
-above) or `'none'` (record neither) instead of `'full'` — a level of
-operator control most peer instrumentations don't offer for this path.
-Full reasoning, including why the default doesn't change in this
-release: ADR 019 (`docs/adr/019-raw-content-on-spans.md`).
+That covers a sharper case than "different libraries recording their own,
+separate operations," too: an outer wrapper — an APM agent's own request
+span, or HTTP/framework auto-instrumentation sitting further out in the
+call stack — independently recording the very same error this library
+just scrubbed. No `errorRecording.mode` mutates the original `err` (see
+"Error recording" above), so a rethrown error is exactly what such a
+wrapper sees; if it calls `recordException(err)` on its own span, the raw
+content lands one span up in the identical trace, regardless of which
+mode is set here. opentel-mcp matches that ecosystem default rather than
+silently diverging from it. What it adds on top: `errorRecording.mode`
+lets you choose `'normalized'` (targeted scrubbing — the same structured
+patterns fingerprinting matches: UUIDs, emails, URLs, IPs, timestamps,
+paths, quoted ids; **not** a general-purpose PII filter, so freeform
+sensitive text — a customer's name in prose, an API key in a format none
+of those patterns match — still reaches the span unchanged, see "Error
+recording" above) or `'none'` (record neither) instead of `'full'` — a
+level of operator control most peer instrumentations don't offer for this
+path, scoped to the span this library creates, not a trace-wide
+guarantee. Full reasoning, including why the default doesn't change in
+this release: ADR 019 (`docs/adr/019-raw-content-on-spans.md`).
 
 This is a data-handling property of an observability library, not a
 security control opentel-mcp is claiming to provide — it doesn't
 authenticate, encrypt, or restrict who can read your traces; that's your
 tracing backend's job.
 
+### Full attribute provenance
+
+The paragraphs above cover the three channels with real content risk;
+the table below is the complete picture — every attribute this library
+sets, anywhere, classified by where its value actually comes from. It was
+produced by tracing every `span.setAttribute()`/`setAttributes()`/
+`addEvent()` call site back to its source, generalizing the manual audits
+`docs/known-gaps.md` entries 10 and 11 already did by hand for the
+riskiest subset.
+
+**Why a table instead of a runtime "audit mode":** provenance here is a
+property of which code path sets an attribute, not of any particular
+call's runtime state — it's the same answer on every call, for a given
+release, until the code setting that attribute changes. A live inspection
+feature can't tell you anything about *category* this table doesn't
+already say, for free, with no new code and no new place for a value to
+leak. Where a table genuinely falls short — "what's the *actual* value
+landing in this attribute for my traffic" — the fix isn't a new library
+feature; it's the extension hooks documented below, which already exist
+and were built for exactly this. "Only the host knows what's safe to look
+at in their own deployment" is the same principle `errorRecording.redactor`
+itself is built around (ADR 020) — reused here, not re-solved.
+
+Four categories: **library-computed** (a hash, count, enum, or fixed
+constant — the safe majority), **host-supplied** (an `instrumentMcpServer()`
+config value), **SDK-supplied** (a transport/protocol id — session,
+request, span, trace), and **tool-controlled** (content from a tool's own
+result or the caller's own arguments — the category every raw-content
+finding in `docs/known-gaps.md` traces back to). Eight rows below are
+genuine **blends** — a single word would mislead for these specifically,
+so they're spelled out instead of forced into one bucket.
+
+| Attribute | Surface | Provenance | Note |
+|---|---|---|---|
+| `mcp.method.name` | span attr | library-computed | fixed string per handler |
+| `gen_ai.operation.name` | span attr | library-computed | fixed string `"execute_tool"` |
+| `gen_ai.tool.name` | span attr, metric label | **blend — tool-controlled** | `request.params.name`, unvalidated against the registered tool set (`docs/known-gaps.md` entry 11) |
+| `jsonrpc.request.id` | span attr | SDK-supplied | transport/protocol correlation id |
+| `mcp.tool.argument_count` | span attr | tool-controlled | a *count* of `request.params.arguments` keys, deliberately — never the argument values themselves |
+| `error.type` | span attr | **blend — depends on code path** | the tool's own `err.name` on a thrown failure; the fixed constant `tool_error` on an `isError: true` failure — same key, two different sources depending on which failure path fired. See "Two keys whose provenance changes by code path" below |
+| `gen_ai.response.model` | span attr | tool-controlled | co-emitted from the same value as `mcp.tool.model`, for dashboard compatibility |
+| `mcp.tool.tokens.input` / `.output` | span attr | tool-controlled | the tool result's own usage numbers |
+| `mcp.tool.tokens.total` | span attr | library-computed | sum of the two tool-controlled values above |
+| `mcp.tool.model` | span attr, metric label | tool-controlled | a tool result's own declared model field, echoed verbatim (`docs/known-gaps.md` entry 10, item 2 — still open) |
+| `mcp.tool.cost.usd` | span attr | **blend — library-computed over tool-controlled × config** | tool-controlled token counts, multiplied by a pricing table that's either this library's default or a host override |
+| `mcp.tool.cost.currency` | span attr | library-computed | fixed constant `"USD"` |
+| `mcp.tool.cost.budget_exceeded` / `.budget_scope` | span attr | library-computed | comparison against a host-supplied budget threshold |
+| `mcp.tool.pricing_status` | span attr, metric label | **blend — library-computed, depends on tool + host** | which of three enum values depends on a tool-controlled model name resolving (or not) in a library-default-or-host-overridden pricing table |
+| `mcp.failure.fingerprint` / `.signature` / `.category` / `.origin` / `.channel` | span attr (2 also metric labels) | library-computed | hashes/enums — the governed core this project has kept clean since v0.4.0 |
+| `mcp.failure.error_class` | span attr | **blend — tool-controlled, capped only** | `err.name`, length-capped at 128 characters but, unlike everything hashed into the fingerprint, *not* pattern-scrubbed — a documented, deliberate tradeoff (`docs/known-gaps.md` entry 10) |
+| `mcp.failure.validation_paths` | span attr | mostly library-computed (gated) | one legacy Zod-issue-rendering path can still carry a tool-controlled dynamic object key, now redacted to a `<KEY>` placeholder rather than closed structurally (`docs/known-gaps.md` entry 10, item 3) |
+| `exception.type` (event) | event attr | tool-controlled | length-capped only under `'normalized'` mode; uncapped under `'full'` (the native SDK call) |
+| `exception.message` / `.stacktrace` (event), status message | event attr + status | **blend — layered** | raw tool content under `'full'`; this library's `normalizeMessage()`/`parseAndNormalizeStack()` transform of that same content under `'normalized'`; optionally a host-supplied `errorRecording.redactor`'s output feeding *that*, first (v0.14.0) — the most layered-provenance attribute in the system |
+| `mcp.tool.schema_drift_detected` / `mcp.tool.thrash_detected` | boolean span attr | library-computed | only ever set to `true`; omitted on a clean call |
+| `mcp.tool.schema_drift.type` | event attr, metric label | library-computed | classifier enum |
+| `mcp.tool.schema_drift.previous_hash` / `.current_hash` | event attr | library-computed | a hash *of* tool-controlled content (the tool's own `inputSchema`), not the schema itself |
+| `mcp.tool.schema_drift.added_fields` / `.removed_fields` / `.changed_fields` | event attr | **blend — tool-controlled, unbounded** | literal property names from a tool's own schema — unbounded across every tool anyone registers, unlike `argument_count` above, which is deliberately reduced to a number for exactly this reason |
+| `mcp.loop.length` / `.duration_ms` | event attr | library-computed | count / timestamp arithmetic |
+| `mcp.loop.wasted_tokens_in` / `_out` / `.wasted_cost_usd` | event attr | library-computed over tool-controlled | same aggregation/pricing chain as `mcp.tool.tokens.*`/`mcp.tool.cost.usd` above |
+| `mcp.loop.first_span_id` / `.first_trace_id` | event attr | SDK-supplied | OTel SDK-generated span/trace ids |
+| `mcp.loop.session_id` | event attr | **blend — depends on code path** | a real transport session id when one exists; a library-generated fallback UUID when it doesn't. See "Two keys whose provenance changes by code path" below |
+| `service.name` | resource attr | host-supplied | the `serviceName` config option (`setupNodeSdk: true` only) |
+| `mcp.pricing.default_table_last_verified` | resource attr | library-computed | constant, attached only when using the unmodified default pricing table |
+| `mcp.tool.outcome` | metric label only | library-computed | never a span attribute — `mcp.tool.duration`'s own outcome dimension |
+
+**Two keys whose provenance changes by code path, not just by
+configuration:**
+
+- **`error.type`** carries the tool's own `err.name` when the failure was
+  a thrown exception, but a fixed library constant (`tool_error`) when
+  the failure was a successful JSON-RPC response with `isError: true` —
+  same attribute key, genuinely different source depending on which of
+  the two failure paths produced it.
+- **`mcp.loop.session_id`** carries a real transport-assigned session id
+  under a session-oriented transport, but a library-generated fallback
+  UUID (`resolveThrashSessionId()`, `src/instrument.js`) under a
+  transport this library can't positively confirm is session-oriented —
+  see "Agent Thrash Detection" → sessionId fallback resolution above. The
+  value is a real id either way; only *who* generated it differs.
+
+**`mcp.server.name` / `mcp.server.version`** are defined in
+`src/attributes.js` but are not currently set anywhere in this codebase —
+dead constants, not a real attribute this library records today. Left
+out of the table above for that reason.
+
+**Want to see the actual value landing in an attribute for your own
+traffic, not just its category?** Don't reach for a new debugging mode —
+the hooks that let you do this safely already exist, because *you*, not
+this library, know what's safe to look at in your own deployment:
+
+- **`errorRecording.redactor`** (ADR 020, `docs/adr/020-redactor-hook.md`)
+  sees the raw `message`/`stack` before this library's own scrubbing runs
+  — a temporary, local redactor that copies what it receives to wherever
+  *you've* decided is safe (your own log line, a breakpoint, a counter)
+  shows you exactly what's landing in `exception.message`/`.stacktrace`
+  for real calls, without this library needing to add a second channel
+  for the same content.
+- **`costTracking.extractor`** (a `UsageExtractor`) sees the full tool
+  result before token/model/cost attribution runs — the same trick works
+  for `mcp.tool.tokens.*`/`mcp.tool.model`/`mcp.tool.cost.*`.
+- **A custom `Classifier`** (`opts.classifiers` on `computeFingerprint()`,
+  `src/fingerprint/compose.js` — see "Deep-failure fingerprinting" →
+  "Extending it" above) sees the coerced error before classification.
+  Unlike the two hooks above, this one isn't yet wired through
+  `instrumentMcpServer()`'s own options — using it today means calling
+  `computeFingerprint()` directly rather than relying on the automatic
+  per-call wrapping.
+
+Each hook is scoped to exactly the content it already has access to; none
+of them create a new place for that content to reach — they're extension
+points this library already ships and already documents, not a bespoke
+audit feature.
+
 ## Configuration
 
 All options passed to `instrumentMcpServer(server, options)`. Source of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",