feat: Implement OpenTelemetry metrics, tracing, and context propagation

[stenalpjolly]

Summary

Integrates OpenTelemetry observability into the Java SDK to provide comprehensive tracing, metrics, and distributed context propagation. All telemetry instrumentation has been implemented at the HTTP transport layer to preserve clean client decoupling.

Expectation & Implementation

• Decoupled Telemetry Boundary: Telemetry spans and context injection are handled inside HttpMcpTransport.java to keep McpToolboxClientImpl.java protocol-agnostic.
• Distributed Tracing: Standardized client spans are created for the network lifecycles of initialize, tools/list, and tools/call <tool_name> operations with semantic attributes.
• W3C Context Propagation: Active trace context (traceparent, tracestate) is injected into the _meta field of JSON-RPC request payloads.
• Metrics Observation: Tracks operation durations and total session duration using double histograms with standardized HSL bucket boundaries.
• Robust Client Lifetime: McpToolboxClient now extends AutoCloseable to cleanly track and record total session duration on client termination.

Acceptance strategy

Functional Intent & Requirements

1. Handshake Tracing: The connection handshake must be wrapped in an initialize span. On success, the negotiated protocol version must be recorded.
2. Operations Tracing: Tool listing and invocation must be wrapped in tools/list and tools/call spans, respectively, recording attributes such as gen_ai.tool.name and gen_ai.operation.name.
3. W3C Propagation: Context headers must be propagated inside the JSON-RPC _meta parameter for all outbound requests.
4. Duration Metrics: Operation and session durations must be recorded as metrics using recommended bucket boundaries.
5. Error Tracking: Any HTTP network failures, JSON-RPC protocol errors, or runtime exceptions must be recorded on the active span and counted in metrics.

Automated Testing & Verification

• Pragmatic Unit Testing: TelemetryTest.java uses a mock HTTP server and the JUnit 5 OpenTelemetryExtension to assert that all spans are correctly created, semantic attributes are set, and W3C trace IDs are propagated in outgoing requests.
• Edge Case Coverage: Verified parser error fallback paths, record method implementations, and session duration error tracking under simulated failures.
• 100% Component Coverage: Achieved 100% line, branch, and instruction coverage for all telemetry components, TelemetryHelper, McpToolboxClientImpl, HttpMcpTransport, and all associated classes.
• Zero Style Violations: Formatting is fully compliant with Google Java standards, passing local Javadoc and checkstyle checks.

Test cases

• TelemetryTest.java:
  • testTelemetrySpansAndContextPropagation: Verifies connection, listing, and invocation tracing.
  • testTelemetryAndClientJsonRpcErrors: Verifies JSON-RPC error mapping, fallback code/message parsing, and error recording on active spans.
• McpToolboxClientImplTest.java: Added testGetMergedMetadata_WithMockGenericTransport_NullProviderEmptyHeadersAndNullExtraMetadata to verify metadata resolution defaults.
• Total Tests: Verified all 147 unit and integration tests locally, passing with 100% success.
• 100.00% Coverage: Verified 100.00% line coverage for all target and newly introduced files.

Breaking changes

None. Making McpToolboxClient extend AutoCloseable is fully backward-compatible.