📋 Summary

Implements comprehensive correlation ID tracking across the gateway to enable end-to-end request tracing through logs, OpenTelemetry spans, and distributed services.

🔗 Related Issues

Closes #300

🔧 Changes Made

Core Implementation

• New utility module (correlation_id.py): ContextVar-based correlation ID storage for async-safe request tracking
• New middleware (correlation_id.py): HTTP middleware for X-Correlation-ID header extraction, validation, and injection
• Enhanced logging (logging_service.py): CorrelationIdJsonFormatter for automatic correlation ID injection into JSON logs

Configuration

1. Added 4 new settings in config.py:

   • correlation_id_enabled: Enable/disable correlation ID tracking
   • correlation_id_header: Configurable header name (default: X-Correlation-ID)
   • correlation_id_preserve: Preserve client-provided IDs
   • correlation_id_response_header: Echo correlation ID in responses

2. Updated .env.example with configuration examples

Integration Points

1. main.py: Registered CorrelationIDMiddleware in middleware stack
2. auth.py: Added _log_auth_event() helper for structured auth logging with correlation IDs
3. tool_service.py: Integrated correlation ID fallback chain
4. http_auth_middleware.py: Unified correlation ID usage
5. observability.py: Auto-inject correlation_id into OpenTelemetry spans
6. request_logging_middleware.py: Enhanced request logging with correlation IDs
7. a2a_service.py: Added correlation ID import for future usage

✅ Testing

Example usage

curl.exe -v -H "X-Correlation-ID: trace-12345" http://localhost:4444/health

• Response body: {"status":"healthy"}
• Response header: x-correlation-id: trace-12345
• Server logs: {"request_id": "trace-12345", "level": "INFO", ...}