opentel-mcp 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 0.3.0
+
+### Added
+
+- OTel metrics, via `@opentelemetry/api`'s Metrics API only (no bundled
+  SDK/exporter — same host-app-provides-the-SDK pattern tracing already
+  uses):
+  - `mcp.tool.calls` (counter) — every tool call; `gen_ai.tool.name`,
+    `mcp.method.name`
+  - `mcp.tool.errors` (counter) — thrown/rejected handler; `gen_ai.tool.name`,
+    `error.type`
+  - `mcp.tool.silent_failures` (counter) — JSON-RPC succeeded but
+    `CallToolResult.isError === true`; `gen_ai.tool.name`
+  - `mcp.tool.duration` (histogram, unit `ms`) — call latency;
+    `gen_ai.tool.name`, `mcp.tool.outcome` (`success` | `error` |
+    `silent_failure`)
+  - `mcp.tool.silent_failures` fires from the same `isError` check that
+    marks the span ERROR — extracted into one shared `isToolResultError()`
+    helper in `src/instrument.js` so the detection logic isn't duplicated
+    between traces and metrics.
+  - Metrics are a zero-overhead no-op until the host application registers
+    a `MeterProvider` (default `@opentelemetry/api` behavior — not
+    special-cased here).
+- `enableMetrics` option (default `true`) to opt out of metric emission
+  without affecting tracing.
+
+### Naming note (no attribute rename)
+
+The tool-name attribute on all four new metrics is `gen_ai.tool.name`, not
+`mcp.tool.name` — the same spec-aligned name spans have used since v0.2's
+semantic-conventions pass (ADR 004). Traces and metrics were already
+consistent going into this release, so nothing was renamed here; this is
+called out because a naive read of the MCP semantic conventions might
+suggest a `mcp.tool.name` attribute, but the spec's actual server-span/
+metric attribute for this is `gen_ai.tool.name` (MCP tool calls are
+GenAI `execute_tool` calls under the hood — see `docs/adr/004-semantic-conventions-alignment.md`
+and `.spec-reference/mcp-semconv.md`). `mcp.method.name`, `error.type`,
+and `mcp.tool.argument_count` are unchanged. `mcp.tool.outcome` is a new
+custom (non-spec) attribute, documented in `src/attributes.js` alongside
+the other custom attribute.
+
+### Docs
+
+- README: new "Metrics" section (instrument table, `enableMetrics`, and a
+  `PeriodicExportingMetricReader` + OTLP/HTTP wiring example targeting
+  SigNoz's default local endpoint).
+- Roadmap updated to reflect metrics shipping in this release.
+
+## 0.2.0
+
+See git history — TypeScript declarations (`.d.ts`), workspace stripping
+for publish, and README documentation improvements.
+
+## 0.1.0
+
+Initial release: OTel tracing for MCP tool calls, including detection of
+`CallToolResult.isError: true` "silent failures" as `error.type: tool_error`
+span status.

package/README.md

@@ -1,18 +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.
+> 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
 
@@ -20,82 +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).
-
-## Quickstart (5-line usage)
-
-Works with either the low-level `Server` API:
+## 30-second quickstart
 
 ```js
-import { Server } from '@modelcontextprotocol/sdk/server/index.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';
 
-const server = new Server({ name: 'my-server', version: '1.0.0' }, {
-  capabilities: { tools: {} }
-});
+const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 
+// Wraps every tool registered below. Must run BEFORE server.tool() —
+// see "Ordering constraint" below for why.
 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
+  serviceName: 'my-mcp-server', // shows up on your traces
+  setupNodeSdk: true, // dev mode: prints traces to your terminal
 });
 
-// ...register tools as usual...
-server.setRequestHandler(CallToolRequestSchema, async (request) => { /*...*/ });
+// A normal tool, registered exactly as usual.
+server.tool('echo', { text: z.string() }, async ({ text }) => ({
+  content: [{ type: 'text', text: `you said: ${text}` }],
+}));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+That's it. Every tool call now emits a trace. Wire an exporter to see them
+(next section).
+
+## See it working
+
+Run the snippet above and this prints to your terminal — a real, captured
+run (full dump: `examples/hello-mcpserver/README.md`):
+
 ```
+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'
+}
+```
+
+No dashboard needed — `setupNodeSdk: true`'s dev exporter printed this
+directly. Point it at a real backend later; see "Two modes" below.
+
+---
+
+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.
 
-...or the high-level `McpServer` API most servers actually use:
+## Both server APIs
+
+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).
+
+**`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.
+
+**`Server`** — the low-level API, for when you're handling raw JSON-RPC
+yourself or building a library on top of MCP:
 
 ```js
-import { McpServer } from '@modelcontextprotocol/sdk/server/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 McpServer({ name: 'my-server', version: '1.0.0' });
+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,
+// 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.tool('my-tool', async (args) => { /*...*/ });
+const transport = new StdioServerTransport();
+await server.connect(transport);
 ```
 
