//! Per-stream capture statistics, for diagnosing a silent or flaky stream //! from the log without ever logging audio content. //! //! Plain counters updated inline on the audio thread (no locks, no extra //! threads): [`CaptureStats::record`] is called once per delivered packet, //! [`CaptureStats::maybe_report`] once per capture loop iteration. A report //! logs and resets the counters; [`CaptureStats::report_final`] logs //! unconditionally, for the one line a capture loop emits when it stops. use std::time::{Duration, Instant}; /// How often a running stream reports its statistics. const REPORT_INTERVAL: Duration = Duration::from_secs(10); #[derive(Debug, Clone, Copy)] pub(crate) struct CaptureStats { since: Instant, packets: u64, frames: u64, silent_packets: u64, /// Peak absolute sample value seen since the last report (0.0 if no /// samples were delivered, e.g. only silent packets). peak: f32, } impl CaptureStats { pub(crate) fn new(now: Instant) -> Self { Self { since: now, packets: 0, frames: 0, silent_packets: 0, peak: 0.0, } } /// Records one packet delivered by the backend: its frame count, whether /// the backend flagged it silent, and the samples it carried (used only /// for the peak; a silent packet's samples are all zero, so it does not /// move the peak). pub(crate) fn record(&mut self, packet_frames: usize, silent: bool, samples: &[f32]) { self.packets += 1; self.frames += packet_frames as u64; if silent { self.silent_packets += 1; } for &sample in samples { self.peak = self.peak.max(sample.abs()); } } /// Logs and resets the counters once at least [`REPORT_INTERVAL`] has /// passed since the last report (or since `new`). `now` is read once per /// capture loop iteration by the caller, not here, so this never touches /// the clock itself. pub(crate) fn maybe_report(&mut self, label: &str, now: Instant) { if now.duration_since(self.since) < REPORT_INTERVAL { return; } self.log(label); *self = Self::new(now); } /// Logs the counters accumulated since the last report, regardless of /// how much time has passed. Call once when a capture loop stops. pub(crate) fn report_final(&self, label: &str) { self.log(label); } fn log(&self, label: &str) { log::info!( "capture '{label}' last 10 s: packets={}, frames={}, silent_packets={}, peak={:.3}", self.packets, self.frames, self.silent_packets, self.peak ); } } #[cfg(test)] mod tests { use super::*; #[test] fn reports_only_after_ten_seconds_have_passed() { let t0 = Instant::now(); let mut stats = CaptureStats::new(t0); stats.record(480, false, &[0.5, -0.25]); // Not yet due: counters untouched. stats.maybe_report("test", t0 + Duration::from_secs(9)); assert_eq!(stats.packets, 1); assert_eq!(stats.frames, 480); // Due: logs (not asserted here) and resets. stats.maybe_report("test", t0 + Duration::from_secs(10)); assert_eq!(stats.packets, 0); assert_eq!(stats.frames, 0); assert_eq!(stats.silent_packets, 0); } #[test] fn a_report_resets_the_peak() { let t0 = Instant::now(); let mut stats = CaptureStats::new(t0); stats.record(100, false, &[0.9]); assert_eq!(stats.peak, 0.9); stats.maybe_report("test", t0 + Duration::from_secs(10)); assert_eq!(stats.peak, 0.0, "peak must not survive a report"); stats.record(100, false, &[0.2]); assert_eq!(stats.peak, 0.2, "only the new packet's peak remains"); } #[test] fn a_silent_packet_is_counted_but_does_not_move_the_peak() { let mut stats = CaptureStats::new(Instant::now()); stats.record(50, false, &[0.4]); stats.record(50, true, &[0.0, 0.0]); assert_eq!(stats.packets, 2); assert_eq!(stats.frames, 100); assert_eq!(stats.silent_packets, 1); assert_eq!(stats.peak, 0.4); } #[test] fn report_final_logs_without_requiring_elapsed_time() { // Mainly a smoke test that it compiles and does not panic or reset; // report_final must not mutate self (it takes &self). let mut stats = CaptureStats::new(Instant::now()); stats.record(10, false, &[0.1]); stats.report_final("test"); assert_eq!(stats.packets, 1, "report_final must not reset the counters"); } }