---
summary: Full OTel instrumentation for MCP prompts — spans, six new metrics, ATTR_MCP_PROMPT_* constants, active-requests gauge coverage
breaking: false
---

# 0.4.1 — 2026-04-19

Closes the OTel observability gap for MCP prompts. Tools and resources already had full instrumentation (span, counter, duration histogram, error counter, byte histograms); prompts only had a structured duration log. Prompts can now do meaningful work (conditional logic, async data fetches, multi-message assembly), so they get the same instrumentation depth. All three handler types are now symmetric.

## Added

- **Prompt OTel span** — `prompt_generation:{name}` with attributes `code.function.name`, `code.namespace=mcp-prompts`, `mcp.prompt.input_bytes`, `mcp.prompt.output_bytes`, `mcp.prompt.message_count`, `mcp.prompt.duration_ms`, `mcp.prompt.success`, and `mcp.prompt.error_code` (on failure).
- **Prompt OTel metrics** (#24) — six new instruments, eagerly initialized at startup via `initHandlerMetrics()`:
  - `mcp.prompt.generations` (Counter, `{generations}`)
  - `mcp.prompt.duration` (Histogram, `ms`)
  - `mcp.prompt.errors` (Counter, `{errors}`) — includes `mcp.prompt.error_category` dimension (`upstream`/`server`/`client`, matching tool instrumentation)
  - `mcp.prompt.input_bytes` (Histogram, `bytes`)
  - `mcp.prompt.output_bytes` (Histogram, `bytes`)
  - `mcp.prompt.message_count` (Histogram, `{messages}`)
- **`ATTR_MCP_PROMPT_*` constants** in `src/utils/telemetry/attributes.ts` — `NAME`, `INPUT_BYTES`, `OUTPUT_BYTES`, `MESSAGE_COUNT`, `DURATION_MS`, `SUCCESS`, `ERROR_CODE`, `ERROR_CATEGORY`.
- **Active-requests gauge includes prompts** — `mcp.requests.active` now covers tool, resource, and prompt handler executions. Gauge description updated accordingly.

## Changed

- **`measurePromptGeneration` signature** — accepts an optional third argument (`inputPayload: unknown`) for input-byte measurement. Backward-compatible (parameter is optional). `PromptRegistry.registerPrompt` now passes the validated args payload.
- **`performance.ts` fileoverview** — removed stale "Prompts get structured logs only" language; reflects new three-way symmetry.

## Tests

- **10 new test cases** in `tests/unit/utils/internal/performance.test.ts` mirroring the tool/resource suites: success metrics + returned messages, OTel counter + histogram on success, input/output/message-count histograms, OTel error counter + `logger.error` on failure, `McpError` code capture, generic (non-`McpError`) errors, active-requests gauge inc/dec, code namespace + function name span attributes, zero message count when generate returns a non-array.
- Full suite: 2239 passed / 10 skipped (pre-existing skips), 0 regressions.
