opentel-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,19 +1,30 @@
 # opentel-mcp
 
-> OpenTelemetry instrumentation for Model Context Protocol (MCP) servers.
-> One-line visibility into which tools your AI agent is calling, how
-> long they take, and which ones fail — via standard OTel traces and
-> metrics.
+> Turn every MCP tool call into an OpenTelemetry trace — including the
+> failures your logs won't show you.
 
 [![CI](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/opentel-mcp.svg)](https://www.npmjs.com/package/opentel-mcp)
+[![node](https://img.shields.io/node/v/opentel-mcp.svg)](https://www.npmjs.com/package/opentel-mcp)
 [![license](https://img.shields.io/npm/l/opentel-mcp.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/blob/main/LICENSE)
 
-## Status
+opentel-mcp watches every tool call your MCP (Model Context Protocol)
+server handles: which tool ran, how long it took, and whether it worked.
+It reports that as OpenTelemetry (OTel) traces — the standard most
+dashboards already read. One function call; no changes to your tools'
+code.
 
-`0.x` — the [MCP semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)
-this library implements are Development-stage and may change. Breaking
-attribute changes will land in minor versions until `1.0`.
+## The problem
+
+Your AI agent calls 15 MCP tools across 3 servers this turn. One tool
+returns `{ isError: true }` inside an otherwise-successful response — how
+a tool reports "I couldn't do that" without crashing. Your logs show
+success. Your metrics show success. The agent gives a wrong answer, and
+nothing you're monitoring says why.
+
+opentel-mcp makes that failure visible: one span per tool call, marked as
+an error when it actually is one, using the same standard your dashboards
+already speak.
 
 ## Install
 
@@ -21,141 +32,121 @@ attribute changes will land in minor versions until `1.0`.
 npm install opentel-mcp @opentelemetry/api
 ```
 
-`opentel-mcp` is an ES module. Your project needs `"type": "module"` in
-its package.json, or you must use `.mjs` file extensions.
-
-## Why
+opentel-mcp is an ES module — add `"type": "module"` to package.json.
 
-When Claude Code calls 15 MCP tools across 3 servers, you have zero
-visibility into which was slow, which errored silently, which sequence
-ran. opentel-mcp wraps any MCP server and emits one OTel span per tool
-invocation with rich attributes, using standard OpenTelemetry APIs so
-it plugs into your existing observability stack (Jaeger, Grafana Tempo,
-Honeycomb, Datadog, whatever).
+## 30-second quickstart
 
-## What you get
+```js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { instrumentMcpServer } from 'opentel-mcp';
+import { z } from 'zod';
 
-MCP tool calls are invisible by default. When an agent turn takes 2.5
-seconds, you have no idea which tool caused it. opentel-mcp turns every
-tool call into an OpenTelemetry span you can read.
+const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 
-### Example trace
+// Wraps every tool registered below. Must run BEFORE server.tool() —
+// see "Ordering constraint" below for why.
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server', // shows up on your traces
+  setupNodeSdk: true, // dev mode: prints traces to your terminal
+});
 
-One agent turn, captured in Jaeger (spans generated by opentel-mcp,
-exported over OTLP):
+// A normal tool, registered exactly as usual.
+server.tool('echo', { text: z.string() }, async ({ text }) => ({
+  content: [{ type: 'text', text: `you said: ${text}` }],
+}));
 
-```
-agent_turn ............................. 2470ms   OK
-├─ tools/call search_documents ........... 46ms   OK
-├─ tools/call fetch_weather ............. 601ms   OK
-└─ tools/call generate_advice .......... 1802ms   OK   ← the bottleneck
+const transport = new StdioServerTransport();
+await server.connect(transport);
 ```
 
-Without tracing you'd know only that the turn took ~2.5s. With it, the
-waterfall shows `generate_advice` is where the time goes —
-`search_documents` and `fetch_weather` are cheap by comparison. That's
-the difference between guessing and knowing.
+That's it. Every tool call now emits a trace. Wire an exporter to see them
+(next section).
 
-### Tool-level failures
+## See it working
 
-An MCP tool can fail two ways: it can throw, or it can return
-`isError: true` on an otherwise-successful response. The second is how a
-tool reports a failure to the agent without crashing the server — and
-most instrumentation records it as a success, because the call
-technically succeeded.
-
-opentel-mcp catches it:
+Run the snippet above and this prints to your terminal — a real, captured
+run (full dump: `examples/hello-mcpserver/README.md`):
 
 ```
-tools/call fetch_weather ................. 605ms   ERROR
-error.type = tool_error
+name: 'tools/call echo'
+kind: 1                    // SpanKind.SERVER
+status: { code: 1 }        // OK
+attributes: {
+  'mcp.method.name': 'tools/call',
+  'gen_ai.tool.name': 'echo',
+  'mcp.tool.argument_count': 1,
+  'jsonrpc.request.id': '1'
+}
 ```
 
-The span is marked ERROR with `error.type = tool_error`, the result is
-returned to the agent unchanged, and nothing is thrown. Your error rate
-reflects reality instead of reading as a flat 100% success.
+No dashboard needed — `setupNodeSdk: true`'s dev exporter printed this
+directly. Point it at a real backend later; see "Two modes" below.
 
-### Span attributes
+---
 
-Every span follows the OpenTelemetry MCP semantic conventions, so it
-drops into existing dashboards (Jaeger, Grafana Tempo, Honeycomb, SigNoz)
-with no custom mapping:
+The rest of this README goes deeper: both server APIs, every attribute
+and metric emitted, how failure grouping works, configuration, and the
+non-obvious design decisions behind each.
 
-| Attribute | Example value |
-|---|---|
-| `mcp.method.name` | `tools/call` |
-| `gen_ai.tool.name` | `generate_advice` |
-| `gen_ai.operation.name` | `execute_tool` |
-| `jsonrpc.request.id` | `3` |
-| `mcp.tool.argument_count` | `2` |
+## Both server APIs
 
-Span name follows the spec's `{method} {target}` form (e.g.
-`tools/call generate_advice`), and span kind is `SERVER`.
+MCP servers are built on one of two classes from `@modelcontextprotocol/sdk`;
+opentel-mcp detects and wraps either one the same way (see ADR 001 in
+`docs/adr/` for how).
 
-## Quickstart (5-line usage)
+**`McpServer`** — the high-level API most servers are actually built on.
+Use it unless you have a specific reason not to; this is what the
+quickstart above uses.
 
-Works with either the low-level `Server` API:
+**`Server`** — the low-level API, for when you're handling raw JSON-RPC
+yourself or building a library on top of MCP:
 
 ```js
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { instrumentMcpServer } from 'opentel-mcp';
 
-const server = new Server({ name: 'my-server', version: '1.0.0' }, {
-  capabilities: { tools: {} }
-});
+const server = new Server({ name: 'my-server', version: '1.0.0' }, { capabilities: { tools: {} } });
 
-instrumentMcpServer(server, {
-  serviceName: 'my-mcp-server', // required because setupNodeSdk is true below
-  setupNodeSdk: true,  // dev-friendly stderr output; omit in prod
-                        // if you already have OTel configured
+// Must run before setRequestHandler(CallToolRequestSchema, ...) below.
+instrumentMcpServer(server, { serviceName: 'my-mcp-server', setupNodeSdk: true });
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { text } = request.params.arguments ?? {};
+  return { content: [{ type: 'text', text: `you said: ${text}` }] };
 });
 
-// ...register tools as usual...
-server.setRequestHandler(CallToolRequestSchema, async (request) => { /*...*/ });
+const transport = new StdioServerTransport();
+await server.connect(transport);
 ```
 
-...or the high-level `McpServer` API most servers actually use:
+Runnable versions of both live in `examples/hello-server/` and
+`examples/hello-mcpserver/`.
 
-```js
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { instrumentMcpServer } from 'opentel-mcp';
+## What gets emitted
 
-const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+### Tool-level failures, specifically
 
-instrumentMcpServer(server, {
-  serviceName: 'my-mcp-server', // required because setupNodeSdk is true below
-  setupNodeSdk: true,
-});
+An MCP tool can fail two ways: it can throw, or it can return
+`isError: true` on an otherwise-successful response (the case from "The
+problem" above). opentel-mcp treats both the same way — span marked
+`ERROR`, nothing thrown, the result returned to the caller unchanged:
 
-// ...register tools as usual...
-server.tool('my-tool', async (args) => { /*...*/ });
+```
+tools/call fetch_weather ................. 605ms   ERROR
+error.type = tool_error
 ```
 
-Either way, `instrumentMcpServer()` must run before any tool is
-registered — see "Ordering constraint" below.
-
-## Semantic conventions
-
-opentel-mcp follows the [MCP semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)
-published by the OTel GenAI SIG (they moved there from the main
-`semantic-conventions` repo, where the MCP conventions are now marked
-deprecated). **That spec's status is Development, not Stable** — attribute
-names and requirement levels may still change upstream, and this package
-will follow suit when they do. See ADR 004 in `docs/adr/` for the full
-reasoning.
-
-One attribute, `mcp.tool.argument_count`, is **not** part of the spec — it's
-our own addition, documented as such in `src/attributes.js`. It's a
-privacy-preserving alternative to the spec's opt-in
-`gen_ai.tool.call.arguments`: it gives shape/anomaly signal (argument count
-changed) without capturing any argument values.
+Verified in `test/instrument.test.js`'s "tool-level failure" tests.
 
-## Span attributes emitted
+### Span attributes
 
-Span (server-side `tools/call` handling) follows the spec's MCP server
-span: name `{mcp.method.name} {tool name}` (e.g. `tools/call echo`, falling
-back to just `mcp.method.name` when no tool name is available), kind
-`SERVER`, status `ERROR` whenever `error.type` is set.
+Every span follows the OpenTelemetry MCP semantic conventions (see
+"Semantic conventions" below), name `{mcp.method.name} {tool name}`
+(e.g. `tools/call echo`), kind `SERVER`, status `ERROR` whenever
+`error.type` is set.
 
 | Attribute | Requirement Level | Description | Example |
 |---|---|---|---|
@@ -167,46 +158,33 @@ back to just `mcp.method.name` when no tool name is available), kind
 | mcp.tool.argument_count | **Custom — not spec** | Number of arguments (values not captured) | 2 |
 
 Span status description carries the error message on failure (thrown
-errors); no separate error-message attribute is emitted — the spec
-expresses success/failure through span status, not a status attribute.
+errors); there's no separate error-message attribute — the spec expresses
+success/failure through span status, not an attribute. Source of truth:
+`src/attributes.js`.
 
-## Metrics
+### Metrics
 
-Alongside spans, opentel-mcp emits four `mcp.tool.*` metrics via
-`@opentelemetry/api`'s Metrics API — same API-only pattern as tracing (see
-"Two modes" below): no SDK or exporter is bundled, and recording is a
-zero-overhead no-op until the host application registers a
-`MeterProvider`. Set `enableMetrics: false` to opt out even when one is
-registered; tracing is unaffected either way.
+Four `mcp.tool.*` metrics via `@opentelemetry/api`'s Metrics API — same
+API-only pattern as tracing (see "Two modes" below): nothing is recorded
+until a `MeterProvider` is registered. Set `enableMetrics: false` to opt
+out even when one is; tracing is unaffected either way. Source of truth:
+`src/metrics.js`.
 
-| Instrument | Type | Unit | Attributes | Emitted when |
+| Metric | Type | Unit | Attributes | Emitted when |
 |---|---|---|---|---|
 | `mcp.tool.calls` | Counter | — | `gen_ai.tool.name`, `mcp.method.name` | Every tool call |
-| `mcp.tool.errors` | Counter | — | `gen_ai.tool.name`, `error.type` | The handler threw or its promise rejected |
-| `mcp.tool.silent_failures` | Counter | — | `gen_ai.tool.name` | The JSON-RPC response succeeded but `CallToolResult.isError` was `true` |
-| `mcp.tool.duration` | Histogram | `ms` | `gen_ai.tool.name`, `mcp.tool.outcome` (`success` \| `error` \| `silent_failure`) | Every tool call, on completion |
-
-`mcp.tool.silent_failures` is incremented from the exact same `isError`
-check that marks the span ERROR (see `isToolResultError()` in
-`src/instrument.js`) — the detection logic isn't duplicated between traces
-and metrics. `gen_ai.tool.name`, `mcp.method.name`, and `error.type` are
-the same spec-aligned attribute names the spans already use (see "Span
-attributes emitted" above); `mcp.tool.outcome` is a custom (non-spec)
-attribute, documented in `src/attributes.js`, that lets a single duration
-histogram distinguish thrown/protocol errors from silent failures without
-joining against `error.type`, which silent failures don't set on this
-metric.
-
-### Wiring a MeterProvider and TracerProvider (example: SigNoz)
-
-opentel-mcp never creates a `MeterProvider` itself (except the stderr/dev
-`setupNodeSdk: true` tracing path, which doesn't touch metrics) — register
-one the same way you would for any OTel-instrumented Node app, before
-calling `instrumentMcpServer()`. The same is true of the `TracerProvider`
-in bring-your-own-SDK mode (`setupNodeSdk: false`, the default): without
-registering one, `trace.getTracer()` inside opentel-mcp resolves to the
-`@opentelemetry/api` no-op default and spans are silently dropped, even
-though `mcp.tool.*` metrics keep flowing:
+| `mcp.tool.errors` | Counter | — | `gen_ai.tool.name`, `error.type`[^1] | Handler threw or rejected |
+| `mcp.tool.silent_failures` | Counter | — | `gen_ai.tool.name`[^1] | Result had `isError: true` |
+| `mcp.tool.duration` | Histogram | ms | `gen_ai.tool.name`, `mcp.tool.outcome`[^1] | Every call, completion |
+
+[^1]: Also carries `mcp.failure.category` when fingerprinting finds one — see "Failure Fingerprinting" below.
+
+`mcp.tool.silent_failures` increments from the exact same check that marks
+the span `ERROR` (`isToolResultError()` in `src/instrument.js`) — the
+detection logic isn't duplicated between traces and metrics.
+
+Wiring a real `MeterProvider`/`TracerProvider` — a worked example against
+SigNoz's local OTLP endpoint:
 
 ```js
 import { metrics, trace } from '@opentelemetry/api';
@@ -236,51 +214,147 @@ const tracerProvider = new NodeTracerProvider({
 });
 tracerProvider.register();
 
-const server = new Server({ name: 'my-server', version: '1.0.0' }, {
-  capabilities: { tools: {} },
-});
+const server = new Server({ name: 'my-server', version: '1.0.0' }, { capabilities: { tools: {} } });
 
-instrumentMcpServer(server, {
-  // setupNodeSdk: false (default) — this example brings its own SDK for
-  // both signals: the MeterProvider above for metrics, and the
-  // NodeTracerProvider above — registered globally via
-  // tracerProvider.register(), which is what trace.getTracer() picks up —
-  // for traces.
-});
+// setupNodeSdk: false (default) — both providers above are already
+// registered globally, so instrumentMcpServer() picks them up as-is.
+instrumentMcpServer(server, {});
 ```
 
-`http://localhost:4318` is SigNoz's default local OTLP/HTTP endpoint (both
-`/v1/metrics` and `/v1/traces`); point it at your collector/SigNoz
-ingestion endpoint in production. `@opentelemetry/sdk-metrics` and
-`@opentelemetry/exporter-metrics-otlp-http` are peer/host-app
-dependencies — opentel-mcp doesn't bundle them (see the peerDependencies
-note in `package.json`). `@opentelemetry/sdk-trace-node` and
-`@opentelemetry/exporter-trace-otlp-http`, by contrast, are already
-runtime dependencies of opentel-mcp itself (used by its `setupNodeSdk: true`
-dev path), so no extra install is needed to use them here.
-
-## Two modes
-
-**One-line (dev):** `setupNodeSdk: true` sets up a NodeTracerProvider
-that prints spans to stderr (safe alongside stdio-transport MCP servers —
-see ADR 003), optionally + an OTLP exporter if `exporterUrl` is provided.
-No separate OTel SDK setup needed — `serviceName` is required in this
-mode, since it names the resource of the provider opentel-mcp creates.
+`http://localhost:4318` is SigNoz's default local OTLP/HTTP (OpenTelemetry
+Protocol — the wire format traces/metrics travel over) endpoint; point it
+at your own collector in production. `@opentelemetry/sdk-metrics` and
+`@opentelemetry/exporter-metrics-otlp-http` are host-app dependencies —
+opentel-mcp doesn't bundle them (see `package.json`'s `peerDependencies`).
+`@opentelemetry/sdk-trace-node` and `@opentelemetry/exporter-trace-otlp-http`
+are already runtime dependencies of opentel-mcp itself (its `setupNodeSdk:
+true` dev path uses them), so no extra install is needed for those two.
+
+## Failure Fingerprinting (v0.4.0+)
+
+Groups logically identical failures under one stable identifier, even
+when the error message contains UUIDs, timestamps, or user IDs. Ten
+calls that fail the same way but each mention a different user ID show
+up as **one** issue, not ten.
+
+Runs locally and synchronously over the error object already in hand —
+no network call, no third-party service. Every thrown error and every
+`isError: true` result gets one, automatically; disable with
+`{ fingerprinting: false }` (default: enabled). Full algorithm: ADR 006
+in `docs/adr/`.
+
+| Attribute | Description | Example |
+|---|---|---|
+| mcp.failure.fingerprint | Stable 16-hex-char identity for the failure | "a3f4c8e2b1d09f77" |
+| mcp.failure.signature | Human-readable `errorClass@fn:line`, ≤60 chars | "TypeError@doThing:42" |
+| mcp.failure.category | One of 8 categories (below) | "timeout" |
+| mcp.failure.origin | `tool_error` \| `thrown` \| `transport` | "thrown" |
+| mcp.failure.error_class | Error class / constructor name | "TypeError" |
+
+Source of truth: `src/fingerprint/attributes.js`. Every category:
+
+- `validation` — bad input (Zod/Joi/Yup errors, "invalid"/"required" wording)
+- `timeout` — an operation timed out (`TimeoutError`, `ETIMEDOUT`, ...)
+- `network` — a connection failed (`ECONNREFUSED`, `FetchError`, ...)
+- `auth` — 401/403, "unauthorized"/"forbidden" wording
+- `dependency` — a downstream service or package failed (Mongo, Postgres, ...)
+- `serialization` — malformed JSON, "unexpected token" wording
+- `internal` — nothing more specific matched (the catch-all)
+- `unknown` — fingerprinting itself hit an internal error (should not normally happen)
+
+Full classifier source: `src/fingerprint/classify/`.
+
+**Cardinality:** the fingerprint itself is unbounded — a new bug means a
+new fingerprint, forever. That's fine on span attributes (each span is
+its own record), but it must **never** go on a metric label, or every
+distinct failure becomes its own permanent time series. opentel-mcp
+enforces this structurally, not by convention: `src/metrics.js` can only
+reach a fingerprint-derived value through
+`METRIC_SAFE_ATTRIBUTES` — a frozen list containing only `category` and
+`origin` (24 combinations max). There is no code path today that could
+accidentally attach `fingerprint`, `signature`, or `error_class` to a
+counter or histogram label. See `src/fingerprint/attributes.js` and ADR
+006's "Consequences" section.
+
+**Extending it:** `computeFingerprint(err, ctx, opts)`
+(`src/fingerprint/compose.js`) accepts `opts.classifiers` to prepend your
+own detection rules ahead of the built-in eight, and `opts.stackFrames` to
+change how many stack frames feed the signature — see
+`test/fingerprint/compose.test.js`'s "uses a custom classifiers list" and
+"respects a custom opts.stackFrames count" tests, and
+`examples/fingerprint-demo.js` for a runnable, standalone demo (`node
+examples/fingerprint-demo.js`). Not yet wired through
+`instrumentMcpServer()`'s own options — today this means importing
+`computeFingerprint` directly rather than configuring the automatic
+per-call-site wrapping; tracked in the roadmap below.
+
+## Configuration
+
+All options passed to `instrumentMcpServer(server, options)`. Source of
+truth: `src/config.js`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `serviceName` | string | — | Resource name for traces[^2] |
+| `setupNodeSdk` | boolean | `false` | Dev mode: stderr tracer, no setup[^3] |
+| `exporterUrl` | string | — | OTLP/HTTP traces endpoint[^4] |
+| `enabled` | boolean | `true` | `false` disables all instrumentation |
+| `enableMetrics` | boolean | `true` | `false` disables `mcp.tool.*` metrics only |
+| `fingerprinting` | boolean | `true` | `false` disables `mcp.failure.*` attributes |
 
