Align telemetry span attributes with MCP OTEL semantic conventions

[ChrisJBurns]

Summary

• Renames all telemetry span attributes to align with OpenTelemetry HTTP semantic conventions, MCP-specific conventions, and gen_ai namespace patterns
• Adds --otel-use-legacy-attributes CLI flag and config option for backward-compatible dual emission (emits both old and new attribute names simultaneously during migration)
• Updates span names to be more concise (e.g., mcp.tools/call → tools/call {tool_name})
• Fixes span status per OTEL spec: 4xx → Unset (client error, not server fault), 5xx → Error with error.type
• Adds new standard attributes: mcp.protocol.version, gen_ai.operation.name, network.protocol.name/version, client.address/port, mcp.session.id
• Includes migration guide (docs/telemetry-migration.md) with attribute mapping tables and PromQL examples

Attribute renames

Category	Old	New
HTTP	http.method	http.request.method
HTTP	http.url	url.full
HTTP	http.status_code	http.response.status_code
MCP	mcp.method	mcp.method.name
MCP	mcp.request.id	jsonrpc.request.id
MCP	mcp.transport	network.transport
Tool	mcp.tool.name	gen_ai.tool.name
Tool	mcp.tool.arguments	gen_ai.tool.call.arguments
Prompt	mcp.prompt.name	gen_ai.prompt.name

Full mapping in docs/telemetry-migration.md.

Backward compatibility

When --otel-use-legacy-attributes is enabled (or otel.use-legacy-attributes: true in config), every span includes both old and new attribute names. This allows gradual migration of dashboards and alerts.

Test plan

• All existing unit tests pass (task test)
• Lint passes with 0 issues (task lint)
• Build compiles cleanly (go build ./...)
• New dual emission tests verify both old+new attributes present when UseLegacyAttributes=true
• New dual emission tests verify only new attributes present when UseLegacyAttributes=false
• Integration tests verify end-to-end with real trace providers
• Helper function tests: mapTransport, httpProtocolVersion, parseRemoteAddr
• Manual verification with OTEL collector (recommended)

🤖 Generated with Claude Code

[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.

[codecov]

Codecov Report

❌ Patch coverage is 94.26230% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.35%. Comparing base (fa9e0bf) to head (0643d15).

Files with missing lines	Patch %	Lines
pkg/telemetry/middleware.go	94.26%	4 Missing and 3 partials ⚠️

Additional details and impacted files

@@                           Coverage Diff                           @@
##           otel/add-use-legacy-attributes-flag    #3727      +/-   ##
=======================================================================
+ Coverage                                66.30%   66.35%   +0.05%     
=======================================================================
  Files                                      427      427              
  Lines                                    41800    41888      +88     
=======================================================================
+ Hits                                     27714    27795      +81     
- Misses                                   11975    11979       +4     
- Partials                                  2111     2114       +3     

☔ 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.

[ChrisJBurns]

Superseded by the split PRs: #3729 (UseLegacyAttributes flag), #3734 (attribute rename + dual emission), #3735 (new attributes + span status fix).