Add correlated V2 runtime latency profiles

[ZenAlexa]

Summary

I added opt-in host-side input profiling through flashdreams-run-v2 --profile-path. It writes JSONL records from each input event's timestamp to the IUILoop claim and the first following client-window write. A dedicated TimestampedInputSource extension supplies the clock origin for session-relative timestamps.

Closes #538

Measurement boundaries

input_to_ui_step_s ends when the IUILoop claims the input. input_to_window_write_s ends when the first following IClientWindow.write call returns. That write can present a held frame from before the input; the metric records the next host write completion. Measuring a rendered response to that input requires additional correlation.

For a native window, the endpoint normally follows the presenter call. WebRTC with an active video track ends after host materialization and admission to the bounded two-frame sender queue. A server waiting for a video track returns after shape validation. Active-peer delivery, RTP transit, browser decode, compositor scheduling, and physical scanout require client telemetry.

Each session segment records its runtime settings and measurement endpoints. Summaries report exact count and maximum values. Median and p90 use all observations through 1,024 samples, then use a bounded uniform reservoir; the artifact records the sample count and approximation status. The profile path is kept distinct from model statistics, MP4 output, and an enabled chunk lifecycle trace.

Validation

At 020fddb4, I ran the V2 CPU suite in the local optional-dependency environment: 185 passed and 5 skipped. The focused suite completed with 88 passed and 1 skipped.

• Ruff formatting, import checks, and undefined-name checks passed.
• Focused ty checks, compileall, and git diff --check passed.
• Sphinx built all 38 sources with 10 warnings also reproduced on the default branch.
• A 20,000-input JSONL probe measured a median 6.14 µs per profiled input across three runs, retaining 1,024 quantile samples per metric.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Greptile Summary

The PR adds opt-in JSONL profiling for V2 host-side input latency, correlating timestamped input with UI-loop claims and subsequent client-window writes.

• Adds RuntimeProfiler, bounded quantile summaries, session lifecycle integration, and profile-path validation.
• Publishes monotonic timestamp origins from native-window and WebRTC input sources.
• Documents profiling boundaries and adds CPU coverage for correlation, replacement sessions, output-path separation, and transport timing.

Confidence Score: 4/5

The PR is not yet safe to merge because disconnected WebRTC tracks can still report sender admission and finalize latency correlations without an active sender.

ZenAlexa reported that commit 1b6cc195 added a sender-availability transition guarded by the track lock, but the reviewed HEAD still has no sender-availability state: disconnect only clears _media_connected, and _VideoTrack.enqueue() rejects only closed tracks.

Files Needing Attention: flashdreams/flashdreams/runtime_v2/serving/webrtc_server.py

Important Files Changed

Filename	Overview
flashdreams/flashdreams/runtime_v2/runtime_profiler.py	Introduces session-scoped JSONL latency records and bounded-memory summary statistics.
flashdreams/flashdreams/runtime_v2/session_runner.py	Integrates input-claim and completed-window-write measurements into the V2 session lifecycle.
flashdreams/flashdreams/runtime_v2/webrtc_client_window.py	Exposes the WebRTC session’s monotonic timestamp origin for input correlation.
flashdreams/flashdreams/runtime_v2/serving/webrtc_server.py	Exposes the server event-clock origin; its existing peer and sender lifecycle remains important to profiling accuracy.
flashdreams/flashdreams/runtime_v2/native_window_client_window.py	Exposes a timestamp origin only when native input uses the runtime monotonic clock.

Sequence Diagram

sequenceDiagram
    participant I as Input source
    participant B as EventBuffer
    participant U as UI loop
    participant P as RuntimeProfiler
    participant W as Client window
    I->>B: Timestamped input event
    B->>U: Claim event batch
    U->>P: ui_step_started(events)
    U->>W: write(StepResult)
    W-->>U: write returns
    U->>P: window_write_completed()
    P->>P: Emit JSONL records and summaries

Loading

_{Reviews (7): Last reviewed commit: "Bound and describe runtime latency profi..." | Re-trigger Greptile}

[ArielG-NV]

Comment

[ZenAlexa]

Good catch to check this race. input_to_window_write_s deliberately ends at the existing IClientWindow.write return; for WebRTC that is the host's single-slot sender-mailbox write. Active-peer delivery, RTP transit, browser decode, composition, and display live beyond this host-side sample and need client telemetry. _sender_available changes transport queuing behavior; client telemetry supplies the presentation timestamp, so that state stays outside this profiling patch.

[ZenAlexa]

Pulled #548's multi-session lifecycle into 5a90e4e9 and followed its new session ownership through the profiler path.

Each replacement now gets a fresh clock binding and an independent JSONL segment, with WebRTC's rebased timestamps mapped back to the correct monotonic session origin. The complete V2 CPU suite passes: 211 passed, 3 deselected. The two metrics remain anchored at IUILoop claim and the first following window write (ง •̀_•́)ง

[ZenAlexa]

I rechecked this against current HEAD and the PR diff. input_to_window_write_s intentionally ends when the existing IClientWindow.write call returns; for WebRTC that records host-side materialization and mailbox admission, including the existing disconnected-state behavior. Active-peer delivery, RTP transit, decode, composition, and display require client timestamps, so they remain a separate telemetry continuation.

This review keeps the transport contract unchanged and keeps #574 scoped to the two host-side perceived-latency checkpoints (•̀ᴗ•́)و

[ZenAlexa]

Synced current main through #584 in 0e007995 and resolved the new UILoopRequests flow at the profiling boundary. The V2 CPU suite completes with 215 passed / 3 deselected; Ruff, focused ty, compileall, and diff checks pass. The WebRTC endpoint description now follows #579's bounded two-frame sender queue.

[jmccaffrey-nv]

Reviewed the implementation against #538, including native/WebRTC clock bridging, replacement-session ownership, correlation, cleanup, path collisions, security, and profiler overhead.

The PR satisfies the narrowed host-side checkpoints discussed on the issue: event receipt to IUILoop claim, and event receipt to the next window.write return. The latter is not causal or end-to-end perceived response latency: the UI can re-render a held pre-input frame, and WebRTC stops at host queue admission before transport, decode, composition, and scanout. The documentation states these limits; please keep that distinction explicit when closing #538.

Local validation at 0e007995: 215 V2 CPU tests passed; focused Ruff formatting/import checks, ty, compileall, and git diff --check passed. The documentation build reached the new section without a new warning; its warning-as-error run still reports 10 unrelated baseline warnings. GitHub currently shows only the successful Greptile check while NVIDIA runner validation awaits vetting.

I left three inline comments on self-describing profile metadata, unbounded in-memory summary retention, and stable event-type serialization. I found no new code-execution, deserialization, dependency, or credential-handling exposure.

-- reviewed using GPT-5.6 Sol

[jmccaffrey-nv]

/ok to test 0e00799

[ZenAlexa]

Addressed the three review threads in 020fddb4: session segments now include artifact and runtime context; summary quantiles use a bounded 1,024-sample reservoir with explicit approximation metadata; input types use UserInputEvent.get_type_name(). Endpoint docs now cover WebRTC's active-track and no-track write behavior.

Validation: 185 V2 CPU tests passed, 5 skipped in the local optional-dependency environment; 88 focused tests passed, 1 skipped; Ruff, focused ty, compileall, and diff checks passed. Sphinx built all 38 sources with 10 pre-existing warnings; current main reproduces all 10. A 20,000-input JSONL probe completed at a median 6.14 µs per profiled input across three runs, with 1,024 quantile samples retained per metric.

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.