DRAFT: Align telemetry middleware with MCP OTEL semantic conventions

[ChrisJBurns]

Summary

• Rename span attributes to match MCP OTEL spec (mcp.method.name, jsonrpc.request.id, gen_ai.tool.name, gen_ai.tool.call.arguments, gen_ai.prompt.name, network.transport)
• Update HTTP attributes to stable OTEL semantic conventions (http.request.method, url.full, http.response.status_code, etc.)
• Add standard metrics: mcp.server.operation.duration and mcp.server.session.duration histograms with spec-defined bucket boundaries
• Emit mcp.server.session.duration on HTTP DELETE session termination (per MCP streamable-http spec)
• Source session ID from Mcp-Session-Id HTTP header instead of JSON-RPC _meta
• Derive network.protocol.version from actual HTTP request instead of hardcoding per transport type
• Add session tracking with TTL-based cleanup to prevent memory leaks
• Update span naming to {method} {target} format (e.g., tools/call get_weather)
• Add error.type, client.address/client.port, gen_ai.operation.name attributes
• Map transport values to standard network.transport/network.protocol.name
• Propagate metric creation errors with warning log and no-op fallback
• Initialize tool call counter once at startup instead of per-request
• Unexport mcpOperationDurationBuckets (no external consumers)
• Remove non-standard http.duration_ms attribute (span timestamps capture duration)
• Add telemetry migration guide (docs/telemetry-migration.md) with attribute rename tables, PromQL examples, and migration checklist
• Remove duplicate mcp.resource.uri attribute for resources/read
• Replace hand-rolled contains() with slices.Contains() in tests
• Fix t.Parallel() on test that mutates env vars (//nolint:paralleltest,tparallel)

Addresses #3399.

PR Stack (2/3): #3682 (propagation) → This PR → #3684 (client spans)

Test plan

• Updated span name expectations in all tests
• Updated attribute name expectations (legacy → stable OTEL conventions)
• Added tests for standard mcp.server.operation.duration metric with correct attributes
• Added tests for session tracking and RecordSessionEnd
• Added tests for session end on HTTP DELETE (success and error cases)
• Added tests for mapTransport, parseRemoteAddr, httpProtocolVersion
• Updated integration test HTTP attribute assertions to stable names
• go build ./... passes
• go test ./pkg/telemetry/... passes
• task lint-fix passes with 0 issues

Screenshots

Traces in tempo/grafana

Metrics in Prometheus/Grafana

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 83.14607% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.30%. Comparing base (0761277) to head (65d3bd9).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/telemetry/middleware.go	83.14%	36 Missing and 9 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3683      +/-   ##
==========================================
+ Coverage   66.26%   66.30%   +0.03%     
==========================================
  Files         427      427              
  Lines       41765    41923     +158     
==========================================
+ Hits        27676    27795     +119     
- Misses      11977    12010      +33     
- Partials     2112     2118       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.