1use std::collections::BTreeMap;
10
11use serde::{Deserialize, Serialize};
12
13use super::facts::{samples_between, usage_of};
14use super::log::{TITLE_SOURCE_MAX, title};
15use super::{Job, JobState, JobSummary, Sample, Step};
16use crate::api::{SAMPLE_INTERVAL, Tone, cpu_time, duration, in_cores};
17use crate::config::ByteSize;
18
19#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
21pub struct CompareQuery {
22 pub with: Option<u64>,
24}
25
26#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
28#[serde(rename_all = "kebab-case", tag = "kind")]
29pub enum Baseline {
30 Chosen {
32 job: u64,
34 branch: Option<String>,
36 queued_at: u64,
38 asked: bool,
40 },
41 Unavailable {
43 reason: Unavailable,
45 },
46 Incompatible {
48 job: u64,
50 },
51 #[serde(other)]
53 Other,
54}
55
56impl Baseline {
57 pub fn against(&self, now: u64) -> Option<String> {
60 let Baseline::Chosen {
61 job,
62 branch,
63 queued_at,
64 ..
65 } = self
66 else {
67 return None;
68 };
69 let on = branch
70 .as_deref()
71 .map(|branch| format!(" on {}", title(branch)))
72 .unwrap_or_default();
73 Some(format!(
74 "against job {job}{on}, queued {}",
75 crate::api::ago(*queued_at, now)
76 ))
77 }
78
79 pub fn words(&self) -> Option<String> {
81 match self {
82 Baseline::Chosen { .. } => None,
83 Baseline::Unavailable { reason } => Some(reason.words().to_owned()),
84 Baseline::Incompatible { job } => Some(format!(
85 "job {job} is not a run of this job: another repository, workflow or name"
86 )),
87 Baseline::Other => Some("not compared".to_owned()),
88 }
89 }
90}
91
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
94#[serde(rename_all = "kebab-case")]
95pub enum Unavailable {
96 NoEarlierSuccess,
98 UnknownWorkflow,
100 UnknownBranch,
102 #[serde(other)]
104 Other,
105}
106
107impl Unavailable {
108 pub fn words(self) -> &'static str {
110 match self {
111 Unavailable::NoEarlierSuccess => {
112 "no earlier run of this job on its branch succeeded here"
113 }
114 Unavailable::UnknownWorkflow => {
115 "its workflow is unknown, so no earlier run is known to be the same job"
116 }
117 Unavailable::UnknownBranch => {
118 "its branch is unknown, so no earlier run is known to be on it"
119 }
120 Unavailable::Other => "no baseline",
121 }
122 }
123}
124
125#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
127#[serde(rename_all = "kebab-case")]
128pub enum FigureKind {
129 Wait,
131 Run,
133 MemoryPeak,
135 CpuTime,
137 CpuAverage,
139 Received,
141 StepTime,
143 StepMemory,
145 StepCpu,
147 #[serde(other)]
149 Other,
150}
151
152impl FigureKind {
153 pub fn label(self) -> &'static str {
155 match self {
156 FigureKind::Wait => "Wait",
157 FigureKind::Run => "Run time",
158 FigureKind::MemoryPeak | FigureKind::StepMemory => "Memory peak",
159 FigureKind::CpuTime => "CPU time",
160 FigureKind::CpuAverage | FigureKind::StepCpu => "Average CPU",
161 FigureKind::Received => "Received",
162 FigureKind::StepTime => "Time",
163 FigureKind::Other => "Figure",
164 }
165 }
166
167 pub fn words(self, value: u64) -> String {
169 match self {
170 FigureKind::Wait | FigureKind::Run | FigureKind::StepTime => duration(value),
171 FigureKind::MemoryPeak | FigureKind::Received | FigureKind::StepMemory => {
172 ByteSize(value).to_string()
173 }
174 FigureKind::CpuTime => cpu_time(value),
175 FigureKind::CpuAverage | FigureKind::StepCpu => in_cores(value),
176 FigureKind::Other => value.to_string(),
177 }
178 }
179
180 fn is_cost(self) -> bool {
182 matches!(
183 self,
184 FigureKind::Wait
185 | FigureKind::Run
186 | FigureKind::MemoryPeak
187 | FigureKind::CpuTime
188 | FigureKind::StepTime
189 | FigureKind::StepMemory
190 )
191 }
192
193 fn floor(self) -> u64 {
195 match self {
196 FigureKind::Wait | FigureKind::Run | FigureKind::StepTime => 5,
197 _ => 0,
198 }
199 }
200}
201
202#[derive(Debug, Clone, Copy, PartialEq, Eq)]
204pub enum ChangeKind {
205 More,
207 Less,
209 Same,
211 Unknown,
213}
214
215#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
217pub struct FigureDelta {
218 pub figure: FigureKind,
220 pub this: Option<u64>,
222 pub baseline: Option<u64>,
224 #[serde(default)]
226 pub sampled: bool,
227}
228
229impl FigureDelta {
230 fn new(figure: FigureKind, this: Option<u64>, baseline: Option<u64>) -> FigureDelta {
231 FigureDelta {
232 figure,
233 this,
234 baseline,
235 sampled: false,
236 }
237 }
238
239 pub fn this_words(&self) -> String {
241 self.this
242 .map_or_else(|| "unknown".to_owned(), |value| self.figure.words(value))
243 }
244
245 pub fn baseline_words(&self) -> String {
247 self.baseline
248 .map_or_else(|| "unknown".to_owned(), |value| self.figure.words(value))
249 }
250
251 pub fn change(&self) -> ChangeKind {
253 match (self.this, self.baseline) {
254 (Some(this), Some(baseline)) if this > baseline => ChangeKind::More,
255 (Some(this), Some(baseline)) if this < baseline => ChangeKind::Less,
256 (Some(_), Some(_)) => ChangeKind::Same,
257 _ => ChangeKind::Unknown,
258 }
259 }
260
261 pub fn change_words(&self) -> String {
263 let (Some(this), Some(baseline)) = (self.this, self.baseline) else {
264 return "unknown".to_owned();
265 };
266 let (sign, by) = match self.change() {
267 ChangeKind::More => ('+', this - baseline),
268 ChangeKind::Less => ('-', baseline - this),
269 ChangeKind::Same | ChangeKind::Unknown => return "same".to_owned(),
270 };
271 let words = format!("{sign}{}", self.figure.words(by));
272 match u128::from(by)
273 .saturating_mul(100)
274 .checked_div(u128::from(baseline))
275 {
276 Some(percent) => format!("{words} ({sign}{percent}%)"),
277 None => words,
278 }
279 }
280
281 pub fn tone(&self) -> Tone {
284 let (Some(this), Some(baseline)) = (self.this, self.baseline) else {
285 return Tone::Quiet;
286 };
287 let by = this.abs_diff(baseline);
288 let marked = by >= self.figure.floor() && u128::from(by) * 10 > u128::from(baseline);
289 match self.change() {
290 ChangeKind::More if marked && self.figure.is_cost() => Tone::Warn,
291 ChangeKind::Less if marked && self.figure.is_cost() => Tone::Good,
292 _ => Tone::Neutral,
293 }
294 }
295}
296
297#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
299#[serde(rename_all = "kebab-case")]
300pub enum StepMatch {
301 Matched,
303 OnlyThis,
305 OnlyBaseline,
307 Ambiguous,
309 #[serde(other)]
311 Other,
312}
313
314impl StepMatch {
315 pub fn words(self) -> Option<&'static str> {
318 match self {
319 StepMatch::Matched => None,
320 StepMatch::OnlyThis => Some("only in this run"),
321 StepMatch::OnlyBaseline => Some("only in the baseline"),
322 StepMatch::Ambiguous => Some("name not unique, not compared"),
323 StepMatch::Other => Some("not compared"),
324 }
325 }
326}
327
328#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
330pub struct StepDelta {
331 pub name: String,
333 pub matched: StepMatch,
335 pub this: Option<u32>,
337 pub baseline: Option<u32>,
339 pub time: FigureDelta,
341 #[serde(default, skip_serializing_if = "Option::is_none")]
343 pub memory: Option<FigureDelta>,
344 #[serde(default, skip_serializing_if = "Option::is_none")]
346 pub cpu: Option<FigureDelta>,
347}
348
349pub(crate) const SAMPLE_GAP_INTERVALS: u64 = 3;
352
353#[derive(Debug, Clone, Copy, PartialEq, Eq)]
355pub struct StepUsage {
356 pub number: u32,
358 pub first: u64,
360 pub last: u64,
362 pub widest_gap: u64,
364 pub memory_peak: u64,
366 pub cpu_average: u64,
368}
369
370impl StepUsage {
371 pub fn of(samples: &[Sample], steps: &[Step]) -> Vec<StepUsage> {
374 steps
375 .iter()
376 .filter_map(|step| {
377 let (from, to) = (step.started_at?, step.completed_at?);
378 let inside = samples_between(samples, from, to);
379 let usage = usage_of(&inside)?;
380 let widest_gap = inside
381 .windows(2)
382 .map(|pair| pair[1].at.saturating_sub(pair[0].at))
383 .max()
384 .unwrap_or(0);
385 Some(StepUsage {
386 number: step.number,
387 first: inside.first()?.at,
388 last: inside.last()?.at,
389 widest_gap,
390 memory_peak: usage.memory_peak,
391 cpu_average: usage.cpu_average,
392 })
393 })
394 .collect()
395 }
396}
397
398#[derive(Debug, Clone, PartialEq, Eq)]
400pub enum BaselineRead {
401 Found {
403 job: Box<JobSummary>,
405 steps: ComparedSteps,
407 usage: Vec<StepUsage>,
409 asked: bool,
411 },
412 Unavailable(Unavailable),
414 Incompatible(u64),
416}
417
418#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
420pub struct JobComparison {
421 pub job: u64,
423 pub baseline: Baseline,
425 pub figures: Vec<FigureDelta>,
427 pub steps: Vec<StepDelta>,
429 #[serde(default, skip_serializing_if = "is_false")]
432 pub steps_cut: bool,
433}
434
435#[expect(
436 clippy::trivially_copy_pass_by_ref,
437 reason = "serde's skip_serializing_if passes a reference"
438)]
439fn is_false(value: &bool) -> bool {
440 !value
441}
442
443pub const COMPARE_STEPS_MAX: usize = 500;
445
446pub const COMPARE_STEP_BYTES: usize = 128 * 1024;
449
450#[derive(Debug, Clone, Default, PartialEq, Eq)]
453pub struct ComparedSteps {
454 pub steps: Vec<Step>,
456 pub cut: bool,
458}
459
460impl ComparedSteps {
461 pub fn of(steps: &[Step]) -> ComparedSteps {
463 let mut ordered: Vec<&Step> = steps.iter().collect();
464 ordered.sort_by_key(|step| step.number);
465 let mut read = ComparedSteps::default();
466 for step in ordered {
467 let mut step = step.clone();
468 let cut = step.name.floor_char_boundary(TITLE_SOURCE_MAX);
469 step.name.truncate(cut);
470 if !read.push(step) {
471 read.cut = true;
472 break;
473 }
474 }
475 read
476 }
477
478 pub fn push(&mut self, step: Step) -> bool {
480 let bytes: usize = self.steps.iter().map(|step| step.name.len()).sum();
481 let full = self.steps.len() >= COMPARE_STEPS_MAX
482 || (!self.steps.is_empty() && bytes + step.name.len() > COMPARE_STEP_BYTES);
483 if !full {
484 self.steps.push(step);
485 }
486 !full
487 }
488}
489
490fn step_time(step: &Step) -> Option<u64> {
492 Some(step.completed_at?.saturating_sub(step.started_at?))
493}
494
495fn covers(usage: &StepUsage, step: &Step) -> bool {
499 let tolerance = SAMPLE_INTERVAL * SAMPLE_GAP_INTERVALS;
500 let (Some(from), Some(to)) = (step.started_at, step.completed_at) else {
501 return false;
502 };
503 usage.first.saturating_sub(from) <= tolerance
504 && to.saturating_sub(usage.last) <= tolerance
505 && usage.widest_gap <= tolerance
506}
507
508impl JobComparison {
509 pub fn same_job(job: &JobSummary, other: &JobSummary) -> bool {
512 other.id != job.id
513 && other.repository == job.repository
514 && job.workflow.is_some()
515 && other.workflow == job.workflow
516 && other.name == job.name
517 }
518
519 pub fn is_baseline(job: &JobSummary, other: &JobSummary) -> bool {
522 JobComparison::same_job(job, other)
523 && job.branch.is_some()
524 && other.branch == job.branch
525 && other.state == JobState::Completed
526 && other.conclusion.as_deref() == Some("success")
527 && other.runner.is_some()
528 && other.timeline.started_at.is_some()
529 && (other.timeline.queued_at, other.id) < (job.timeline.queued_at, job.id)
530 }
531
532 pub fn baseline_of<'history>(
535 job: &JobSummary,
536 history: &'history [JobSummary],
537 ) -> Result<&'history JobSummary, Unavailable> {
538 if job.workflow.is_none() {
539 return Err(Unavailable::UnknownWorkflow);
540 }
541 if job.branch.is_none() {
542 return Err(Unavailable::UnknownBranch);
543 }
544 history
545 .iter()
546 .filter(|other| JobComparison::is_baseline(job, other))
547 .max_by_key(|other| (other.timeline.queued_at, other.id))
548 .ok_or(Unavailable::NoEarlierSuccess)
549 }
550
551 pub fn in_history(
555 id: u64,
556 with: Option<u64>,
557 history: &[Job],
558 usage: impl Fn(&Job) -> Vec<StepUsage>,
559 ) -> Option<JobComparison> {
560 let find = |id: u64| history.iter().find(|job| job.summary.id == id);
561 let this = find(id)?;
562 let found = |other: &Job, asked: bool| BaselineRead::Found {
563 job: Box::new(other.summary.clone()),
564 steps: ComparedSteps::of(&other.steps),
565 usage: usage(other),
566 asked,
567 };
568 let baseline = if let Some(with) = with {
569 let other = find(with)?;
570 if JobComparison::same_job(&this.summary, &other.summary) {
571 found(other, true)
572 } else {
573 BaselineRead::Incompatible(with)
574 }
575 } else {
576 let summaries: Vec<JobSummary> =
577 history.iter().map(|job| job.summary.clone()).collect();
578 match JobComparison::baseline_of(&this.summary, &summaries) {
579 Ok(other) => find(other.id).map_or(
580 BaselineRead::Unavailable(Unavailable::NoEarlierSuccess),
581 |other| found(other, false),
582 ),
583 Err(reason) => BaselineRead::Unavailable(reason),
584 }
585 };
586 let (steps, usage) = match baseline {
587 BaselineRead::Found { .. } => (ComparedSteps::of(&this.steps), usage(this)),
588 _ => (ComparedSteps::default(), Vec::new()),
589 };
590 Some(JobComparison::of(&this.summary, &steps, &usage, baseline))
591 }
592
593 pub fn of(
596 job: &JobSummary,
597 steps: &ComparedSteps,
598 usage: &[StepUsage],
599 baseline: BaselineRead,
600 ) -> JobComparison {
601 let (other, other_steps, other_usage, asked) = match baseline {
602 BaselineRead::Found {
603 job,
604 steps,
605 usage,
606 asked,
607 } => (job, steps, usage, asked),
608 BaselineRead::Unavailable(reason) => {
609 return JobComparison::alone(job, Baseline::Unavailable { reason });
610 }
611 BaselineRead::Incompatible(other) => {
612 return JobComparison::alone(job, Baseline::Incompatible { job: other });
613 }
614 };
615 JobComparison {
616 job: job.id,
617 baseline: Baseline::Chosen {
618 job: other.id,
619 branch: other.branch.clone(),
620 queued_at: other.timeline.queued_at,
621 asked,
622 },
623 figures: figures(job, Some(&other)),
624 steps: deltas(&steps.steps, usage, &other_steps.steps, &other_usage),
625 steps_cut: steps.cut || other_steps.cut,
626 }
627 }
628
629 fn alone(job: &JobSummary, baseline: Baseline) -> JobComparison {
631 JobComparison {
632 job: job.id,
633 baseline,
634 figures: figures(job, None),
635 steps: Vec::new(),
636 steps_cut: false,
637 }
638 }
639
640 pub fn steps_cut_words(&self) -> Option<&'static str> {
642 self.steps_cut.then_some(
643 "some steps are not compared: a run has more steps, or longer step names, than a comparison reads",
644 )
645 }
646}
647
648fn figures(job: &JobSummary, baseline: Option<&JobSummary>) -> Vec<FigureDelta> {
650 let read = |job: &JobSummary, figure: FigureKind| -> Option<u64> {
651 let timeline = &job.timeline;
652 let metrics = &job.metrics;
653 match figure {
654 FigureKind::Wait => timeline
655 .started_at
656 .map(|started| started.saturating_sub(timeline.queued_at)),
657 _ if !job.state.is_final() => None,
658 FigureKind::Run => Some(timeline.finished_at?.saturating_sub(timeline.started_at?)),
659 FigureKind::MemoryPeak => metrics.memory_peak,
660 FigureKind::CpuTime => metrics.cpu_time,
661 FigureKind::CpuAverage => metrics.cpu_average,
662 FigureKind::Received => metrics.network_received,
663 _ => None,
664 }
665 };
666 [
667 FigureKind::Wait,
668 FigureKind::Run,
669 FigureKind::MemoryPeak,
670 FigureKind::CpuTime,
671 FigureKind::CpuAverage,
672 FigureKind::Received,
673 ]
674 .into_iter()
675 .map(|figure| {
676 FigureDelta::new(
677 figure,
678 read(job, figure),
679 baseline.and_then(|baseline| read(baseline, figure)),
680 )
681 })
682 .collect()
683}
684
685fn names(steps: &[Step]) -> BTreeMap<&str, usize> {
687 let mut names = BTreeMap::new();
688 for step in steps {
689 *names.entry(step.name.as_str()).or_insert(0) += 1;
690 }
691 names
692}
693
694fn deltas(
696 ours_steps: &[Step],
697 usage: &[StepUsage],
698 theirs_steps: &[Step],
699 other_usage: &[StepUsage],
700) -> Vec<StepDelta> {
701 let ours = names(ours_steps);
702 let theirs = names(theirs_steps);
703 let unique = |name: &str| {
704 ours.get(name).copied().unwrap_or(0) <= 1 && theirs.get(name).copied().unwrap_or(0) <= 1
705 };
706 let usage_of = |usage: &[StepUsage], step: &Step| {
707 usage
708 .iter()
709 .find(|usage| usage.number == step.number)
710 .filter(|usage| covers(usage, step))
711 .copied()
712 };
713 let sampled = |figure: FigureKind, this: u64, other: u64| FigureDelta {
714 figure,
715 this: Some(this),
716 baseline: Some(other),
717 sampled: true,
718 };
719 let mut deltas = Vec::new();
720 for step in ours_steps {
721 let paired = unique(&step.name)
722 .then(|| theirs_steps.iter().find(|theirs| theirs.name == step.name))
723 .flatten();
724 let matched = match (paired, unique(&step.name)) {
725 (Some(_), _) => StepMatch::Matched,
726 (None, false) => StepMatch::Ambiguous,
727 (None, true) => StepMatch::OnlyThis,
728 };
729 let ours_used = usage_of(usage, step);
730 let theirs_used = paired.and_then(|theirs| usage_of(other_usage, theirs));
731 let both = ours_used.zip(theirs_used);
732 deltas.push(StepDelta {
733 name: title(&step.name),
734 matched,
735 this: Some(step.number),
736 baseline: paired.map(|theirs| theirs.number),
737 time: FigureDelta::new(
738 FigureKind::StepTime,
739 step_time(step),
740 paired.and_then(step_time),
741 ),
742 memory: both.map(|(ours, theirs)| {
743 sampled(FigureKind::StepMemory, ours.memory_peak, theirs.memory_peak)
744 }),
745 cpu: both.map(|(ours, theirs)| {
746 sampled(FigureKind::StepCpu, ours.cpu_average, theirs.cpu_average)
747 }),
748 });
749 }
750 for theirs in theirs_steps {
751 let unpaired = !unique(&theirs.name) || !ours.contains_key(theirs.name.as_str());
752 if !unpaired {
753 continue;
754 }
755 deltas.push(StepDelta {
756 name: title(&theirs.name),
757 matched: if unique(&theirs.name) {
758 StepMatch::OnlyBaseline
759 } else {
760 StepMatch::Ambiguous
761 },
762 this: None,
763 baseline: Some(theirs.number),
764 time: FigureDelta::new(FigureKind::StepTime, None, step_time(theirs)),
765 memory: None,
766 cpu: None,
767 });
768 }
769 deltas
770}
771
772#[cfg(test)]
774#[cfg(any(feature = "host", feature = "client"))]
775mod tests;