Summary

This PR completes the journey tracing dual-stream architecture implementation across 10 PRs (PR #0 prerequisite + PRs #1-#9), including comprehensive regression audit and documentation.

What's Included

Implementation (PRs #0-#9)

• ✅ PR #0: Remove EngineCoreEvent system (prerequisite cleanup)
• ✅ PR [Feature] Add monotonically increasing step counter to vLLM scheduler #1: Initialize OTEL tracer in scheduler
• ✅ PR [Feature] Add request journey event tracing to v1 scheduler #2: Core span lifecycle management
• ✅ PR [Feature] Add CLI flag for journey tracing with OTEL integration #3: Journey state cleanup
• ✅ PR [Refactor] Use SpanAttributes constants for journey event attributes #4: Emit journey events to core spans
• ✅ PR [Bugfix] Fix prefill progress tracking for chunked prefill preemption #5: API span tracking infrastructure
• ✅ PR [Feature] Implement dual-stream journey tracing with OTEL spans #6: API parent span lifecycle
• ✅ PR [Bugfix] Remove legacy EngineCoreEvent system and restore Prometheus metrics #7: API↔Engine context propagation
• ✅ PR [Feature] Initialize OTEL tracer in scheduler for journey tracing (PR #1/9) #8: API lifecycle events and request attributes
• ✅ PR [CI] Add Docker build and push workflow #9: Remove journey event buffering (real-time emission)

Documentation & Quality

• ✅ Comprehensive end-user documentation (JOURNEY_TRACING.md)
• ✅ Detailed implementation plan (JOURNEY_TRACING_PR_PLAN.md)
• ✅ Repository guide for contributors (CLAUDE.md)
• ✅ Regression audit report (REGRESSION_AUDIT_REPORT.md)

Architecture

Dual-Stream Design:

• API Layer: Parent spans (llm_request) track end-to-end request lifecycle
• Engine Core: Child spans (llm_core) track scheduler-level processing
• Real-Time Emission: Events emitted directly to OTEL spans (no buffering)
• Parent-Child Linkage: W3C Trace Context propagation

Testing

Comprehensive Test Coverage:

• 88 new journey tracing tests (5,000+ lines)
• All existing tests passing (99/99 scheduler tests)
• Integration tests for API→Engine flow
• Backwards compatibility tests
• Zero overhead when disabled tests

Regression Audit Results

Verdict: ✅ NO PRODUCTION REGRESSIONS FOUND

Verified Safe:

• ✅ Backward compatible (all existing APIs preserved)
• ✅ Zero overhead when disabled (proper early-return guards)
• ✅ OTEL imports optional (graceful degradation without opentelemetry)
• ✅ Metrics independent (Prometheus works without tracing)
• ✅ Exception handling improved (better cleanup guarantees)
• ✅ No memory leaks (centralized cleanup with try/finally)

Changes Analyzed:

• 42 files changed (+10,824 insertions, -1,074 deletions)
• All production code paths verified
• OpenAI API correctness maintained
• Scheduler behavior unchanged
• Metrics/stats timestamp capture improved

Key Features

1. Optional Feature - Disabled by default (--enable-journey-tracing)
2. OTEL Native - Uses OpenTelemetry for industry-standard observability
3. Real-Time - Events emitted immediately (no buffering/deferred export)
4. Progress Tracking - Accurate token counts that survive preemption
5. Dual Stream - API and engine-core events in linked parent-child spans

Usage

# Enable journey tracing with OTEL endpoint
vllm serve MODEL --enable-journey-tracing --otlp-traces-endpoint http://localhost:4317

# View traces in Jaeger/Tempo/other OTEL backends

Breaking Changes

None - Fully backward compatible:

• New CLI flag is optional (default: false)
• No new required dependencies
• OTEL optional (works without opentelemetry installed)
• Existing APIs unchanged

Files Changed

Core Implementation:

• vllm/v1/core/sched/scheduler.py (+467 lines)
• vllm/entrypoints/openai/chat_completion/serving.py (major refactor)
• vllm/entrypoints/openai/engine/serving.py (+265 lines)
• vllm/tracing.py (+49 lines)
• vllm/config/observability.py (+6 lines)

Tests:

• 9 new test files (5,000+ lines)
• Test cleanup (removed 2 obsolete buffering tests)

Documentation:

• JOURNEY_TRACING.md (623 lines) - End-user guide
• JOURNEY_TRACING_PR_PLAN.md (2,226 lines) - Implementation plan
• REGRESSION_AUDIT_REPORT.md (530 lines) - Audit results
• CLAUDE.md (397 lines) - Repository guide

Review Focus

1. Regression Audit Report - Comprehensive analysis of all changes
2. Test Coverage - 88 new tests verify all scenarios
3. Documentation - Clear end-user and implementation docs
4. Backward Compatibility - All existing functionality preserved

Related

• All 10 PRs (#0-[CI] Add Docker build and push workflow #9) included in this branch
• Supersedes individual PRs (already merged to this branch)
• Ready for merge after review

🤖 Generated with Claude Code