API Telemetry

Overview

The framework auto-instruments every tool, resource, prompt, storage, LLM, speech, and graph call — each gets its own span and the standard counters/histograms. HTTP server requests pick up spans from HttpInstrumentation (all Node.js HTTP traffic, skips /healthz) plus httpInstrumentationMiddleware from @hono/otel on the MCP HTTP endpoint when installed (optional Tier 3 peer — bun add @hono/otel). On Bun, HttpInstrumentation silently no-ops and @hono/otel is the only HTTP coverage. Auth checks and session lifecycle are tracked as metrics only — auth decorates the active HTTP span with attributes, sessions emit counters.

requestId, traceId, and tenantId correlate automatically across spans, metrics, and logs. Framework log records carry traceId/spanId from the request context.

A handler's ctx.traceId / ctx.spanId name the execution span it runs in — tool_execution:<name> or resource_read:<name> — not the enclosing HTTP request span. Under HTTP the trace ID is the request's, so handler logs join to the request; the span ID is the child execution's, so they join to that span's attributes and duration. On stdio, where no transport span exists, both are still populated from the execution span the framework opens. Both are undefined when telemetry is disabled: the non-recording span a disabled pipeline produces carries all-zero IDs, and the framework reports no correlation rather than IDs that correlate to nothing.

For the helper API surface (withSpan, createCounter, createHistogram, buildTraceparent, etc.) — see the api-utils skill, Telemetry section. This skill is the catalog of what is emitted; that one is the reference for how to emit your own.

Enabling export

OTel is off by default. OTEL_ENABLED=true alone does nothing — you also need an OTLP endpoint. Without an endpoint the SDK is configured but nothing leaves the process.

Metrics push via PeriodicExportingMetricReader every 15 seconds. Traces use BatchSpanProcessor.

Traces and metrics endpoints resolve per the OTLP exporter spec: the signal-specific variable as-is, else the base plus the signal path. A signal with no resolved endpoint exports nothing, and NodeSDK's own OTEL_METRICS_EXPORTER / OTEL_LOGS_EXPORTER defaults are not consulted.

Log records export only when OTEL_EXPORTER_OTLP_LOGS_ENDPOINT is set. The base endpoint alone never turns it on, so a deployment exporting traces and metrics keeps its logs local until it opts in. When set, every record the framework logger writes — after the MCP_LOG_LEVEL filter and the rate limit, with the same field redaction as the pino output — is also sent through a BatchLogRecordProcessor, with its MCP level as the severity and the active span's trace context (a handler's ctx.log record joins its tool_execution:* span). interactions.log transcripts are never exported. Log export needs three more optional peers: bun add @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/api-logs.

Runtime support

Cloud platform detection auto-populates resource attributes:

Flush at exit

Spans batch and metrics push on a 15-second cycle, so a process that exits between cycles takes its telemetry with it. ServerHandle.shutdown() is the drain: it stops the transport, runs the teardown hook, then force-flushes traces and metrics through the OTLP exporters and closes the logger.

A failed flush is logged as a warning and the logger still closes, so the final log lines survive. The usual cause is an exporter that can't reach its collector and hits the 5 s OTel shutdown ceiling.

A signal ends the process. Every exit-bearing path runs the cleanup exactly once — shutdown detaches the signal handlers and the EOF watcher as it starts, so neither can re-enter it — and then exits explicitly instead of waiting to run out of handles. Two things follow: the OTLP export leaves the process, and a handle registered outside framework teardown (a recursive fs.watch, a setInterval without unref()) can no longer keep the server resident. A second signal arriving mid-shutdown reaches no handler, so the default disposition terminates immediately — the operator's force-kill escape hatch. Neither path writes to stdout.

The drain is bounded. Shutdown-on-exit races a 10-second backstop that bounds the shutdown as a whole, not any single await: a step that settles inside the ceiling is never truncated, and only one that never settles is cut. A signal cut exits 1 after a warning naming that step; a stdin-EOF cut exits 0 without one. The logger bounds its own flush separately, per pino instance: a completing callback is awaited in full, and a runtime whose callback never arrives releases shutdown rather than hanging it.

Release what the framework cannot see. createApp({ teardown }) is the setup counterpart: it runs after the transport stops and before the logger closes, on every shutdown path, with CoreServices still alive. Close a watcher, socket, or poller there rather than leaving it for the backstop, which cuts a ref'd handle rather than closing it. An error it raises is logged and never blocks the exit; a hook that never settles is what the ceiling then bounds. Node/Bun only — createWorkerHandler does not accept it.

Workers has no ServerHandle and no NodeSDK — flush whatever exporter you wired there yourself, via ctx.waitUntil().

Spans

Every handler call gets a span. Nested operations (storage, graph, LLM) become child spans on the same trace. All spans carry code.function.name and code.namespace for code-attribution. Errors are recorded via span.recordException() and SpanStatusCode.ERROR; McpError codes surface as the *.error_code attribute.

A handler that ends its round with ctx.requestInput(...) closes its span OK with mcp.*.input_required set — no recorded exception, no error-counter increment. Multi-round-trip input is protocol control flow, so it never inflates error rates; split on that attribute to tell an incomplete round from a completed call.

The measured region

A tool or resource call is measured from the start of the handler through the response pipeline that follows it: output-schema validation, format(), the enrichment merge, and the trailer render for tools; output-schema validation and format() for resources. Telemetry therefore records the outcome the client sees — a failure in any of those is an ERROR span, success=false counters, an error-counter increment, and isSuccess: false in the completion log, matching the isError: true the caller receives. Prompt generation has no post-handler pipeline, so its region is the generate function alone.

Two consequences worth knowing when reading a dashboard:

mcp.tool.partial_success and the mcp.tool.batch.* counts read the same domain value, so a batch envelope ({ succeeded, failed }) is still detected once the result has been assembled around it. For an output built with partialResultSchema(), the arrays are read under its failedKey/succeededKey, resolved once per definition from the output schema.

Trace context propagates across boundaries via W3C traceparent headers. See api-utils → telemetry/trace for withSpan, buildTraceparent, extractTraceparent, createContextWithParentTrace, injectCurrentContextInto, runInContext signatures.

Metrics

All custom metrics are namespaced mcp.* (or process.* / http.client.* where standard semconv applies). Lazy-initialized on first emission; tool, resource, prompt, http.client.request.duration, heartbeat, session, auth, rate-limit, and error metrics are eagerly created at startup so series exist from the first export cycle. LLM, speech, graph, and storage instruments are lazy-initialized on first use.

Tools, resources, prompts

Rejections and cancellations. A call refused before the handler runs — argument validation (-32602) or the inline auth check (-32005 missing scope, -32006 no auth context) — never reaches the measured region, so it is absent from mcp.tool.calls, mcp.tool.duration, and mcp.tool.errors and counts once on mcp.tool.rejections instead, labelled with the code and category the caller received. mcp.tool.outcome separates a caller hang-up from a failure: cancelled for a RequestCancelled (-32011, always paired with error_category="client"), error for any other failure, ok for a success or an input_required round. mcp.tool.success and error_category keep their meaning, so existing sum() queries are unchanged. An error rate that excludes hang-ups filters on mcp.tool.outcome!="cancelled"; the failure rate a caller sees is (errors + rejections) / (calls + rejections). Resources and prompts carry neither split.

The three mcp.input.* counters are the pre-validation step's metrics. Each marks a call the strict input schema would otherwise have rejected: a key rewritten to its canonical spelling, a client-added root key dropped, or a value repaired after the parse failed — a stringified array or object, or an integer sent for a string. mcp.input.coerced adds one per repaired call per kind, not per repaired value: a call repairing an array and an object adds one to each mcp.input.coercion series, and a call repairing three arrays adds one. A call the step rescues carries nothing about it in its response, so a client artifact spreading across a fleet shows up here first. The counters describe the arguments the handler receives: when a call is retried with the alias stage first (see add-tool), the key the retry rewrote counts on mcp.input.aliased and never also on mcp.input.ignored_key, and a rejected call counts the attempt its rejection reports — the retry's when it ran. The counters are not the only record: every stage writes a debug log naming the key or the repair kinds, the opt-in failure-payload record (below) keeps a failed call's arguments as the caller sent them, and a rejected call reports its rewrites and underscore-rule drops to the caller as data.input (see api-errors). All three are lazy: a server whose callers never trip a stage emits no series at all.

Every label is author- or framework-defined — the caller's own key text is never one. mcp.input.ignore_rule is the ignore-list entry that matched or the fixed underscore_prefix, bounded by the list's length plus one. mcp.input.aliased is labelled by the canonical mcp.input.target (a declared property of the tool) and mcp.input.alias_kind, not by the alias the caller sent — the case-style half accepts every -/_/case permutation of a declared key, so labelling the alias would put a caller-controlled set on a permanent series. That is the unbounded-label leak removed from the rate-limiter counter in 0.9.0: a metric attribute set lives until process restart, so anything the caller names belongs on a span or in a log, never on a counter.

To find the raw key, read the debug log, which carries ignoredKey / alias alongside the bounded rule and target. The counter tells you a client artifact exists and how often; the log tells you what it is called, which is what you need before extending input.ignoreKeys, declaring an inputAliases entry, or renaming a parameter.