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