-**Bring-your-own-SDK (prod):** Omit `setupNodeSdk` (default false).
-opentel-mcp uses whatever tracer provider you've already registered
-via `trace.setGlobalTracerProvider()`. This means it plugs into any
-existing OTel setup without conflict. In this mode the host's
-TracerProvider owns the resource, so `serviceName` is not needed and has
-no effect — set `service.name` on the host's Resource instead. Passing
-`serviceName` anyway is harmless but logs a one-time `diag.warn`.
+[^2]: Required only when `setupNodeSdk` is `true`. Has no effect otherwise — the host app's registered `TracerProvider` owns the resource; passing it anyway logs a one-time `diag.warn`.
+[^3]: Creates and registers a `NodeTracerProvider` that always prints to stderr (safe alongside stdio-transport servers — ADR 003), additionally exporting via OTLP/HTTP if `exporterUrl` is set.
+[^4]: Only takes effect when `setupNodeSdk` is `true`.
 
 ## Ordering constraint
 
-Call `instrumentMcpServer()` BEFORE registering any tool handlers —
+Instrumentation works by wrapping the tool-call handler at the moment
+it's registered. If a handler is registered before `instrumentMcpServer()`
+runs, that handler was never wrapped — it slipped past the trap before it
+was set.
+
+Call `instrumentMcpServer()` **before** registering any tool handlers —
 before `server.setRequestHandler(CallToolRequestSchema, ...)` (low-level
 `Server`) or before any `.tool()`/`.registerTool()` call (`McpServer`).
