Overview

This is the 1st of 9 PRs in the journey tracing dual-stream architecture implementation. This PR initializes an OpenTelemetry tracer in the scheduler without creating any per-request state or spans. It establishes the foundation for the next PR, which will create and manage core spans.

Branch: pr1ofjourney
Depends on: #7 (EngineCoreEvent removal - already merged)
Next: The next PR will use this tracer to create core spans with complete lifecycle management

What This PR Does

Adds tracer initialization to Scheduler.__init__() that:

• Creates a tracer instance when both enable_journey_tracing=True AND otlp_traces_endpoint is configured
• Uses defensive programming with try/except and warning logs
• Provides graceful degradation if OTEL packages are unavailable
• Does NOT create any spans - just initialization
• Does NOT introduce per-request state - tracer is class-level only

Changes

Production Code (19 lines)

vllm/v1/core/sched/scheduler.py:

# Defensive import at top of file
try:
    from vllm.tracing import SpanAttributes
except Exception:
    SpanAttributes = None  # type: ignore

# Tracer initialization in __init__()
self.tracer: Any | None = None
if self._enable_journey_tracing:
    endpoint = self.observability_config.otlp_traces_endpoint
    if endpoint is not None:
        try:
            from vllm.tracing import init_tracer
            self.tracer = init_tracer("vllm.scheduler", endpoint)
        except Exception as e:
            logger.warning(
                "Failed to initialize tracer for journey tracing: %s", e
            )

Test Changes (112 lines)

tests/v1/core/utils.py (2 lines):

• Added otlp_traces_endpoint: str | None = None parameter to create_scheduler()
• Pass to ObservabilityConfig

tests/v1/core/test_scheduler.py (110 lines):

• Added patch import for mocking
• Added 4 comprehensive tests (all use mocking, no external dependencies):
  1. test_tracer_init_when_endpoint_set() - Positive path
  2. test_tracer_none_when_endpoint_not_set() - Negative paths (3 cases)
  3. test_scheduler_init_succeeds_with_tracing_enabled() - Smoke test
  4. test_tracer_init_handles_failure_gracefully() - Error handling

Safety Guarantees

✅ No Per-Request State

• Tracer is stored as self.tracer (class-level instance variable)
• Shared across all requests
• No per-request cleanup needed

✅ Zero Overhead When Disabled

• Guarded by TWO conditions:
  • enable_journey_tracing=False → tracer stays None
  • otlp_traces_endpoint is None → tracer stays None
• No OTEL imports on hot paths
• No tracer creation unless explicitly enabled

✅ No Spans Created

• This PR only initializes the tracer
• Spans will be created in the next PR (with cleanup in same PR)
• Zero tracing activity in this PR

✅ Graceful Degradation

• SpanAttributes import wrapped in try/except (None fallback)
• init_tracer() wrapped in try/except (warning log on failure)
• Scheduler initialization succeeds even if OTEL fails
• Warning log helps with debugging

✅ Backward Compatible

• All new parameters have defaults
• otlp_traces_endpoint defaults to None
• Existing code works unchanged
• No behavior changes unless explicitly enabled

✅ Legacy Tracing Untouched

• RequestJourneyEvent buffering still works
• OutputProcessor.do_tracing() still functional
• No changes to existing journey tracing code

Test Results

All 85 tests passing (81 existing + 4 new):

pytest tests/v1/core/test_scheduler.py -v
# 85 passed, 16 warnings in 24.53s

Test Coverage:

• ✅ Positive path: Tracer initialized when configured
• ✅ Negative paths: Tracer is None when disabled/unconfigured
• ✅ Smoke test: Scheduler initializes successfully
• ✅ Error handling: Graceful failure with warning log
• ✅ No regressions: All existing tests pass

Test Quality:

• All tests use mocking (no external OTEL collector needed)
• Deterministic and isolated
• Fast execution
• No flakiness

Code Review Notes

Issue identified during review: Test 3 initially called real init_tracer()
Fix applied: Added @patch decorator for deterministic testing
Result: All 4 tests now properly mocked and consistent

Resource Safety Checklist

• ✅ No spans created → no spans to close
• ✅ No per-request state → no per-request cleanup
• ✅ No buffering when tracer absent → graceful degradation
• ✅ Legacy tracing untouched → no regression risk
• ✅ Tests prove no leaks → all tests verify tracer is None when expected
• ✅ Defensive error handling → tracing failures don't break scheduler
• ✅ Zero overhead when disabled → early returns, no allocations

Architecture Context

This PR is part of the dual-stream journey tracing architecture (9 PRs total):

• Core Layer (PRs 1-4): Initialize tracer, create child spans, emit events
• API Layer (PRs 5-8): Add metadata, create parent spans, emit events
• Linkage (PR 7): W3C Trace Context propagation
• Cleanup (PR 9): Remove legacy buffering

This PR establishes the foundation for core layer tracing by initializing the tracer that will be used in the next PR.

See JOURNEY_TRACING_PR_PLAN.md for the complete implementation roadmap.

Next Steps

The next PR (2nd of 9) will:

• Use self.tracer to create core spans in add_request()
• Add _core_spans: dict[str, Span] to track active spans
• Implement _end_core_span_and_cleanup() for all termination paths
• Create spans AND cleanup in the same PR (Iron Rule compliance)

Related Documentation

• Implementation Plan: JOURNEY_TRACING_PR_PLAN.md (updated with completion status)
• User Guide: JOURNEY_TRACING.md (no changes needed - internal only)

Reviewer Checklist

When reviewing, please verify:

• No per-request state introduced
• No spans created (initialization only)
• Zero overhead when disabled
• Graceful error handling
• All 4 tests pass and use mocking
• No regressions in existing tests
• Backward compatible (optional parameters)

Size: 4 files changed, 236 insertions(+), 32 deletions(-)
Review Time: ~10 minutes
Safe to merge: Yes - no per-request state, no spans, complete test coverage