Skip to main content

runnerd_core/api/insights/
shown.rs

1//! What insights and the digest mean as every client shows them: each insight's labels and tone, how many warn,
2//! the window they come from, what the page says without any, and the digest's lines. Plain derivations of
3//! [`Insights`] and [`Digest`]; the dashboard, `runnerctl`, the TUI and notifications only lay them out.
4
5use super::{Digest, Insight, InsightKind, Insights, LongWait, Severity, WaitSpread};
6use crate::api::{HostMemory, Tone, duration};
7
8impl InsightKind {
9    /// Its name as a label: `Slower`, `Flaky`, `Near its cap`, `Cold cache`, `Memory pressure`, `CPU cap`,
10    /// `Host memory`, `Waits`, or `Insight` for a kind from a later release.
11    pub fn label(&self) -> &'static str {
12        match self {
13            InsightKind::Slower { .. } => "Slower",
14            InsightKind::Flaky { .. } => "Flaky",
15            InsightKind::NearCap { .. } => "Near its cap",
16            InsightKind::ColdCache { .. } => "Cold cache",
17            InsightKind::Throttled { .. } => "Memory pressure",
18            InsightKind::CpuHeld { .. } => "CPU cap",
19            InsightKind::HostHeld { .. } => "Host memory",
20            InsightKind::Waits { .. } => "Waits",
21            InsightKind::Unknown => "Insight",
22        }
23    }
24
25    /// Its name as one word, the API's `kind`: `slower`, `flaky`, `near-cap`, `cold-cache`, `throttled`,
26    /// `cpu-held`, `host-held` or `waits`; `unknown` for a kind from a later release.
27    pub fn word(&self) -> &'static str {
28        match self {
29            InsightKind::Slower { .. } => "slower",
30            InsightKind::Flaky { .. } => "flaky",
31            InsightKind::NearCap { .. } => "near-cap",
32            InsightKind::ColdCache { .. } => "cold-cache",
33            InsightKind::Throttled { .. } => "throttled",
34            InsightKind::CpuHeld { .. } => "cpu-held",
35            InsightKind::HostHeld { .. } => "host-held",
36            InsightKind::Waits { .. } => "waits",
37            InsightKind::Unknown => "unknown",
38        }
39    }
40}
41
42impl Insight {
43    /// What a [`HostHeld`](InsightKind::HostHeld) insight says: `3 jobs wait for the host's memory, the longest for
44    /// 42m 10s (halyard/api: CI / build); programs outside CI hold 30G, most java 9.3G and claude 5.1G. Closing programs
45    /// frees only part of that.` `longest` names the job that waited longest; `memory` is the
46    /// reading that names who holds the memory. The part the programs named leave is the kernel, compressed swap and
47    /// the many small programs, so the sentence never says closing them frees the whole figure.
48    pub fn host_held_sentence(
49        jobs: u32,
50        waited: u64,
51        longest: &str,
52        memory: &HostMemory,
53    ) -> String {
54        let who = if jobs == 1 {
55            "1 job waits".to_owned()
56        } else {
57            format!("{jobs} jobs wait")
58        };
59        format!(
60            "{who} for the host's memory, the longest for {} ({longest}); {}. Closing programs frees only part of \
61             that.",
62            duration(waited),
63            memory.outside_line()
64        )
65    }
66}
67
68impl Severity {
69    /// `warning` or `notice`.
70    pub fn label(self) -> &'static str {
71        match self {
72            Severity::Warning => "warning",
73            Severity::Notice => "notice",
74        }
75    }
76}
77
78impl Insight {
79    /// What it means for the reader, by its severity alone, whatever its kind: a warning is worth a look, a notice
80    /// a plain fact.
81    pub fn tone(&self) -> Tone {
82        match self.severity {
83            Severity::Warning => Tone::Warn,
84            Severity::Notice => Tone::Neutral,
85        }
86    }
87}
88
89impl Insights {
90    /// How many insights warn.
91    pub fn warning_count(&self) -> usize {
92        self.insights
93            .iter()
94            .filter(|insight| insight.severity == Severity::Warning)
95            .count()
96    }
97
98    /// How many insights warn, worded for the overview: `3 insights`; `None` when none does.
99    pub fn warning_line(&self) -> Option<String> {
100        match self.warning_count() {
101            0 => None,
102            1 => Some("1 insight".to_owned()),
103            count => Some(format!("{count} insights")),
104        }
105    }
106
107    /// The whole days its window covers.
108    pub fn days(&self) -> u64 {
109        self.until.saturating_sub(self.since) / 86_400
110    }
111
112    /// Where its insights come from: `from the last 30 days`.
113    pub fn window_line(&self) -> String {
114        format!("from the last {} days", self.days())
115    }
116
117    /// What it says without any insight: `nothing stands out from the last 30 days`.
118    pub fn empty_line(&self) -> String {
119        format!("nothing stands out {}", self.window_line())
120    }
121}
122
123impl WaitSpread {
124    /// `value`, one of its percentiles, when it has jobs to take it over; `None` to show none.
125    pub fn reading(&self, value: Option<u64>) -> Option<u64> {
126        value.filter(|_| self.jobs > 0)
127    }
128}
129
130impl Digest {
131    /// Its day in a line: `12 jobs finished, 2 failed`, then `, 1 new insight` when some are new.
132    pub fn summary_line(&self) -> String {
133        let jobs = if self.finished == 1 { "job" } else { "jobs" };
134        let line = format!("{} {jobs} finished, {} failed", self.finished, self.failed);
135        match self.new.len() {
136            0 => line,
137            1 => format!("{line}, 1 new insight"),
138            new => format!("{line}, {new} new insights"),
139        }
140    }
141}
142
143impl LongWait {
144    /// It in a line: `halyard/api CI / test waited 1m 30s`, or `halyard/api job 7 waited 1m 30s` until the daemon
145    /// knows the job's name.
146    pub fn line(&self) -> String {
147        format!(
148            "{} {} waited {}",
149            self.repository,
150            crate::api::job_title(self.workflow.as_deref(), &self.name, Some(self.job)),
151            duration(self.waited)
152        )
153    }
154}
155
156#[cfg(test)]
157mod tests;