-See ADR 002 in docs/adr/ for why.
+See ADR 002 in `docs/adr/` for the detection logic that catches violations
+of this at instrument time.
+
+## Two modes
+
+### Quick dev setup
+
+`setupNodeSdk: true` sets up a `NodeTracerProvider` that prints spans to
+stderr (safe alongside stdio-transport MCP servers — see ADR 003),
+optionally plus an OTLP exporter if `exporterUrl` is provided. No separate
+OTel SDK setup needed — `serviceName` is required in this mode, since it
+names the resource of the provider opentel-mcp creates.
+
+### Production setup
+
+Omit `setupNodeSdk` (default `false`). opentel-mcp uses whatever
+`TracerProvider` is already registered via
+`trace.setGlobalTracerProvider()`, so it plugs into any existing OTel
+setup without conflict. The host's `TracerProvider` owns the resource
+here, so `serviceName` is not needed and has no effect — set
+`service.name` on the host's `Resource` instead. Passing `serviceName`
+anyway is harmless but logs a one-time `diag.warn`.
+
+## Semantic conventions
+
+`0.x` — the [MCP semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)
+this library implements are Development-stage, not Stable, and may still
+change upstream; breaking attribute renames will land in minor versions
+until `1.0`, tracked in release notes rather than silently shipped.
+
+opentel-mcp follows those conventions (published by the OTel GenAI SIG,
+moved there from the main `semantic-conventions` repo, where the MCP
+conventions are now deprecated) for everything they define, and adds two
+namespaces of its own where they don't yet: `mcp.tool.*` (call-count and
+duration metrics) and `mcp.failure.*` (failure fingerprinting). Both are
+documented as non-spec at every attribute (`src/attributes.js`,
+`src/fingerprint/attributes.js`), and are candidates to fold into the
+spec's own metrics/error vocabulary if it grows an equivalent. Full
+reasoning: ADR 004 in `docs/adr/`.
 
 ## Compatibility
 