-Either way, `instrumentMcpServer()` must run before any tool is
-registered — see "Ordering constraint" below.
+Runnable versions of both live in `examples/hello-server/` and
+`examples/hello-mcpserver/`.
 
-## Semantic conventions
+## What gets emitted
+
+### Tool-level failures, specifically
 
-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.
+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:
 
-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.
+```
+tools/call fetch_weather ................. 605ms   ERROR
+error.type = tool_error
+```
 
-## Span attributes emitted
+Verified in `test/instrument.test.js`'s "tool-level failure" tests.
 
-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.
+### Span attributes
+
+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 |
 |---|---|---|---|
@@ -107,31 +158,203 @@ 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`.
 
-## Two modes
+### Metrics
+
+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`.
+
+| 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`[^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';
+import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { instrumentMcpServer } from 'opentel-mcp';
+
+const resource = resourceFromAttributes({ 'service.name': 'my-mcp-server' });
 
-**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.
+const meterProvider = new MeterProvider({
+  resource,
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({ url: 'http://localhost:4318/v1/metrics' }),
+    }),
+  ],
+});
+metrics.setGlobalMeterProvider(meterProvider);
+
+const tracerProvider = new NodeTracerProvider({
+  resource,
+  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }))],
+});
+tracerProvider.register();
 
-**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`.
+const server = new Server({ name: 'my-server', version: '1.0.0' }, { capabilities: { tools: {} } });
+
+// 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 (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 |
+
+[^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
 
@@ -141,15 +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
 
-- v0.2: OTel metrics (`mcp.server.operation.duration`,
-  `mcp.server.session.duration`) alongside traces, plus opt-in
-  `gen_ai.tool.call.arguments` support with a redaction callback
-- v0.3: 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.2.0",
+  "version": "0.4.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -22,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"
   },
@@ -56,7 +59,9 @@
   },
   "devDependencies": {
     "@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/attributes.js

@@ -63,3 +63,25 @@ export const ATTR_MCP_TOOL_ARGUMENT_COUNT = 'mcp.tool.argument_count';
 
 export const ATTR_MCP_SERVER_NAME = 'mcp.server.name';
 export const ATTR_MCP_SERVER_VERSION = 'mcp.server.version';
+
+/**
+ * NOT part of the MCP semantic conventions. Our own addition, on the
+ * mcp.tool.duration histogram (see src/metrics.js): which of the three
+ * call outcomes a given duration measurement belongs to. The spec's
+ * mcp.server.operation.duration metric (not yet implemented here — see
+ * README roadmap) expresses failure only via error.type; this attribute
+ * additionally distinguishes "thrown/protocol error" from "silent failure"
+ * (isError: true) so both are visible on the same histogram without
+ * requiring a join against error.type, which silent failures don't set
+ * on the duration metric.
+ */
+export const ATTR_MCP_TOOL_OUTCOME = 'mcp.tool.outcome';
+
+/** Well-known mcp.tool.outcome value: the call succeeded. */
+export const MCP_TOOL_OUTCOME_SUCCESS = 'success';
+
+/** Well-known mcp.tool.outcome value: the handler threw or its promise rejected. */
+export const MCP_TOOL_OUTCOME_ERROR = 'error';
+
+/** Well-known mcp.tool.outcome value: isError: true (see ERROR_TYPE_TOOL_ERROR above). */
+export const MCP_TOOL_OUTCOME_SILENT_FAILURE = 'silent_failure';

package/src/config.js

@@ -16,12 +16,23 @@ import { diag } from '@opentelemetry/api';
  *   Only takes effect when `setupNodeSdk` is true.
  * @property {boolean} [enabled=true] - Set to false to disable instrumentation entirely; instrumentMcpServer()
  *   becomes a no-op.
+ * @property {boolean} [enableMetrics=true] - Set to false to disable the mcp.tool.* metrics (tracing is
+ *   unaffected). Metrics are already a zero-overhead no-op when no MeterProvider is registered — the default
+ *   @opentelemetry/api behavior — so this flag exists for opting out even when one *is* registered, not as a
+ *   substitute for that default.
  * @property {boolean} [setupNodeSdk=false] - When true, instrumentMcpServer() creates and registers its own
  *   NodeTracerProvider (always exporting to stderr — safe alongside stdio-transport MCP servers, see ADR 003;
  *   additionally to `exporterUrl` via OTLP/HTTP if set). When false (the default), spans are emitted via
  *   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
@@ -66,6 +77,8 @@ export function resolveOptions(options) {
     serviceName: opts.serviceName,
     exporterUrl: opts.exporterUrl,
     enabled: opts.enabled ?? true,
+    enableMetrics: opts.enableMetrics ?? true,
     setupNodeSdk,
+    fingerprinting: opts.fingerprinting ?? true,
   };
 }