opentel-mcp 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,225 @@
 # Changelog
 
+## 0.15.0
+
+"Make it visible" — no instrumentation changes, no `tools/call` hot-path
+changes. Phase 1 (ADR 022, `docs/adr/022-publish-ui.md`): publishes
+`opentel-mcp-ui`, previously a working but `"private": true`, unpublished
+scaffold with zero mentions in this README. See
+[`opentel-mcp-ui`'s own CHANGELOG](https://www.npmjs.com/package/opentel-mcp-ui)
+for what changed in that package. Phase 2 (ADR 023,
+`docs/adr/023-dev-mode-metrics.md`): dev-mode metrics under
+`setupNodeSdk: true` — see "Added" below.
+
+### Added
+
+- README: a "See it locally" section near the top, pointing at
+  `npx opentel-mcp-ui --demo` — this library had no documented way for a
+  new reader to see its own output before installing anything.
+- `setupNodeSdk: true` now also stands up an owned `MeterProvider` (ADR
+  023): a `PeriodicExportingMetricReader` exporting all 12 `mcp.tool.*`/
+  `mcp.tool.loop.*`/`mcp.tool.schema_drift.*` instruments to stderr every
+  5 seconds, via a new `StderrMetricExporter` (compact
+  `name{attrs} = value` lines, never a stdout-writing JSON dump — same
+  ADR 003 reasoning `StderrSpanExporter` already follows). Gated
+  additionally by `enableMetrics` (default `true`, unchanged option).
+  Closes the gap where the documented 30-second quickstart emitted
+  stderr spans but none of its 12 metrics. `setupNodeSdk: false` (the
+  default, and the production posture) is completely unaffected — every
+  new code path is gated behind the same existing `setupNodeSdk === true`
+  check `StderrSpanExporter` already uses.
+  - If a `MeterProvider` is already registered globally when this runs
+    (your own, or anything else's), this is a complete no-op: nothing is
+    overridden, no exception is thrown, and a single `diag.warn` (once
+    per process, not once per `instrumentMcpServer()` call) names the
+    situation. Detected via `@opentelemetry/api`'s own documented
+    `boolean` return from `setGlobalMeterProvider()` — not by inspecting
+    internals. The abandoned candidate provider built before that check
+    is shut down immediately (fire-and-forget), closing a leak where its
+    own periodic reader would otherwise tick forever, unused, in the
+    background.
+  - `server.shutdown()` (already attached under `setupNodeSdk: true`) now
+    also flushes and shuts down this `MeterProvider`, alongside the
+    existing `TracerProvider` shutdown it already performed.
+  - `StderrMetricExporter` only reprints a metric when its value has
+    actually changed since the last export. Every instrument here is
+    CUMULATIVE, so without this a single early tool call would otherwise
+    reprint two unchanged lines every 5 seconds for the rest of the
+    process's life — confirmed empirically before this fix shipped, not
+    assumed.
+
+### Changed
+
+- **`@opentelemetry/sdk-metrics` is now a runtime (`dependencies`, not
+  `devDependencies`) dependency of `opentel-mcp`, installed for every
+  user — including under `setupNodeSdk: false`, which never executes any
+  code from it.** Needed at import time for the feature above; moving it
+  to `dependencies` means `npm install opentel-mcp` always pulls it in,
+  regardless of whether a given deployment ever sets `setupNodeSdk: true`.
+  Adds no new transitive dependency: its own two dependencies
+  (`@opentelemetry/core`, `@opentelemetry/resources`) were already in
+  this package's tree via `@opentelemetry/sdk-trace-node`/the existing
+  `@opentelemetry/resources` dependency. See ADR 023's "Dependency
+  strategy" section for the full reasoning, including why an optional-peer
+  + dynamic-import approach was considered and rejected.
+
+### Fixed
+
+- The example servers (`examples/hello-server`, `examples/hello-mcpserver`)
+  never showed a metrics line in their own READMEs' "What you'll see": a
+  single piped `tools/call` request exits the process before the 5-second
+  export interval. Both now flush once via `process.on('beforeExit', ...)`
+  right before the process would otherwise exit — confirmed
+  `StdioServerTransport` does not call its own `close()`/`onclose` on
+  stdin EOF, so `beforeExit` is the one hook that still allows the async
+  flush to complete first.
+- Documentation only, no code/behavior changes:
+  - README claimed "Four `mcp.tool.*` metrics" in a way that read as the
+    library's total metric count. Corrected: four is this section's own
+    base call/duration metrics; twelve exist in total across cost/token
+    attribution (2), Agent Thrash Detection (5), and schema drift (1),
+    each already documented in their own sections.
+  - README's test count was stale at every point it was checked this
+    release; now 1017 tests, 1013 passing + 4 intentionally skipped.
+  - README's SigNoz metrics-wiring example described
+    `@opentelemetry/sdk-metrics` as a host-app dependency opentel-mcp
+    "doesn't bundle" — true before this release, no longer true now that
+    it's a real dependency (see "Changed" above).
+
+### CI
+
+- `dependency-audit` (`.github/workflows/ci.yml`) no longer audits this
+  monorepo's own shared, hoisted `node_modules` — `npm audit`, even with
+  `--omit=dev` and run from inside `packages/core/`, scans the entire
+  installed tree regardless of cwd or `--workspace` (confirmed
+  empirically), so it was reporting findings from `examples/*`'s real
+  `@modelcontextprotocol/sdk` dependency (express/hono/ajv transitives)
+  as if they were this library's own. Now packs and installs each of
+  `packages/core`/`packages/ui` into its own clean, throwaway project —
+  the exact tree a real `npm install` produces — and audits that instead.
+
+## 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