Skip to main content

rustango_cms/
perf.rs

1//! Request timing instrumentation — opt-in, off by default.
2//!
3//! Set `CMS_PERF_LOG=1` to get one log line per request with the total
4//! wall time plus a breakdown of the phases the handler recorded:
5//!
6//! ```text
7//! PERF GET /getting-started -> 303 in 3512.4ms | tenant=181.2 locale=182.0
8//!      resolve=543.9 restriction=362.1 render=0.0
9//! ```
10//!
11//! The point is attribution. A slow page is nearly always slow for one
12//! of two reasons — too many sequential round-trips, or one expensive
13//! phase — and a single total tells you neither.
14//!
15//! Phases are recorded through a task-local, so [`mark`] is a no-op
16//! outside a request (tests, CLI commands) and costs an atomic load
17//! when the feature is off.
18
19use std::cell::RefCell;
20use std::time::Instant;
21
22// tokio is not a direct dependency; the framework re-exports it for
23// exactly this reason (same path `#[rustango::main]` resolves through).
24rustango::__private_runtime::tokio::task_local! {
25    /// Phase marks for the request being served by *this task*.
26    ///
27    /// Deliberately a task-local, not a thread-local: tokio moves a task
28    /// between worker threads at any await point, so thread-local marks
29    /// get attributed to whichever request happens to be on that thread
30    /// afterwards — the breakdown then looks plausible and is wrong.
31    /// A `Vec` rather than a map because order is the useful part.
32    static MARKS: RefCell<Vec<(&'static str, f64)>>;
33}
34
35/// `CMS_PERF_LOG=1` — read once; this is on the hot path.
36pub fn enabled() -> bool {
37    static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
38    *ON.get_or_init(|| {
39        crate::config::flag("PERF_LOG")
40    })
41}
42
43/// Start a timer. Pair with [`mark`], or drop it to record nothing.
44#[must_use]
45pub fn start() -> Instant {
46    Instant::now()
47}
48
49/// Record `name` as having taken the time since `t`. No-op unless
50/// `CMS_PERF_LOG` is set.
51pub fn mark(name: &'static str, t: Instant) {
52    if !enabled() {
53        return;
54    }
55    let ms = t.elapsed().as_secs_f64() * 1000.0;
56    // `try_with` so a mark outside a request (CLI, tests) is a no-op
57    // rather than a panic.
58    let _ = MARKS.try_with(|m| m.borrow_mut().push((name, ms)));
59}
60
61/// Take and clear the marks recorded for the current request.
62fn take_marks() -> Vec<(&'static str, f64)> {
63    MARKS
64        .try_with(|m| std::mem::take(&mut *m.borrow_mut()))
65        .unwrap_or_default()
66}
67
68/// Axum middleware: time the whole request and emit the breakdown.
69///
70/// Mounted automatically by the CMS routers when `CMS_PERF_LOG` is set,
71/// so a host needs no wiring to profile a running site.
72pub async fn timing_middleware(
73    req: axum::extract::Request,
74    next: axum::middleware::Next,
75) -> axum::response::Response {
76    if !enabled() {
77        return next.run(req).await;
78    }
79    let method = req.method().clone();
80    let path = req
81        .uri()
82        .path_and_query()
83        .map(ToString::to_string)
84        .unwrap_or_else(|| req.uri().path().to_owned());
85
86    let t0 = Instant::now();
87    // Scope the marks to this request's task, so a handler's phases can
88    // never be credited to a neighbouring request.
89    let (resp, marks) = MARKS
90        .scope(RefCell::new(Vec::new()), async move {
91            let resp = next.run(req).await;
92            (resp, take_marks())
93        })
94        .await;
95    let total = t0.elapsed().as_secs_f64() * 1000.0;
96
97    // `unattributed` is the gap between the total and the phases the
98    // handler declared — middleware, extractors, serialisation, and any
99    // path with no marks at all.
100    let attributed: f64 = marks.iter().map(|(_, ms)| ms).sum();
101    let detail = marks
102        .iter()
103        .map(|(n, ms)| format!("{n}={ms:.1}"))
104        .collect::<Vec<_>>()
105        .join(" ");
106
107    tracing::info!(
108        target: "cms::perf",
109        "PERF {method} {path} -> {status} in {total:.1}ms | {detail} unattributed={gap:.1}",
110        status = resp.status().as_u16(),
111        gap = (total - attributed).max(0.0),
112    );
113    resp
114}
115
116/// Wrap `router` in the timing middleware when profiling is enabled.
117#[must_use]
118pub fn instrument(router: axum::Router) -> axum::Router {
119    if enabled() {
120        router.layer(axum::middleware::from_fn(timing_middleware))
121    } else {
122        router
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129
130    #[test]
131    fn marking_outside_a_request_is_a_no_op() {
132        // No task-local scope here: `mark` must not panic, and there is
133        // nothing to collect.
134        mark("phase", start());
135        assert!(take_marks().is_empty());
136    }
137
138    #[tokio::test]
139    async fn marks_are_scoped_to_their_own_task() {
140        // Two concurrent tasks must not see each other's marks — the
141        // exact failure a thread-local would produce under tokio.
142        let one = MARKS.scope(RefCell::new(Vec::new()), async {
143            let _ = MARKS.try_with(|m| m.borrow_mut().push(("a", 1.0)));
144            tokio::task::yield_now().await;
145            take_marks()
146        });
147        let two = MARKS.scope(RefCell::new(Vec::new()), async {
148            let _ = MARKS.try_with(|m| m.borrow_mut().push(("b", 2.0)));
149            tokio::task::yield_now().await;
150            take_marks()
151        });
152        let (a, b) = tokio::join!(one, two);
153        assert_eq!(a, vec![("a", 1.0)]);
154        assert_eq!(b, vec![("b", 2.0)]);
155    }
156}