---
phase: 02-junction-telemetry-audit-items
plan: 01
subsystem: streaming
tags: [tracing, telemetry, puck, junction, live-engine]

requires:
  - phase: 01-junction-fix
    provides: junction fill block in symbol_task (JUNC-01..04)
provides:
  - Structured junction telemetry (junction_gap_tid_delta, forming_bar_trades, ws_buffer_depth)
  - Per-symbol fill_from_rest timing summary (duration_ms, trade_count, bars_produced)
  - Puck event_type differentiation (junction_fill, normal_gap_fill, on_demand_gap_fill)
  - WS buffer drain and replay at junction startup
affects:
  [
    phase-04-parallel-fill,
    phase-08-integration-testing,
    phase-10-deploy-verification,
  ]

tech-stack:
  added: []
  patterns:
    - "Drain-and-measure: drain WS channel into Vec to measure buffer depth before junction fill"
    - "event_type tagging on puck_fill for distinguishing gap-fill contexts in journal logs"

key-files:
  created: []
  modified:
    - crates/opendeviationbar-streaming/src/live_engine.rs

key-decisions:
  - "Drain WS channel into Vec at junction to measure buffer depth (tokio mpsc has no .len())"
  - "Replay buffered WS trades after junction fill with gap detection to prevent trade loss"

patterns-established:
  - "fill_from_rest.symbol_summary structured log for per-symbol REST fill telemetry"
  - "junction.telemetry structured log emitted at every junction code path"
  - "puck_fill event_type parameter for context-aware gap-fill logging"

requirements-completed:
  [
    TELE-01,
    TELE-02,
    TELE-03,
    TELE-04,
    TELE-05,
    AUDT-02,
    AUDT-03,
    AUDT-04,
    AUDT-05,
  ]

duration: 2 min
completed: 2026-03-19
---

# Phase 02 Plan 01: Junction + fill_from_rest Telemetry Instrumentation Summary

**Structured tracing instrumentation across junction fill, fill_from_rest, and puck_fill with event_type differentiation and WS buffer depth measurement**

## Performance

- **Duration:** 2 min
- **Started:** 2026-03-19T21:53:16Z
- **Completed:** 2026-03-19T21:55:44Z
- **Tasks:** 4
- **Files modified:** 1

## Accomplishments

- Per-symbol fill_from_rest summary with duration_ms, trade_count, bars_produced for both data and no-data branches
- Junction telemetry emitting junction_gap_tid_delta, forming_bar_trades, ws_buffer_depth at all 3 code paths (gap, no-gap, no-rest-tid)
- WS buffer drain-and-replay at junction startup prevents trade loss during fill latency
- Puck event_type parameter distinguishes junction_fill, normal_gap_fill, and on_demand_gap_fill in journal output

## Task Commits

Each task was committed atomically:

1. **Task 1: Per-symbol fill_from_rest summary with timing** - `cf6e0dd` (feat)
2. **Task 2: Junction telemetry — gap size, forming bar trades, WS buffer depth** - `ff8aac0` (feat)
3. **Task 3: Puck event_type differentiation** - `ab47293` (feat)
4. **Task 4: Verify build compiles** - no commit (verification only, `cargo check` passed)

## Files Created/Modified

- `crates/opendeviationbar-streaming/src/live_engine.rs` - Added telemetry instrumentation across fill_from_rest, junction fill, and puck_fill

## Decisions Made

- Drain WS channel into Vec at junction to measure buffer depth — tokio mpsc::Receiver has no `.len()` method, so drain via `try_recv` is the only way to measure pending count
- Replay buffered WS trades after junction fill with full gap detection — prevents trade loss when WS trades arrive during junction fill latency

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- All telemetry instrumentation complete for Phase 2 Plan 1
- Ready for Plan 02-02 (AUDT-01: ring buffer capacity analysis)
- Junction telemetry provides tuning data needed by Phase 4 (parallel fill_from_rest)

---

_Phase: 02-junction-telemetry-audit-items_
_Completed: 2026-03-19_
