Skip to main content

blitz_script/
script_stats.rs

1//! What the JavaScript side costs, per frame.
2//!
3//! The renderer has published real timings for a while: resolve, paint and
4//! present. Script execution had none, so a profile could show a 4ms frame and
5//! a UI that still felt slow, with nothing in between to look at. Every
6//! reactive update, event handler, timer callback and microtask drain runs
7//! through a document's poll boundary, so timing that boundary accounts for the
8//! whole language runtime without passing a clock through every operation.
9//!
10//! Deliberately mirrors `blitz_shell::frame_stats`: a bounded ring, means and
11//! tails rather than a running average, and no data reported as zero when there
12//! is no data at all.
13
14use std::sync::Mutex;
15use std::time::Duration;
16
17/// How many polls to retain. Matches the frame ring so the two line up when
18/// read together.
19const CAPACITY: usize = 256;
20
21/// A poll that ran JavaScript. Polls that found nothing to do are counted but
22/// not retained: they are the idle case and would drag every average toward
23/// zero, hiding the handler that actually costs something.
24#[derive(Debug, Clone, Copy)]
25struct Poll {
26    duration: Duration,
27}
28
29/// Cumulative cost of one kind of work, so a poll can be attributed rather
30/// than merely measured. "JavaScript is slow" is not actionable; "scroll
31/// handlers cost 14ms of every 16ms poll" is.
32#[derive(Debug, Default, Clone, Copy)]
33struct Bucket {
34    calls: u64,
35    spent: Duration,
36    worst: Duration,
37}
38
39impl Bucket {
40    fn record(&mut self, duration: Duration) {
41        self.calls += 1;
42        self.spent += duration;
43        if duration > self.worst {
44            self.worst = duration;
45        }
46    }
47
48    fn absorb(&mut self, other: &Bucket) {
49        self.calls += other.calls;
50        self.spent += other.spent;
51        if other.worst > self.worst {
52            self.worst = other.worst;
53        }
54    }
55}
56
57#[derive(Debug, Default)]
58struct Log {
59    /// Buckets keyed by a compile-time label, for call sites hot enough that
60    /// allocating a `String` per call would be its own measurement error. DOM
61    /// construction runs thousands of times per mount.
62    statics: std::collections::BTreeMap<&'static str, Bucket>,
63    /// Event names are dynamic, so they are interned into a small set rather
64    /// than leaking a `String` per dispatch.
65    dynamic: std::collections::BTreeMap<String, Bucket>,
66    polls: Vec<Poll>,
67    /// Every poll, including the ones that did no work.
68    total: u64,
69    /// Polls that actually ran script.
70    productive: u64,
71    /// Cumulative time in the script runtime, idle polls included.
72    spent: Duration,
73}
74
75static LOG: Mutex<Option<Log>> = Mutex::new(None);
76
77thread_local! {
78    /// Per-thread buckets for the static labels, folded into [`LOG`] once per
79    /// poll.
80    ///
81    /// `record_static` runs per DOM node, so a 4,000-node mount calls it tens
82    /// of thousands of times. Taking the process-global lock there cost more
83    /// than several of the operations being timed, which inflated every
84    /// absolute the profile reported: the instrument was a measurable share of
85    /// the measurement. Script runs on one thread, so the accumulator can be
86    /// thread-local and the hot path needs no synchronisation at all.
87    static LOCAL_STATICS: std::cell::RefCell<Vec<(&'static str, Bucket)>> =
88        const { std::cell::RefCell::new(Vec::new()) };
89}
90
91/// Attribute a slice of script time to a fixed source, without allocating.
92///
93/// Use for anything called per DOM node. `record_work` takes a `&str` and
94/// interns it, which is fine per event and far too expensive per element.
95pub fn record_static(label: &'static str, duration: Duration) {
96    // `try_with`/`try_borrow_mut` rather than the panicking forms: this runs
97    // inside `Drop`, and a profiler that can panic during unwinding turns a
98    // recoverable error into an abort.
99    let _ = LOCAL_STATICS.try_with(|local| {
100        let Ok(mut buckets) = local.try_borrow_mut() else {
101            return;
102        };
103        // Linear scan over a fixed, tiny label set (one entry per DOM binding).
104        // Cheaper than hashing or an ordered map at this size, and identical
105        // literals share an address, so the common case is one word compare.
106        if let Some((_, bucket)) = buckets
107            .iter_mut()
108            .find(|(seen, _)| std::ptr::eq(*seen, label) || *seen == label)
109        {
110            bucket.record(duration);
111            return;
112        }
113        let mut bucket = Bucket::default();
114        bucket.record(duration);
115        buckets.push((label, bucket));
116    });
117}
118
119/// Fold the calling thread's static buckets into the shared log.
120///
121/// Only this thread's, by construction. Script and the diagnostics collection
122/// that reads these both run on the document thread, so that is the thread
123/// whose buckets matter; a reader on any other thread sees the totals as of the
124/// last poll rather than a torn half-update.
125fn drain_local_statics(log: &mut Log) {
126    let _ = LOCAL_STATICS.try_with(|local| {
127        let Ok(mut buckets) = local.try_borrow_mut() else {
128            return;
129        };
130        for (label, bucket) in buckets.iter_mut() {
131            log.statics.entry(*label).or_default().absorb(bucket);
132            *bucket = Bucket::default();
133        }
134    });
135}
136
137/// What crossed from the guest runtime into the host, in bytes.
138///
139/// The runtime adapter records each string conversion at the boundary. Repeated
140/// values count separately because each copied string is part of the traffic.
141#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
142pub struct BoundaryCounters {
143    /// Strings copied from the guest runtime into the host.
144    pub strings_crossed: u64,
145    /// Their total length in UTF-8 bytes.
146    pub bytes_copied: u64,
147}
148
149thread_local! {
150    /// Script runs on the document thread, so a `Cell` is the whole
151    /// synchronisation story and the hot path needs no atomic.
152    static BOUNDARY: std::cell::Cell<BoundaryCounters> =
153        const { std::cell::Cell::new(BoundaryCounters { strings_crossed: 0, bytes_copied: 0 }) };
154}
155
156/// Record one guest-to-host string conversion, using its UTF-8 byte length.
157///
158/// Gated on the same switch as [`Timed`], so a build that is not profiling pays
159/// one relaxed atomic load and nothing else.
160pub fn record_boundary_string(bytes: usize) {
161    if !blitz_traits::profiling::deep_profiling_enabled() {
162        return;
163    }
164    let _ = BOUNDARY.try_with(|cell| {
165        let mut counters = cell.get();
166        counters.strings_crossed += 1;
167        counters.bytes_copied += bytes as u64;
168        cell.set(counters);
169    });
170}
171
172/// What has crossed on this thread since the last [`reset_boundary_counters`].
173#[must_use]
174pub fn boundary_counters() -> BoundaryCounters {
175    BOUNDARY.try_with(std::cell::Cell::get).unwrap_or_default()
176}
177
178/// Zero the boundary counters for this thread.
179pub fn reset_boundary_counters() {
180    let _ = BOUNDARY.try_with(|cell| cell.set(BoundaryCounters::default()));
181}
182
183/// Attribute a slice of script time to a named source.
184///
185/// Called from the runtime around timer callbacks and DOM event dispatch. The
186/// label is the event name where there is one, so a profile says which handler
187/// is expensive instead of only that something was.
188pub fn record_work(label: &str, duration: Duration) {
189    let Ok(mut guard) = LOG.lock() else {
190        return;
191    };
192    let log = guard.get_or_insert_with(Log::default);
193    log.dynamic
194        .entry(label.to_string())
195        .or_default()
196        .record(duration);
197}
198
199/// The costliest sources seen so far, worst total first.
200#[must_use]
201pub fn work_breakdown() -> Vec<(String, u64, f64, f64)> {
202    let Ok(mut guard) = LOG.lock() else {
203        return Vec::new();
204    };
205    // Statics accumulate off-lock, so fold this thread's in before reading or
206    // the breakdown reports the state as of the previous poll.
207    let log = guard.get_or_insert_with(Log::default);
208    drain_local_statics(log);
209    let mut rows: Vec<(String, u64, f64, f64)> = log
210        .statics
211        .iter()
212        .map(|(label, bucket)| {
213            (
214                (*label).to_string(),
215                bucket.calls,
216                bucket.spent.as_secs_f64() * 1_000.0,
217                bucket.worst.as_secs_f64() * 1_000.0,
218            )
219        })
220        .chain(log.dynamic.iter().map(|(label, bucket)| {
221            (
222                label.clone(),
223                bucket.calls,
224                bucket.spent.as_secs_f64() * 1_000.0,
225                bucket.worst.as_secs_f64() * 1_000.0,
226            )
227        }))
228        .collect();
229    rows.sort_by(|a, b| b.2.partial_cmp(&a.2).unwrap_or(std::cmp::Ordering::Equal));
230    rows
231}
232
233/// Record one `poll`. Cheap enough to leave on: a lock and a push.
234pub fn record_poll(duration: Duration, ran_script: bool) {
235    let Ok(mut guard) = LOG.lock() else {
236        return;
237    };
238    let log = guard.get_or_insert_with(Log::default);
239    // Once per poll is the natural fold point: the lock is already held, and a
240    // poll is the unit the rest of these numbers are reported in.
241    drain_local_statics(log);
242    log.total += 1;
243    log.spent += duration;
244    maybe_report(log);
245    if !ran_script {
246        return;
247    }
248    log.productive += 1;
249    if log.polls.len() == CAPACITY {
250        log.polls.remove(0);
251    }
252    log.polls.push(Poll { duration });
253}
254
255/// Mean, 95th percentile and worst case for the retained polls, in
256/// milliseconds.
257#[derive(Debug, Clone, Copy, PartialEq)]
258pub struct ScriptStatsSnapshot {
259    pub mean_ms: f64,
260    pub p95_ms: f64,
261    pub max_ms: f64,
262    /// Polls that ran script, out of the retained window.
263    pub window_polls: u64,
264    /// Every poll since launch.
265    pub total_polls: u64,
266    /// Polls that ran script since launch.
267    pub productive_polls: u64,
268    /// Total time in the script runtime since launch, in milliseconds.
269    pub spent_ms: f64,
270}
271
272/// `None` until script has actually run, so a caller reports "no data" rather
273/// than printing zeros that look like a measurement.
274#[must_use]
275pub fn latest_script_stats() -> Option<ScriptStatsSnapshot> {
276    // Permission, not an attached consumer: the same reason as
277    // `blitz_shell::frame_stats::latest_frame_stats`. Requiring a consumer to
278    // *read* what has already been recorded made the owner's toggle look inert,
279    // because the local `[blitz-frame]` log file has no consumer to attach.
280    // The recorders above stay gated on `deep_profiling_enabled`, which is the
281    // part that costs something per section.
282    if !blitz_traits::profiling::deep_profiling_permitted() {
283        return None;
284    }
285    let guard = LOG.lock().ok()?;
286    let log = guard.as_ref()?;
287    if log.polls.is_empty() {
288        return None;
289    }
290    let mut millis: Vec<f64> = log
291        .polls
292        .iter()
293        .map(|poll| poll.duration.as_secs_f64() * 1_000.0)
294        .collect();
295    let sum: f64 = millis.iter().sum();
296    let mean = sum / millis.len() as f64;
297    millis.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
298    // Nearest rank, so a short window still reports a real observation rather
299    // than an interpolation between two samples it does not have.
300    let rank = ((millis.len() as f64) * 0.95).ceil() as usize;
301    let p95 = millis[rank.saturating_sub(1).min(millis.len() - 1)];
302    Some(ScriptStatsSnapshot {
303        mean_ms: mean,
304        p95_ms: p95,
305        max_ms: *millis.last().unwrap_or(&0.0),
306        window_polls: millis.len() as u64,
307        total_polls: log.total,
308        productive_polls: log.productive,
309        spent_ms: log.spent.as_secs_f64() * 1_000.0,
310    })
311}
312
313/// Times a scope and attributes it on drop.
314///
315/// Every early return and `?` in a DOM binding is an exit path, and a manual
316/// stopwatch would miss most of them. This cannot.
317///
318/// Compiled out unless the `dom-stats` feature is on. The clock reads alone are
319/// two `mach_absolute_time` calls per DOM operation, which a release build has
320/// no reader for and should not pay. `debug-control` turns it on, so inspector
321/// builds keep the attribution; it can also be enabled by itself to profile a
322/// build shaped like the shipping one.
323#[cfg(feature = "dom-stats")]
324pub struct Timed {
325    label: &'static str,
326    started: Option<std::time::Instant>,
327}
328
329#[cfg(feature = "dom-stats")]
330impl Timed {
331    #[must_use]
332    /// Use the profiling mode selected at the start of the enclosing job slice.
333    pub fn new(profiling: bool, label: &'static str) -> Self {
334        Self {
335            label,
336            started: profiling.then(std::time::Instant::now),
337        }
338    }
339}
340
341/// Print what the script runtime is costing, once a second, under
342/// `BLITZ_SCRIPT_STATS=1`.
343fn maybe_report(log: &Log) {
344    use std::sync::OnceLock;
345    use std::time::Instant;
346
347    static ENABLED: OnceLock<bool> = OnceLock::new();
348    if !*ENABLED.get_or_init(|| {
349        matches!(
350            std::env::var("BLITZ_SCRIPT_STATS").ok().as_deref(),
351            Some("1") | Some("true")
352        )
353    }) {
354        return;
355    }
356
357    static LAST: std::sync::Mutex<Option<Instant>> = std::sync::Mutex::new(None);
358    let Ok(mut last) = LAST.lock() else { return };
359    let now = Instant::now();
360    if last.is_some_and(|time| now.duration_since(time) < Duration::from_secs(1)) {
361        return;
362    }
363    let elapsed = last.map(|time| now.duration_since(time));
364    *last = Some(now);
365    drop(last);
366
367    let spent_ms = log.spent.as_secs_f64() * 1000.0;
368    static PREV_SPENT: std::sync::Mutex<f64> = std::sync::Mutex::new(0.0);
369    let delta_ms = if let Ok(mut previous) = PREV_SPENT.lock() {
370        let delta = spent_ms - *previous;
371        *previous = spent_ms;
372        delta
373    } else {
374        0.0
375    };
376    let share = elapsed
377        .map(|duration| delta_ms / (duration.as_secs_f64() * 1000.0) * 100.0)
378        .unwrap_or(0.0);
379
380    eprintln!(
381        "[script] polls={} productive={} spent={spent_ms:.0}ms last_second={delta_ms:.1}ms ({share:.1}% of wall clock)",
382        log.total, log.productive,
383    );
384}
385
386#[cfg(feature = "dom-stats")]
387impl Drop for Timed {
388    fn drop(&mut self) {
389        if let Some(started) = self.started {
390            record_static(self.label, started.elapsed());
391        }
392    }
393}
394
395/// Discard every retained script and DOM timing sample.
396pub fn clear() {
397    if let Ok(mut log) = LOG.lock() {
398        *log = None;
399    }
400    let _ = LOCAL_STATICS.try_with(|local| {
401        if let Ok(mut buckets) = local.try_borrow_mut() {
402            buckets.clear();
403        }
404    });
405}
406
407/// The zero-cost stand-in. Same call sites, no clock, no bucket, no drop glue.
408#[cfg(not(feature = "dom-stats"))]
409pub struct Timed;
410
411#[cfg(not(feature = "dom-stats"))]
412impl Timed {
413    #[must_use]
414    #[inline(always)]
415    pub fn new(_profiling: bool, _label: &'static str) -> Self {
416        Self
417    }
418}
419
420#[cfg(test)]
421mod tests {
422    use super::*;
423
424    /// These share one process-global log, so they must not interleave. Without
425    /// this the suite passes or fails depending on thread scheduling, which is
426    /// worse than no test at all.
427    static SERIAL: Mutex<()> = Mutex::new(());
428
429    /// The serial lock, and a consumer holding sampling open for the test.
430    ///
431    /// Both have to outlive the body because recording needs permission and an
432    /// attached consumer, so a profiling guard created and dropped inside this helper
433    /// would stop collection before the caller records anything.
434    struct TestCapture {
435        _serial: std::sync::MutexGuard<'static, ()>,
436        _sampling: blitz_traits::profiling::DeepProfilingGuard,
437    }
438
439    fn reset() -> TestCapture {
440        let guard = SERIAL
441            .lock()
442            .unwrap_or_else(|poisoned| poisoned.into_inner());
443        *LOG.lock().unwrap() = None;
444        // The static buckets outlive the shared log, so clearing only the log
445        // would leak the previous test's DOM samples into the next one.
446        LOCAL_STATICS.with(|local| local.borrow_mut().clear());
447        blitz_traits::profiling::set_deep_profiling_permitted(true);
448        let sampling =
449            blitz_traits::profiling::begin_deep_profiling().expect("permission was just granted");
450        TestCapture {
451            _serial: guard,
452            _sampling: sampling,
453        }
454    }
455
456    #[test]
457    fn static_labels_reach_the_breakdown_without_locking_per_call() {
458        let _serial = reset();
459        for _ in 0..3 {
460            record_static("dom:appendChild", Duration::from_micros(10));
461        }
462        record_static("dom:appendChild", Duration::from_micros(90));
463        let rows = work_breakdown();
464        let row = rows
465            .iter()
466            .find(|(label, ..)| label == "dom:appendChild")
467            .expect("the static bucket is reported");
468        assert_eq!(row.1, 4, "every call counted: {rows:?}");
469        assert!(
470            (row.3 - 0.09).abs() < 0.01,
471            "the worst call survives the total: {rows:?}"
472        );
473    }
474
475    #[test]
476    fn folding_twice_does_not_double_count() {
477        let _serial = reset();
478        record_static("dom:createElement", Duration::from_micros(50));
479        let first = work_breakdown();
480        let second = work_breakdown();
481        assert_eq!(
482            first, second,
483            "a drained bucket must not be added to the shared log again"
484        );
485    }
486
487    #[test]
488    fn nothing_is_reported_before_script_runs() {
489        let _serial = reset();
490        record_poll(Duration::from_millis(5), false);
491        assert!(
492            latest_script_stats().is_none(),
493            "idle polls are not a measurement of script cost"
494        );
495    }
496
497    #[test]
498    fn the_worst_poll_survives_the_mean() {
499        let _serial = reset();
500        for _ in 0..40 {
501            record_poll(Duration::from_millis(1), true);
502        }
503        record_poll(Duration::from_millis(60), true);
504        let stats = latest_script_stats().expect("script ran");
505        assert!(stats.mean_ms < 3.0, "one outlier must not move the mean");
506        assert!(
507            (stats.max_ms - 60.0).abs() < 1.0,
508            "the outlier is the whole point: {stats:?}"
509        );
510    }
511
512    #[test]
513    fn idle_polls_are_counted_without_diluting_the_window() {
514        let _serial = reset();
515        record_poll(Duration::from_millis(2), true);
516        for _ in 0..10 {
517            record_poll(Duration::from_micros(10), false);
518        }
519        let stats = latest_script_stats().expect("script ran");
520        assert_eq!(stats.window_polls, 1);
521        assert_eq!(stats.total_polls, 11);
522        assert_eq!(stats.productive_polls, 1);
523    }
524}