Add structured logging with correlation IDs for distributed tracing

[vladiant]

Summary

Adds structured logging with per-request correlation IDs across all layers, replacing the basic logging.basicConfig() setup. Every request now carries a unique trace identifier through its entire lifecycle, making it possible to follow a request's path across log lines and downstream services.

Changes

New modules:

• correlation.py — contextvars-based correlation ID storage with X-Correlation-ID header propagation
• logging_config.py — CorrelationIdFilter, JSONFormatter, and configure_logging() setup helper

Middleware (middleware.py):

• Reads X-Correlation-ID from incoming requests or generates a new UUID
• Sets the correlation ID in a ContextVar for the duration of the request
• Echoes the correlation ID back in the response header

Targeted logging added to:

• routes/images.py — upload rejections (content-type, size, tags, validation), successful uploads, 404s
• routes/retention.py — sweep trigger with batch size
• upload_image.py — image persisted with ID, filename, path
• get_image.py — not-found lookups and missing paths (DEBUG)
• process_image.py — processing start, completion with dimensions, and non-existent image warning
• pipeline.py — batch start/complete with counts
• local_image_storage.py — file store/retrieve/delete (DEBUG)
• cached_image_repository.py — cache hit/miss (DEBUG)

Bug fix:

• Replaced bare except Exception: with except Exception as e: in ProcessImageUseCase so the exception is captured in log output

Version

1.2.4 → 1.3.0 (MINOR — new features, no breaking changes)

Testing

• 14 new tests in test_correlation.py covering context var, logging filter, JSON formatter, and middleware integration
• Full suite: 101 passed, ruff clean, mypy clean

Diff

15 files changed, 366 insertions, 8 deletions