@@ -290,16 +364,24 @@ See ADR 002 in docs/adr/ for why.
 - Supports both low-level `Server` and high-level `McpServer` APIs
 - @modelcontextprotocol/sdk ^1.0.0
 - @opentelemetry/api ^1.9.0
+- 127 tests (`npm test`) — see `test/`
 
 ## Roadmap
 
-- Shipped in v0.3: `mcp.tool.*` metrics (see "Metrics" above). Opt-in
-  `gen_ai.tool.call.arguments` support with a redaction callback, and the
-  spec's own `mcp.server.operation.duration` / `mcp.server.session.duration`
-  metrics, remain unimplemented — tracked here, not silently dropped.
-- Next: W3C trace context propagation via `params._meta` per
-  [SEP-414](https://modelcontextprotocol.io/community/seps/414-request-meta),
-  plus client-side instrumentation, so a single trace can span the client
+- v0.4: Deep Failure Fingerprinting ✓ — see "Failure Fingerprinting" above
+  and ADR 006.
+- v0.5: Failure clustering + regression detection
+- Future: recovery hints, root-cause chaining across parent spans,
+  alignment with the OTel GenAI SIG's MCP semantic conventions when
+  published
+- Also still tracked, not silently dropped: exposing `computeFingerprint`'s
+  `classifiers`/`stackFrames` options through `instrumentMcpServer()`
+  itself; opt-in `gen_ai.tool.call.arguments` support with a redaction
+  callback; the spec's own `mcp.server.operation.duration` /
+  `mcp.server.session.duration` metrics; W3C trace context propagation via
+  `params._meta` per
+  [SEP-414](https://modelcontextprotocol.io/community/seps/414-request-meta);
+  and client-side instrumentation, so a single trace can span the client
   call and the server's tool execution
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -23,6 +23,8 @@
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "bench": "vitest bench --run",
     "prepack": "node scripts/strip-workspaces.js",
     "postpack": "node scripts/restore-workspaces.js"
   },
@@ -59,6 +61,7 @@
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "@vitest/coverage-v8": "^2.1.9",
     "typescript": "^7.0.2",
     "vitest": "^2.1.8"
   }

