Summary

This PR implements W3C Trace Context propagation from API spans to core spans, enabling parent-child linkage in distributed traces. This completes the handshake between PR #6 (API span lifecycle) and PR #2 (core span lifecycle).

Part of journey tracing series: PRs #0-#7 completed, #8-#9 remaining

What Changed

Core Implementation

Added inject_trace_context() helper (vllm/tracing.py, ~30 lines):

• Injects span context into carrier dict using W3C Trace Context propagator
• Mirrors existing extract_trace_context() for symmetric API
• Defensive error handling (returns carrier on failure, no exceptions)
• Early return when OTEL unavailable (zero overhead)

Added context injection in API layer (chat_completion/serving.py, ~16 lines):

• Injection occurs immediately after API span creation succeeds
• Before engine.generate() call (critical ordering preserved)
• Wrapped in try-except with DEBUG logging
• Modified trace_headers flows to both beam_search and engine.generate paths

Test Coverage

New test file: tests/entrypoints/openai/test_context_propagation.py (~430 lines)

12 tests, all passing:

• ✅ Basic injection with None carrier
• ✅ Injection with existing carrier (preserves headers)
• ✅ Early return when span is None
• ✅ Early return when OTEL unavailable
• ✅ Graceful failure handling
• ✅ W3C traceparent format validity
• ✅ Existing headers preserved during injection
• ✅ Conditional injection (only when span exists)
• ✅ Tracing disabled behavior (backward compatibility)
• ✅ Integration point verification
• ✅ Graceful failure (request continues)
• ✅ Trace ID continuity through Client→API→Core chain

Strengthened test: Mock propagator actually reads span.get_span_context() to prove span context usage.

Behavioral Guarantees Verified

All unit-testable guarantees from the approved plan:

• G1: Trace ID Continuity ✅ - API and core spans share same trace_id
• G2: W3C Format ✅ - traceparent header present with valid format
• G3: Trace Continuation ✅ - trace_id preserved (not replaced)
• G4: Graceful Degradation ✅ - Request continues on injection failure
• G5: No Exception Propagation ✅ - Injection failures never break requests
• G6: Conditional Injection ✅ - Only when API span exists

Invariants:

• I1: Backward Compatibility ✅ - Early return when tracing disabled
• I2: Zero Overhead ✅ - No allocations when disabled
• I3: No Resource Leaks ✅ - Only modifies existing dict

Test Results

✅ 12/12 new tests pass (test_context_propagation.py)
✅ 17/17 existing API span tests pass (test_api_span_lifecycle.py)
✅ 8/8 API span tracking tests pass (test_api_span_tracking.py)
✅ Total: 37/37 tests pass (100%)

Why This Is Safe

No Lifecycle Risk

• ✅ Zero new resources (only modifies existing trace_headers dict)
• ✅ No cleanup obligations (dict managed by request lifecycle)
• ✅ Stateless transformation (span context → headers)

Defensive Error Handling

• ✅ All OTEL operations wrapped in try-except
• ✅ Failures logged at DEBUG level only
• ✅ Request processing never interrupted

Performance

• ✅ Early return when tracing disabled (before propagator instantiation)
• ✅ No allocations when disabled
• ✅ Single injection point (no redundant operations)

Ordering Safety

• ✅ Strict sequence preserved: span creation → inject → engine call
• ✅ Single-threaded request processing (no race conditions)

Edge Cases Handled

1. Injection failure: Request continues, core span becomes root (no linkage)
2. Span is None: Early return, no injection attempted
3. OTEL unavailable: Early return, headers preserved
4. Tracing disabled: Early return, zero overhead
5. Incoming client traceparent: trace_id preserved through chain

Polish Fixes Applied

Following code review:

1. Clarified docstring: Documents when carrier is returned unchanged (not "returns None on failure")
2. Strengthened test: Propagator now reads span.get_span_context() to generate traceparent (proves G1/G3 without OTLP)

Files Modified

Total: ~489 lines added

Compliance with Approved Plan

✅ All scope constraints met (no new resources)
✅ All hard constraints satisfied (ordering, semantics, defensive behavior)
✅ All testing requirements fulfilled (behavioral properties A-E)
✅ Zero regressions (all existing tests pass)
✅ Follows vLLM coding conventions

Next Steps

• PR [Feature] Initialize OTEL tracer in scheduler for journey tracing (PR #1/9) #8: Add remaining API events (HANDOFF_TO_CORE, FIRST_RESPONSE_FROM_CORE)
• PR [CI] Add Docker build and push workflow #9: Remove journey event buffering (obsolete with OTEL spans)

Related PRs

• Depends on: PR [Feature] Add request journey event tracing to v1 scheduler #2 (core span lifecycle), PR [Feature] Implement dual-stream journey tracing with OTEL spans #6 (API span lifecycle)
• Enables: PR [Feature] Initialize OTEL tracer in scheduler for journey tracing (PR #1/9) #8 (API events), PR [CI] Add Docker build and push workflow #9 (remove buffering)

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com