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}