Telemetry Event Catalog
This page tracks core telemetry events that are useful for debugging recording quality, upload state, and player support cases.
For the detailed user-facing error and warning contract, see Core Signals.
Capture lifecycle
| Event | Level | Purpose |
|---|---|---|
capture.v2.start | INFO | Pure-v2 capture started with encoder and configuration details. Includes encoder_id, requested_encoder_id, and encoder_policy_overrode so dashboards can quantify how often the policy layer rewrites user/default encoder choice. |
capture.v2.target_baseline | INFO | Baseline target parameters for the active recording. |
capture.v2.first_frame | INFO | First frame successfully enqueued. setup_ms reports the time between capture.start and the first usable frame — long values point at WGC fallback failures or slow window readiness. Active-duration accounting begins here, not at capture.start, so pre-frame setup does not penalize muxed FPS. |
capture.source_unhealthy | WARNING | WGC reported the capture source has degraded (window minimized, hidden, or fallback texture unavailable). Recording auto-pauses immediately via the pause policy; no need to wait for the watchdog poll. |
capture.source_healthy | INFO | Capture source recovered from a previous capture.source_unhealthy. |
Quality and backpressure
| Event | Level | Purpose |
|---|---|---|
capture.v2.qos_snapshot | INFO | Periodic high-level capture queue and drop counters. |
capture.v2.pool_pressure | INFO | Texture pool pressure, waits, held slots, and availability. |
capture.v2.encode_stage.frame_metrics | INFO | Encode throughput and latency indicators. |
capture.v2.packet_queue.depth | INFO | Packet queue depth and blocked enqueue indicators. |
capture.v2.mux_stage.write_metrics | INFO | MP4 mux write latency and disk I/O indicators. |
capture.v2.fps_profiler.event | WARNING/INFO | FPS profiler warning raised, updated, or resolved. |
capture.v2.zero_video_output_watchdog | INFO/WARNING/ERROR | Detects active capture/encode flow that is not producing muxed video output. |
capture.v2.nvenc.encode_failed | ERROR | NVENC encode call failed. |
capture.v2.nvenc.lock_failed | ERROR | NVENC bitstream lock failed. |
capture.v2.mux_stage.write_failed | ERROR | Mux stage failed to write encoded packet data. |
Microphone (EC-259)
Events emitted by MicRecorder and the RecordingMicObserver. They cover
the opt-in lifecycle and the runtime mute toggle. Use them to verify how
often users actually opt into mic capture, how often mute is engaged, and
which device-open failures are common in the field.
| Event | Level | Purpose |
|---|---|---|
mic.skip | INFO | MicRecorder::start was called but MicConfig.enabled=false. Treated as success; no device is opened and no _mic.aac is written. Emitted once per recording session start when the user has not opted in. |
mic.open | INFO | WASAPI eCapture device opened. Carries the negotiated sample_rate, channels, bits, and is_float. Useful for spotting devices that report unusual formats (e.g. mono mics, 44.1 kHz mics, non-float). |
mic.start | INFO | Mic recording started. Carries the resolved path, sample_rate, channels, and bitrate. The path lets dashboards correlate the mic sidecar with the parent MP4 session. |
mic.stop | INFO | Mic recording stopped. AAC tail packets were drained and the _mic.aac file was closed. |
mic.config_update | INFO | /api/audio/mic-config POST committed a config change. Carries enabled, muted, and device ("default" or the endpoint ID). |
mic.hotkey_toggle | INFO | F7 was pressed and muted was flipped. Carries the new muted state. Use this to distinguish hotkey-driven mutes from UI-driven mutes (which appear as mic.config_update instead). |
mic.open_failed | WARNING | MicCapture::open failed (device disconnected, exclusive-mode collision, unsupported format). Carries the human-readable error. The session continues without a mic sidecar. |
mic.aac_init_failed | WARNING | Media Foundation AAC encoder failed to initialize for the mic stream. Same fallback as above — session proceeds, sidecar absent. |
mic.denoiser_init_failed | WARNING | IDenoiser::initialize returned false. Currently impossible with the shipped NoOpDenoiser; the event exists so DeepFilterNet / future implementations have a place to surface init issues. |
mic.encode_failed | WARNING | MediaFoundationAacEncoder::encode_pcm failed for one frame. The frame is dropped; subsequent frames are still encoded. Carries the underlying error. |
mic.poll_failed | WARNING | Polling AAC AUs from the MFT failed. Same handling as mic.encode_failed. |
mic.observer.start_failed | WARNING | RecordingMicObserver tried to start the recorder on a RecordingStartedEvent but MicRecorder::start returned false. Carries the derived path and the underlying error. The MP4 session continues. |
mic.privacy_gate.boot | INFO | EC-263 privacy gate verdict at core startup. Carries supported, reason (stable code), gpu_vendor, gpu_vram_mb, total_ram_mb. Tells you whether this user can use the mic at all. |
mic.privacy_gate.recompute | INFO | The gate was re-evaluated mid-session (driver hot-swap, GPU change). Carries the new supported and reason. |
mic.privacy_gate.block | WARNING | A /api/audio/mic-config POST tried to flip enabled on but the gate denied. Carries reason, gpu_vendor, and the prev_enabled state. The HTTP response was 403. |
Contributor identity link
These app-side events help debug the e2e contributor portal link flow. Edge Function and browser portal logs also include request_id for cross-system correlation.
| Event | Level | Purpose |
|---|---|---|
contributor_link.intent_opened | INFO | The Playroll app created a signed contributor link intent and opened the portal URL. |
contributor_link.intent_failed | WARNING | The app failed to create or open the contributor link intent. |
contributor_link.status_verified | INFO | The app read a verified contributor projection for the current app user. |
contributor_link.status_missing | DEBUG | The app read no contributor projection for the current app user. |
contributor_link.status_fetch_failed | WARNING | The app could not fetch the contributor projection. |
FPS profiler payload
capture.v2.fps_profiler.event includes:
| Field | Meaning |
|---|---|
phase | Emission phase, currently snapshot. |
type | warning_raised, warning_updated, or warning_resolved. |
severity | good, degraded, severe, or critical. |
reason | Granular profiler reason. |
active_seconds | Active recording time when the event was emitted. |
window_seconds | Snapshot window duration. |
window_muxed_fps | Muxed video FPS in the latest window. |
window_source_fps | Source/capture FPS in the latest window. |
window_encoded_fps | Encoded FPS in the latest window. |
cumulative_muxed_fps | Muxed FPS across the active recording. |
drop_ratio | Dropped frames divided by seen frames in the latest window. |
worst_window_muxed_fps | Worst muxed FPS while the warning has been active. |
Maintenance plan
This catalog should eventually be generated from source code by scanning LOG_EVENT(...) call sites and merging those entries with curated descriptions.