Skip to content

feat: Structured Request Logging (F11)#125

Merged
leocamello merged 4 commits intomainfrom
feature/f11-structured-logging
Feb 14, 2026
Merged

feat: Structured Request Logging (F11)#125
leocamello merged 4 commits intomainfrom
feature/f11-structured-logging

Conversation

@leocamello
Copy link
Owner

Summary

Implements F11: Structured Request Logging — per-request structured logs with correlation IDs, privacy-safe content handling, and component-level filtering.

What's New

Logging Module (src/logging/)

  • mod.rs — Module exports + build_filter_directives() for EnvFilter construction
  • middleware.rs — UUID v4 request ID generation
  • fields.rs — Token extraction, status extraction, privacy-safe prompt truncation

Instrumented Request Handler

  • #[instrument] macro on handle_chat_completion() with 15 span fields
  • Fields recorded at lifecycle points: request entry → after routing → at completion
  • Log level progression: INFO (success) → WARN (retry) → ERROR (exhausted)

Route Reason Tracking

  • RoutingResult gains route_reason: String field
  • Descriptive reasons: highest_score:backend:0.95, round_robin:index_N, fallback:model:reason

Configuration

  • component_levels — per-component log level overrides
  • enable_content_logging — opt-in prompt preview (default: off, with startup warning)
  • JSON output format via tracing-subscriber JSON layer

Verification Summary

  • 437 tests pass (30 new: 20 integration + 7 unit + 3 doc tests)
  • Clippy clean, fmt clean
  • speckit.analyze: Full alignment (15/15 FR, 6/6 US, 10/10 SC)
  • verification.md: 123✅, 71 N/A
  • tasks.md: 90/90 tasks complete

Spec Artifacts

  • specs/011-structured-logging/spec.md — 15 functional requirements, 6 user stories
  • specs/011-structured-logging/walkthrough.md — Junior-developer-friendly code guide

Closes #117
Closes #118
Closes #119
Closes #120
Closes #121
Closes #122
Closes #123
Closes #124

- Add comprehensive spec for structured, queryable request logs
- Include correlation IDs for tracking retries and failovers
- Define JSON and human-readable log formats
- Ensure privacy-safe logging (no message content by default)
- Support configurable log levels per component
- Align with Constitution principles III, VIII, X
- Include complete requirements checklist (14/14 items passed)
- Add src/logging/ module (fields.rs, middleware.rs, mod.rs)
- Instrument handle_chat_completion with tracing spans
- Add request_id (UUID v4) correlation across retries/fallbacks
- Extend RoutingResult with route_reason field
- Extend LoggingConfig with component_levels and enable_content_logging
- Add build_filter_directives() for component-level filtering
- Add truncate_prompt() for privacy-safe content preview
- Support JSON and pretty log formats via tracing-subscriber
- Add 20 structured logging tests (integration + unit)
- Update nexus.example.toml with logging configuration examples

Closes #117
Closes #118
Closes #119
Closes #120
Closes #121
Closes #122
Closes #123
Closes #124
@leocamello leocamello added enhancement New feature or request structured-logging F11: Structured Request Logging labels Feb 14, 2026
@leocamello leocamello merged commit ac9f6e0 into main Feb 14, 2026
8 of 9 checks passed
@leocamello leocamello deleted the feature/f11-structured-logging branch February 14, 2026 19:11
@codecov-commenter
Copy link

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 73.14286% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.04%. Comparing base (b3e1730) to head (ae2b0a8).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
src/routing/mod.rs 65.43% 28 Missing ⚠️
src/logging/fields.rs 66.66% 12 Missing ⚠️
src/cli/serve.rs 0.00% 4 Missing ⚠️
src/api/completions.rs 93.47% 3 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #125      +/-   ##
==========================================
- Coverage   79.96%   79.04%   -0.92%     
==========================================
  Files          37       40       +3     
  Lines        1612     1756     +144     
==========================================
+ Hits         1289     1388      +99     
- Misses        323      368      +45     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

leocamello added a commit that referenced this pull request Feb 17, 2026
* feat(spec): add F11 structured request logging specification

- Add comprehensive spec for structured, queryable request logs
- Include correlation IDs for tracking retries and failovers
- Define JSON and human-readable log formats
- Ensure privacy-safe logging (no message content by default)
- Support configurable log levels per component
- Align with Constitution principles III, VIII, X
- Include complete requirements checklist (14/14 items passed)

* feat: implement Structured Request Logging (F11)

- Add src/logging/ module (fields.rs, middleware.rs, mod.rs)
- Instrument handle_chat_completion with tracing spans
- Add request_id (UUID v4) correlation across retries/fallbacks
- Extend RoutingResult with route_reason field
- Extend LoggingConfig with component_levels and enable_content_logging
- Add build_filter_directives() for component-level filtering
- Add truncate_prompt() for privacy-safe content preview
- Support JSON and pretty log formats via tracing-subscriber
- Add 20 structured logging tests (integration + unit)
- Update nexus.example.toml with logging configuration examples

Closes #117
Closes #118
Closes #119
Closes #120
Closes #121
Closes #122
Closes #123
Closes #124

* doc: add walkthrough and verification for F11 Structured Logging

* doc: mark VER-150 complete with PR #125
leocamello added a commit that referenced this pull request Feb 17, 2026
* feat(spec): add F11 structured request logging specification

- Add comprehensive spec for structured, queryable request logs
- Include correlation IDs for tracking retries and failovers
- Define JSON and human-readable log formats
- Ensure privacy-safe logging (no message content by default)
- Support configurable log levels per component
- Align with Constitution principles III, VIII, X
- Include complete requirements checklist (14/14 items passed)

* feat: implement Structured Request Logging (F11)

- Add src/logging/ module (fields.rs, middleware.rs, mod.rs)
- Instrument handle_chat_completion with tracing spans
- Add request_id (UUID v4) correlation across retries/fallbacks
- Extend RoutingResult with route_reason field
- Extend LoggingConfig with component_levels and enable_content_logging
- Add build_filter_directives() for component-level filtering
- Add truncate_prompt() for privacy-safe content preview
- Support JSON and pretty log formats via tracing-subscriber
- Add 20 structured logging tests (integration + unit)
- Update nexus.example.toml with logging configuration examples

Closes #117
Closes #118
Closes #119
Closes #120
Closes #121
Closes #122
Closes #123
Closes #124

* doc: add walkthrough and verification for F11 Structured Logging

* doc: mark VER-150 complete with PR #125
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment