Request Correlation ID Middleware for Distributed Tracing #328
Description
Labels: middleware, observability, debugging, medium-priority
Description:
Implement correlation ID generation and propagation to trace requests across services, logs, and async operations.
Requirements:
- Generate unique correlation ID for each incoming request
- Accept client-provided correlation IDs (X-Correlation-ID header)
- Attach correlation ID to all logs within request lifecycle
- Include correlation ID in all error responses
- Propagate correlation ID to downstream services (future microservices)
- Store correlation ID in request context for easy access
- Support correlation across async operations (queues, workers)
- Include correlation ID in response headers
- Use industry-standard format (UUID v4)
- Integrate with distributed tracing systems (OpenTelemetry, Jaeger)
Acceptance Criteria:
- Every request has unique correlation ID
- Correlation IDs appear in all log entries for that request
- Error responses include correlation ID for support tickets
- Client can provide correlation ID for multi-step operations
- Correlation ID available in all middleware and controllers
- Async operations (emails, notifications) preserve correlation
- Response headers include X-Correlation-ID
- Distributed tracing tools can follow request flow
- Correlation IDs help debug issues across service boundaries
- No performance impact from ID generation
Correlation ID Format:
- UUID v4 (e.g., 550e8400-e29b-41d4-a716-446655440000)
- Generated via cryptographically secure random
- Unique per request (collision probability negligible)
Header Handling:
- Request: X-Correlation-ID (optional, client-provided)
- Response: X-Correlation-ID (always included)
- Propagate to downstream services in outgoing requests
Integration Points:
- Logger: Include correlationId in all log entries
- Error responses: Include correlationId in JSON
- Request context: Store for access by controllers/services
- Async jobs: Pass correlationId to queue messages
- External API calls: Send correlationId header
Use Cases:
- User reports error: Support uses correlation ID to find exact request
- Debugging: Trace request through multiple services
- Performance analysis: Track slow requests from start to finish
- Error tracking: Group related errors by correlation ID
Example Log Entry:
{
timestamp: "2024-03-19T10:30:45.123Z",
level: "info",
correlationId: "550e8400-e29b-41d4-a716-446655440000",
userId: "user123",
message: "Puzzle submitted successfully"
}