Implements complete API-level span lifecycle with guaranteed cleanup on all
termination paths. This PR creates parent spans that will be linked to core
spans via context propagation in PR #7.

Key implementation:
- Added _create_api_span() with ARRIVED event emission
- Added _finalize_api_span() single finalizer (DEPARTED/ABORTED/cleanup-only)
- Added _pop_api_span_info() for explicit pop-at-start idempotence
- Wrapped streaming/non-streaming generators with comprehensive error handling
- Covered 12 termination paths (6 streaming, 6 non-streaming)

Critical fixes applied (post-review):
- Guaranteed span.end() via nested try/except/finally (prevents OTEL leaks)
- Eliminated brittle test patterns using kwargs-only helper function
- All 17 tests passing with robust event detection

Design patterns:
- Pop-at-start idempotence: only one caller succeeds in finalization
- Cleanup-only fallback: outer finally with terminal_event=None
- Re-raise pattern: CancelledError/GeneratorExit finalize then re-raise
- Cleanup independence: span.end() not gated on is_recording() or flags

Test coverage: 17 tests
- Span creation (2)
- Streaming termination (6)
- Non-streaming termination (5)
- Idempotence & leak prevention (2)
- Cleanup independence (2)

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

* [Feature] Add API parent span lifecycle management (PR #6/9)

Implements complete API-level span lifecycle with guaranteed cleanup on all
termination paths. This PR creates parent spans that will be linked to core
spans via context propagation in PR #7.

Key implementation:
- Added _create_api_span() with ARRIVED event emission
- Added _finalize_api_span() single finalizer (DEPARTED/ABORTED/cleanup-only)
- Added _pop_api_span_info() for explicit pop-at-start idempotence
- Wrapped streaming/non-streaming generators with comprehensive error handling
- Covered 12 termination paths (6 streaming, 6 non-streaming)

Critical fixes applied (post-review):
- Guaranteed span.end() via nested try/except/finally (prevents OTEL leaks)
- Eliminated brittle test patterns using kwargs-only helper function
- All 17 tests passing with robust event detection

Design patterns:
- Pop-at-start idempotence: only one caller succeeds in finalization
- Cleanup-only fallback: outer finally with terminal_event=None
- Re-raise pattern: CancelledError/GeneratorExit finalize then re-raise
- Cleanup independence: span.end() not gated on is_recording() or flags

Test coverage: 17 tests
- Span creation (2)
- Streaming termination (6)
- Non-streaming termination (5)
- Idempotence & leak prevention (2)
- Cleanup independence (2)

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

* [Docs] Add PR #14 reference to journey tracing plan

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

…/9)

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

Changes:
- Add inject_trace_context() helper to vllm/tracing.py
- Inject API span context into trace_headers after span creation
- Context flows to engine.generate() and scheduler for parent-child linkage
- Defensive error handling: injection failures never break requests
- Zero overhead when tracing disabled (early return)

Behavioral guarantees verified by tests:
- G1: Trace ID continuity (API and core spans share same trace_id)
- G2: W3C Trace Context format (traceparent header valid)
- G3: Trace continuation (trace_id preserved through Client→API→Core)
- G4: Graceful degradation (request continues on injection failure)
- G5: No exception propagation (injection failures caught)
- G6: Conditional injection (only when API span exists)

Invariants:
- I1: Backward compatibility (early return when tracing disabled)
- I2: Zero overhead when disabled (no propagator/allocation access)
- I3: No resource leaks (only modifies existing trace_headers dict)

Test coverage:
- 12 new tests (100% pass) covering all unit-testable properties
- 17 existing API span lifecycle tests pass (no regressions)
- Tests focus on behavioral properties, not implementation details

Safety properties:
- Zero new resources (only modifies existing dict)
- No cleanup obligations (dict managed by request lifecycle)
- Stateless transformation (span context → headers)
- Single injection point (strict ordering preserved)

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

Updates to reflect PR #7 completion:
- PR sequence table: Mark #7 as COMPLETED with 12 tests
- Dependency chain: Mark #6 and #7 as COMPLETED
- PR #7 section: Add completion status with commit hashes
- Document deliverables: inject_trace_context(), tests, guarantees

Remaining: PRs #8 (API events), #9 (remove buffering)

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

…/9) (#15)

* [Feature] Add API↔Engine context propagation for journey tracing (PR #7/9)

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

Changes:
- Add inject_trace_context() helper to vllm/tracing.py
- Inject API span context into trace_headers after span creation
- Context flows to engine.generate() and scheduler for parent-child linkage
- Defensive error handling: injection failures never break requests
- Zero overhead when tracing disabled (early return)

Behavioral guarantees verified by tests:
- G1: Trace ID continuity (API and core spans share same trace_id)
- G2: W3C Trace Context format (traceparent header valid)
- G3: Trace continuation (trace_id preserved through Client→API→Core)
- G4: Graceful degradation (request continues on injection failure)
- G5: No exception propagation (injection failures caught)
- G6: Conditional injection (only when API span exists)

Invariants:
- I1: Backward compatibility (early return when tracing disabled)
- I2: Zero overhead when disabled (no propagator/allocation access)
- I3: No resource leaks (only modifies existing trace_headers dict)

Test coverage:
- 12 new tests (100% pass) covering all unit-testable properties
- 17 existing API span lifecycle tests pass (no regressions)
- Tests focus on behavioral properties, not implementation details

Safety properties:
- Zero new resources (only modifies existing dict)
- No cleanup obligations (dict managed by request lifecycle)
- Stateless transformation (span context → headers)
- Single injection point (strict ordering preserved)

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

* [Polish] Improve inject_trace_context docstring and strengthen test

Two quality improvements following code review:

1. Clarify inject_trace_context() docstring:
   - Previous: "or None if injection failed" (misleading)
   - Now: Explicitly documents when carrier is returned unchanged
   - Details all three early-return paths (OTEL unavailable, span None, exception)

2. Strengthen test_trace_id_preserved_through_chain():
   - Mock propagator now actually reads span.get_span_context()
   - Extracts trace_id and span_id from span context
   - Generates traceparent using those values (simulates real OTEL behavior)
   - Asserts get_span_context() was called
   - Better proves G1/G3 guarantees without requiring real OTLP exporter

Test results: All 29 tests pass (12 context propagation + 17 lifecycle)

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

* [Docs] Mark PR #7 as completed in journey tracing plan

Updates to reflect PR #7 completion:
- PR sequence table: Mark #7 as COMPLETED with 12 tests
- Dependency chain: Mark #6 and #7 as COMPLETED
- PR #7 section: Add completion status with commit hashes
- Document deliverables: inject_trace_context(), tests, guarantees

Remaining: PRs #8 (API events), #9 (remove buffering)

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

* removing PR7_summary

Signed-off-by: Srinivasan Parthasarathy <spartha@us.ibm.com>

---------

Signed-off-by: Srinivasan Parthasarathy <spartha@us.ibm.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>