Improve OTel GenAI span semantics and DIFC/rate-limit milestone visibility

[Copilot]

This addresses gaps from the OTel module review: mcp.tool_call spans were missing key GenAI semconv attributes, and DIFC/rate-limit milestones were not represented as span events. The PR adds those missing semantics and timeline markers in unified and proxy paths.

• GenAI semconv completion (mcp.tool_call)

  • Adds gen_ai.operation.name="execute_tool" to tool-call spans.
  • Adds gen_ai.agent.name="mcp-gateway" to tool-call spans.
  • Keeps existing attributes (gen_ai.system, gen_ai.agent.id, gen_ai.tool.name, mcp.method) intact.

• DIFC milestone span events

  • Adds difc.pre_phases_complete after successful pre-phases.
  • Adds difc.access_denied with structured reason on policy denials.
  • Applies in both:
    • unified server tool-call path
    • proxy DIFC pipeline path

• Rate-limit observability events

  • Adds rate_limit.detected event when rate-limit signals are detected.
  • Includes reset_at event attribute when available.
  • Adds rate_limit.hit=true attribute on proxy forward span when signaled.

• Proxy rate-limit signal consolidation

  • Introduces a shared internal helper for rate-limit detection in proxy flow and reuses it for both header injection and tracing event emission.

• Tracing docs and focused test updates

  • Updates OTel/Sentry docs to reflect new GenAI attributes and span events.
  • Extends tracing/rate-limit tests to cover new attributes and helper behavior.

return startSpan(ctx, tracer, "mcp.tool_call", oteltrace.SpanKindInternal,
    GenAISystem.String("mcp"),
    GenAIAgentName.String("mcp-gateway"),
    GenAIAgentID.String(serverID),
    GenAIOperationName.String("execute_tool"),
    MCPMethod.String("tools/call"),
    GenAIToolName.String(toolName),
)

[lpcox]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved in 2ec32599. I merged main, fixed the tracing helper conflicts, and verified the result with targeted package tests plus make agent-finished.

[Copilot]

Pull request overview

This PR enhances OpenTelemetry trace semantics for MCP tool calls and the proxy DIFC pipeline by adding milestone span events for DIFC phases/denials and rate-limit detection, improving trace timelines and Sentry visibility.

Changes:

• Emit DIFC milestone span events in both unified tool-call flow and proxy DIFC pipeline (difc.pre_phases_complete, difc.access_denied with reason).
• Emit rate_limit.detected span events with optional reset_at, and set rate_limit.hit=true on relevant spans when rate limiting is detected.
• Consolidate proxy rate-limit signal detection into a shared helper and add focused unit test coverage for the helper.

Show a summary per file

File	Description
internal/server/unified.go	Adds DIFC and rate-limit milestone events to mcp.tool_call spans (and propagates rate_limit.hit).
internal/proxy/handler.go	Adds DIFC milestone events, rate-limit event/attribute emission, and introduces shared rateLimitSignal helper.
internal/proxy/rate_limit_test.go	Adds unit tests covering the new rateLimitSignal helper behavior.
docs/otel-sentry.md	Documents new gen_ai.* attributes on mcp.tool_call and the new milestone span events / expanded rate_limit.hit coverage.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 4/4 changed files
• Comments generated: 0