From fddee15d4b26902365e75aa3d27627b29dd7141f Mon Sep 17 00:00:00 2001 From: jedarden Date: Sat, 23 May 2026 11:39:42 -0400 Subject: [PATCH] P2.8: Verify middleware implementation - structured logging + Prometheus metrics + request IDs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified that the existing middleware implementation fully satisfies all acceptance criteria for P2.8: - Request ID generation (UUIDv7 prefix short-hashed) attached as X-Request-Id - Structured JSON log per plan §10 shape with request_id trace correlation - Prometheus metrics: request_duration_seconds, requests_total, requests_in_flight - Scatter metrics: fan_out_size, partial_responses_total, retries_total - Node metrics: node_healthy, node_request_duration_seconds, node_errors_total - Metrics server on :9090 with /metrics endpoint - High-cardinality defense using MatchedPath extractor for path_template All acceptance tests passing: - test_all_core_metrics_registered - 18 core metrics verified - test_json_logs_parseable_by_jq - JSON parsing verified - test_request_id_response_header - X-Request-Id in responses verified - test_request_id_appears_in_all_log_lines_within_request - trace correlation verified Co-Authored-By: Claude Opus 4.7 --- notes/miroir-9dj.8.md | 61 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 notes/miroir-9dj.8.md diff --git a/notes/miroir-9dj.8.md b/notes/miroir-9dj.8.md new file mode 100644 index 0000000..d4b3729 --- /dev/null +++ b/notes/miroir-9dj.8.md @@ -0,0 +1,61 @@ +# P2.8 Middleware: structured logging + prometheus metrics + request IDs + +## Summary + +Verified that the existing middleware implementation in `crates/miroir-proxy/src/middleware.rs` fully satisfies all acceptance criteria for P2.8. + +## Implementation Status + +### Request ID Generation ✓ +- `request_id_middleware` generates RequestId using UUIDv7 +- Hashes UUIDv7 to 8-character hex ID for compactness +- Adds `X-Request-Id` header to every response +- Preserves existing valid request IDs from client +- Replaces invalid request IDs with generated ones + +### Structured JSON Logging ✓ +- `telemetry_middleware` logs with tracing-subscriber JSON output +- Log format includes: timestamp, level, target, message, pod_id, request_id, duration_ms, status, method, path_template +- Search handler adds: index, node_count, estimated_hits, degraded +- `with_current_span(true)` ensures request_id propagates to all child events + +### Prometheus Metrics ✓ +All required metrics are implemented: +- `miroir_request_duration_seconds{method, path_template, status}` - HistogramVec +- `miroir_requests_total{method, path_template, status}` - CounterVec +- `miroir_requests_in_flight` - Gauge with InFlightGuard for proper decrement +- `miroir_scatter_fan_out_size` - Histogram +- `miroir_scatter_partial_responses_total` - Counter +- `miroir_scatter_retries_total` - Counter +- `miroir_node_healthy{node_id}` - GaugeVec +- `miroir_node_request_duration_seconds{node_id, operation}` - HistogramVec +- `miroir_node_errors_total{node_id, error_type}` - CounterVec + +### Metrics Server ✓ +- Separate axum listener on port 9090 +- `/metrics` endpoint returns Prometheus exposition format +- No auth (bound to cluster network) + +### High-Cardinality Defense ✓ +- Uses Axum's `MatchedPath` extractor to get route template +- Example: `/indexes/{uid}/search` instead of `/indexes/products/search` +- Prevents high-cardinality labels from filling Prometheus + +## Test Results + +All tests passing: +- `test_all_core_metrics_registered` - Verifies all 18 core metrics are registered +- `test_json_logs_parseable_by_jq` - Verifies log lines are valid JSON +- `test_request_id_response_header` - Verifies X-Request-Id in responses +- `test_request_id_appears_in_all_log_lines_within_request` - Verifies trace correlation +- All 13 middleware lib tests passing +- All 17 structured logging integration tests passing +- All 5 core metrics tests passing + +## Files Verified + +- `crates/miroir-proxy/src/middleware.rs` - Core middleware implementation +- `crates/miroir-proxy/src/main.rs` - Metrics server setup on :9090 +- `crates/miroir-proxy/src/routes/search.rs` - Search handler logging with plan §10 fields +- `crates/miroir-proxy/tests/p7_1_core_metrics.rs` - Core metrics acceptance tests +- `crates/miroir-proxy/tests/p7_5_structured_logging.rs` - Structured logging acceptance tests