package/src/config.js

@@ -26,6 +26,13 @@ import { diag } from '@opentelemetry/api';
  *   whatever OpenTelemetry TracerProvider the host application
  *   has already registered globally — or dropped silently if none has been registered. This default keeps
  *   instrumentMcpServer() from ever overriding a host application's own OpenTelemetry setup.
+ * @property {boolean} [fingerprinting=true] - Set to false to disable deep-failure fingerprinting. When enabled
+ *   (the default), every thrown error and tool-level failure (isError: true) is run through
+ *   src/fingerprint/compose.js's computeFingerprint(), adding mcp.failure.* span attributes and an
+ *   mcp.failure.category attribute on the mcp.tool.errors / mcp.tool.silent_failures / mcp.tool.duration
+ *   metrics (see src/fingerprint/attributes.js). computeFingerprint() never throws, so this only trades a
+ *   small amount of per-failure CPU (see the p99 < 200µs budget in test/fingerprint/benchmark.test.js) for
+ *   fingerprinting.
  */
 
 // Guards the "serviceName has no effect" diagnostic below so it fires once
@@ -72,5 +79,6 @@ export function resolveOptions(options) {
     enabled: opts.enabled ?? true,
     enableMetrics: opts.enableMetrics ?? true,
     setupNodeSdk,
+    fingerprinting: opts.fingerprinting ?? true,
   };
 }