Skip to main content

cargo_critpath/
timings.rs

1//! Reading per-unit weights out of `cargo build --timings`.
2//!
3//! There is no JSON timing output on any channel: `--timings` is a valueless flag and
4//! `--timings=json` is rejected. The report is HTML with JavaScript data islands embedded in it,
5//! and the array literals in those islands are valid JSON, so they are located by their assignment
6//! and handed to `serde_json`. No HTML parser is involved, and none would make an undocumented
7//! format less fragile.
8
9use serde_json::Value;
10
11use critpath_core::Millis;
12
13use crate::error::ParseError;
14
15/// What the timing report says a unit is.
16///
17/// The report's `target` field is a display string rather than structured data, and it renders every
18/// library target as the empty string. A plain rlib, a procedural macro, a `cdylib` and a `dylib`
19/// are therefore indistinguishable here, which is one of the two reasons the verbose log is needed
20/// as well.
21#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
22#[non_exhaustive]
23pub enum TimingTarget {
24    /// A library of some sort.
25    Library,
26    /// Compiling a build script.
27    BuildScriptCompile,
28    /// Running a build script that was already compiled.
29    BuildScriptRun,
30    /// A named target, such as `` rg "bin" ``.
31    Named {
32        /// The target's own name, which for a binary is the binary's name rather than the package's.
33        name: String,
34        /// The target kind Cargo printed, such as `bin`, `test` or `bench`.
35        kind: String,
36    },
37    /// Something this parser has not seen, kept verbatim.
38    Other(String),
39}
40
41impl TimingTarget {
42    /// A short name for the target, for display and for the machine-readable output's label.
43    #[must_use]
44    pub fn label(&self) -> &str {
45        match self {
46            Self::Library => "lib",
47            Self::BuildScriptCompile => "build-script",
48            Self::BuildScriptRun => "build-script (run)",
49            Self::Named { name, .. } => name,
50            Self::Other(text) => text,
51        }
52    }
53}
54
55/// One entry of the report's `UNIT_DATA` array.
56#[derive(Clone, Debug, PartialEq, Eq)]
57#[non_exhaustive]
58pub struct TimingUnit {
59    /// The report's own `i`, which is the unit's index in Cargo's sorted unit list. The array is
60    /// ordered by start time, so this is a permutation rather than the position, and the
61    /// `unblocked_*` fields refer to it.
62    pub index: usize,
63    /// Position in the array, which is start order.
64    pub position: usize,
65    /// The package's name, which the report states authoritatively.
66    pub package: String,
67    /// The package's version.
68    pub version: String,
69    /// What sort of target this is, as far as the report can say.
70    pub target: TimingTarget,
71    /// The features the unit was compiled with, sorted. These separate two instances of one package
72    /// at one version when the rest of the report cannot.
73    pub features: Vec<String>,
74    /// When the unit started, measured from the beginning of the build.
75    pub start: Millis,
76    /// How long the unit took.
77    pub duration: Millis,
78    /// How far into the unit its `frontend` section ended, which is when metadata became available,
79    /// clamped to the unit's own duration.
80    pub metadata_at: Option<Millis>,
81    /// Units this one unblocked by finishing. **Not the dependency graph**: only the units for which
82    /// this one happened to be the last remaining blocker, which covered 51% of the real edges on a
83    /// measured 28-unit build. Useful as a cross-check, useless as a source.
84    pub unblocked: Vec<usize>,
85    /// Units this one unblocked by emitting its metadata. Partial in the same way.
86    pub unblocked_rmeta: Vec<usize>,
87}
88
89/// Everything one timing report described.
90#[derive(Clone, Debug, PartialEq, Eq)]
91#[non_exhaustive]
92pub struct TimingReport {
93    /// Every unit, in the order the report listed them, which is start order.
94    pub units: Vec<TimingUnit>,
95    /// Units the build reused from the cache. The analysis requires this to be zero.
96    pub fresh_units: usize,
97    /// Units the build actually compiled.
98    pub dirty_units: usize,
99    /// Units in the build.
100    pub total_units: usize,
101    /// The `-j` the build ran with, from `Max concurrency: N (jobs=J ncpu=C)`.
102    pub jobs: Option<u32>,
103    /// The machine's processor count, from the same row.
104    pub cpus: Option<u32>,
105    /// The peak number of units Cargo actually had in flight. This can exceed `jobs`, because a
106    /// build-script execution is not a compiler process and takes no compile token.
107    pub max_concurrency: Option<u32>,
108    /// The profile the build used.
109    pub profile: Option<String>,
110    /// The `rustc` version, as the report's header states it.
111    pub rustc_version: Option<String>,
112    /// The host triple.
113    pub host: Option<String>,
114    /// The target triple.
115    pub target: Option<String>,
116    /// Cargo's own total for the build, which includes everything outside the unit model.
117    pub reported_total: Option<Millis>,
118    /// The targets the build was asked for, as one display string.
119    pub targets: Option<String>,
120    /// When the build started, as an RFC 3339 timestamp, exactly as the report wrote it.
121    pub build_start: Option<String>,
122}
123
124impl TimingReport {
125    /// The last unit's end minus the first unit's start: the part of the build that compiled things.
126    ///
127    /// Predictions are compared against this rather than against Cargo's reported total, because a
128    /// registry update or a crate download sits on the same clock and is not work any graph
129    /// transformation can shorten.
130    #[must_use]
131    pub fn compilation_span(&self) -> Millis {
132        let first = self.units.iter().map(|u| u.start).min();
133        let last = self
134            .units
135            .iter()
136            .map(|u| u.start.saturating_add(u.duration))
137            .max();
138        match (first, last) {
139            (Some(first), Some(last)) => last.saturating_sub(first),
140            _ => Millis::ZERO,
141        }
142    }
143
144    /// Cargo's reported total minus the compilation span: fetching, resolution, and anything else
145    /// outside the unit model.
146    ///
147    /// Reported separately rather than folded in. A build that spent 28 s downloading and 4.7 s
148    /// compiling is not a 32.5 s compilation problem.
149    #[must_use]
150    pub fn excluded_prefix(&self) -> Millis {
151        match self.reported_total {
152            Some(total) => total.saturating_sub(self.compilation_span()),
153            None => Millis::ZERO,
154        }
155    }
156}
157
158/// Reads a `cargo-timing.html` report.
159///
160/// # Errors
161///
162/// [`ParseError::NoUnitData`] or [`ParseError::TruncatedArray`] if the data islands are absent or
163/// incomplete, [`ParseError::BadUnitField`] if an entry has a shape this parser does not know, and
164/// [`ParseError::FreshUnits`] if the build reused cached units, whose recorded durations are zero.
165pub fn parse(text: &str) -> Result<TimingReport, ParseError> {
166    crate::error::reject_wide_text(text, "timing report")?;
167    // The unit array is located first, so that a file which is not a timing report at all is named
168    // as such rather than as a file with a missing table row.
169    let raw = array_literal(text, "UNIT_DATA")?.ok_or(ParseError::NoUnitData)?;
170
171    let summary = summary_table(text)?;
172    let fresh_units = summary.number("Fresh units")?;
173    let dirty_units = summary.number("Dirty units")?;
174    let total_units = summary
175        .number("Total units")
176        .unwrap_or_else(|_| fresh_units.saturating_add(dirty_units));
177    if fresh_units > 0 {
178        return Err(ParseError::FreshUnits {
179            fresh: fresh_units,
180            total: total_units,
181        });
182    }
183
184    let value: Value = serde_json::from_str(&raw).map_err(|e| ParseError::MalformedArray {
185        name: "UNIT_DATA".to_owned(),
186        detail: e.to_string(),
187    })?;
188    let entries = value.as_array().ok_or_else(|| ParseError::MalformedArray {
189        name: "UNIT_DATA".to_owned(),
190        detail: "the literal is not an array".to_owned(),
191    })?;
192
193    let mut units = Vec::with_capacity(entries.len());
194    for (position, entry) in entries.iter().enumerate() {
195        units.push(unit(entry, position)?);
196    }
197
198    let (max_concurrency, jobs, cpus) = concurrency_row(&summary);
199    let (rustc_version, host, target) = compiler_row(&summary);
200
201    Ok(TimingReport {
202        units,
203        fresh_units,
204        dirty_units,
205        total_units,
206        jobs,
207        cpus,
208        max_concurrency,
209        profile: summary.text("Profile"),
210        rustc_version,
211        host,
212        target,
213        reported_total: summary.text("Total time").and_then(|v| seconds_prefix(&v)),
214        targets: summary.text("Targets"),
215        build_start: summary.text("Build start"),
216    })
217}
218
219fn unit(entry: &Value, position: usize) -> Result<TimingUnit, ParseError> {
220    let bad = |field: &'static str, expected: &'static str| ParseError::BadUnitField {
221        entry: position,
222        field,
223        expected,
224    };
225
226    let index = entry
227        .get("i")
228        .and_then(Value::as_u64)
229        .ok_or_else(|| bad("i", "a unit index"))? as usize;
230    let package = entry
231        .get("name")
232        .and_then(Value::as_str)
233        .ok_or_else(|| bad("name", "a package name"))?
234        .to_owned();
235    let version = entry
236        .get("version")
237        .and_then(Value::as_str)
238        .unwrap_or_default()
239        .to_owned();
240    let display = entry
241        .get("target")
242        .and_then(Value::as_str)
243        .ok_or_else(|| bad("target", "a target display string"))?;
244    let start_seconds = entry
245        .get("start")
246        .and_then(Value::as_f64)
247        .ok_or_else(|| bad("start", "a number of seconds"))?;
248    let duration_seconds = entry
249        .get("duration")
250        .and_then(Value::as_f64)
251        .ok_or_else(|| bad("duration", "a number of seconds"))?;
252
253    let start = millis_from_seconds(start_seconds, position)?;
254    let duration = millis_from_seconds(duration_seconds, position)?;
255
256    let mut features: Vec<String> = entry
257        .get("features")
258        .and_then(Value::as_array)
259        .map(|items| {
260            items
261                .iter()
262                .filter_map(Value::as_str)
263                .map(str::to_owned)
264                .collect()
265        })
266        .unwrap_or_default();
267    features.sort();
268    features.dedup();
269
270    // `sections` is `[[name, {start, end}], …]` with times relative to the unit's own start. On
271    // stable it is present exactly for pipelined units.
272    let frontend_end = entry
273        .get("sections")
274        .and_then(Value::as_array)
275        .and_then(|sections| {
276            sections.iter().find_map(|section| {
277                let pair = section.as_array()?;
278                if pair.first().and_then(Value::as_str)? != "frontend" {
279                    return None;
280                }
281                pair.get(1)?.get("end")?.as_f64()
282            })
283        });
284    let metadata_at = match frontend_end {
285        Some(seconds) => Some(millis_from_seconds(seconds, position)?.max(Millis::ZERO)),
286        None => None,
287    };
288    // Metadata cannot be emitted after the unit that emits it has ended, and the core rejects a
289    // graph that claims otherwise, so a section that overruns is clamped here where the reason is
290    // visible rather than turned into an error the user cannot act on.
291    let metadata_at = metadata_at.map(|at| if at > duration { duration } else { at });
292
293    Ok(TimingUnit {
294        index,
295        position,
296        package,
297        version,
298        target: target_of(display),
299        features,
300        start,
301        duration,
302        metadata_at,
303        unblocked: indices(entry.get("unblocked_units")),
304        unblocked_rmeta: indices(entry.get("unblocked_rmeta_units")),
305    })
306}
307
308fn indices(value: Option<&Value>) -> Vec<usize> {
309    value
310        .and_then(Value::as_array)
311        .map(|items| {
312            items
313                .iter()
314                .filter_map(Value::as_u64)
315                .map(|i| i as usize)
316                .collect()
317        })
318        .unwrap_or_default()
319}
320
321/// The one place a report's floating-point seconds become integer milliseconds.
322///
323/// Cargo writes two decimal places, so rounding to the nearest millisecond loses nothing that was
324/// ever measured. A value that is not a finite, non-negative number of seconds small enough to be
325/// counted in milliseconds is refused rather than saturated, because a saturated weight would look
326/// like a real measurement.
327fn millis_from_seconds(seconds: f64, entry: usize) -> Result<Millis, ParseError> {
328    const LIMIT: f64 = 1e15;
329    if !seconds.is_finite() || !(0.0..=LIMIT).contains(&seconds) {
330        return Err(ParseError::DurationOutOfRange { entry, seconds });
331    }
332    Ok(Millis::new((seconds * 1000.0).round() as u64))
333}
334
335fn target_of(display: &str) -> TimingTarget {
336    // The observed alphabet, note the leading space on everything but a library.
337    match display {
338        "" => return TimingTarget::Library,
339        " build-script" => return TimingTarget::BuildScriptCompile,
340        " build-script (run)" => return TimingTarget::BuildScriptRun,
341        _ => {}
342    }
343    // ` name "kind"`
344    let trimmed = display.trim();
345    if let Some((name, rest)) = trimmed.split_once(' ') {
346        let kind = rest.trim().trim_matches('"');
347        if !name.is_empty() && !kind.is_empty() && !kind.contains(char::is_whitespace) {
348            return TimingTarget::Named {
349                name: name.to_owned(),
350                kind: kind.to_owned(),
351            };
352        }
353    }
354    TimingTarget::Other(trimmed.to_owned())
355}
356
357/// `12 (jobs=10 ncpu=10)` split into its three numbers.
358fn concurrency_row(summary: &Summary) -> (Option<u32>, Option<u32>, Option<u32>) {
359    let Some(value) = summary.text("Max concurrency") else {
360        return (None, None, None);
361    };
362    let peak = value.split_whitespace().next().and_then(|n| n.parse().ok());
363    let field = |name: &str| {
364        value
365            .split(|c: char| c.is_whitespace() || c == '(' || c == ')')
366            .find_map(|part| part.strip_prefix(name)?.parse().ok())
367    };
368    (peak, field("jobs="), field("ncpu="))
369}
370
371/// `rustc 1.95.0 (…)<br>Host: …<br>Target: …` split into its three parts.
372fn compiler_row(summary: &Summary) -> (Option<String>, Option<String>, Option<String>) {
373    let Some(raw) = summary.raw("rustc") else {
374        return (None, None, None);
375    };
376    let mut version = None;
377    let mut host = None;
378    let mut target = None;
379    for part in raw.split("<br>") {
380        let text = strip_tags(part);
381        if let Some(rest) = text.strip_prefix("Host:") {
382            host = Some(rest.trim().to_owned());
383        } else if let Some(rest) = text.strip_prefix("Target:") {
384            target = Some(rest.trim().to_owned());
385        } else if !text.is_empty() && version.is_none() {
386            version = Some(text);
387        }
388    }
389    (version, host, target)
390}
391
392/// The leading `61.2s` of `61.2s (1m 1.2s)`.
393fn seconds_prefix(value: &str) -> Option<Millis> {
394    let digits: String = value
395        .chars()
396        .take_while(|c| c.is_ascii_digit() || *c == '.')
397        .collect();
398    let seconds: f64 = digits.parse().ok()?;
399    millis_from_seconds(seconds, 0).ok()
400}
401
402/// The report's first table, as label-and-value pairs in the order they appeared.
403struct Summary {
404    rows: Vec<(String, String)>,
405}
406
407impl Summary {
408    fn raw(&self, label: &str) -> Option<&str> {
409        self.rows
410            .iter()
411            .find(|(name, _)| name == label)
412            .map(|(_, value)| value.as_str())
413    }
414
415    fn text(&self, label: &str) -> Option<String> {
416        self.raw(label).map(strip_tags)
417    }
418
419    fn number(&self, label: &'static str) -> Result<usize, ParseError> {
420        let value = self
421            .text(label)
422            .ok_or(ParseError::MissingSummaryRow { row: label })?;
423        value.trim().parse().map_err(|_| ParseError::BadSummaryRow {
424            row: label,
425            value,
426            expected: "a count",
427        })
428    }
429}
430
431fn summary_table(text: &str) -> Result<Summary, ParseError> {
432    let start = text.find("<table").ok_or(ParseError::NoSummaryTable)?;
433    let rest = text.get(start..).ok_or(ParseError::NoSummaryTable)?;
434    let end = rest.find("</table>").ok_or(ParseError::NoSummaryTable)?;
435    let table = rest.get(..end).ok_or(ParseError::NoSummaryTable)?;
436
437    // The summary table is a flat list of alternating label and value cells, so the cells are
438    // collected and paired. Matching `<tr>` blocks would buy nothing and would break on the
439    // whitespace Cargo puts between them.
440    let mut cells = Vec::new();
441    let mut remaining = table;
442    while let Some(open) = remaining.find("<td>") {
443        let after = match remaining.get(open.saturating_add(4)..) {
444            Some(after) => after,
445            None => break,
446        };
447        let Some(close) = after.find("</td>") else {
448            break;
449        };
450        if let Some(cell) = after.get(..close) {
451            cells.push(cell);
452        }
453        remaining = match after.get(close.saturating_add(5)..) {
454            Some(rest) => rest,
455            None => break,
456        };
457    }
458
459    let mut rows = Vec::new();
460    let mut pairs = cells.chunks_exact(2);
461    for pair in &mut pairs {
462        let (Some(label), Some(value)) = (pair.first(), pair.get(1)) else {
463            continue;
464        };
465        let label = strip_tags(label);
466        let label = label.trim().trim_end_matches(':').to_owned();
467        rows.push((label, (*value).to_owned()));
468    }
469    if rows.is_empty() {
470        return Err(ParseError::NoSummaryTable);
471    }
472    Ok(Summary { rows })
473}
474
475/// A cell's text: markup removed, entities decoded, whitespace collapsed at the ends.
476fn strip_tags(html: &str) -> String {
477    let mut out = String::with_capacity(html.len());
478    let mut depth = 0usize;
479    for c in html.chars() {
480        match c {
481            '<' => depth = depth.saturating_add(1),
482            '>' => depth = depth.saturating_sub(1),
483            _ if depth == 0 => out.push(c),
484            _ => {}
485        }
486    }
487    decode_entities(out.trim())
488}
489
490fn decode_entities(text: &str) -> String {
491    if !text.contains('&') {
492        return text.to_owned();
493    }
494    let mut out = String::with_capacity(text.len());
495    let mut rest = text;
496    while let Some(at) = rest.find('&') {
497        if let Some(head) = rest.get(..at) {
498            out.push_str(head);
499        }
500        let tail = rest.get(at..).unwrap_or("");
501        let replacement = [
502            ("&amp;", "&"),
503            ("&lt;", "<"),
504            ("&gt;", ">"),
505            ("&quot;", "\""),
506            ("&#39;", "'"),
507        ]
508        .into_iter()
509        .find(|(entity, _)| tail.starts_with(entity));
510        match replacement {
511            Some((entity, decoded)) => {
512                out.push_str(decoded);
513                rest = tail.get(entity.len()..).unwrap_or("");
514            }
515            None => {
516                out.push('&');
517                rest = tail.get(1..).unwrap_or("");
518            }
519        }
520    }
521    out.push_str(rest);
522    out
523}
524
525/// The array literal assigned to `const <name> = […];`, with brackets matched so that a truncated
526/// file is distinguishable from a malformed one.
527fn array_literal(text: &str, name: &str) -> Result<Option<String>, ParseError> {
528    let needle = format!("const {name} = ");
529    let Some(at) = text.find(&needle) else {
530        return Ok(None);
531    };
532    let rest = text
533        .get(at.saturating_add(needle.len())..)
534        .unwrap_or_default();
535    let mut depth = 0usize;
536    let mut in_string = false;
537    let mut escaped = false;
538    for (offset, c) in rest.char_indices() {
539        if in_string {
540            if escaped {
541                escaped = false;
542            } else if c == '\\' {
543                escaped = true;
544            } else if c == '"' {
545                in_string = false;
546            }
547            continue;
548        }
549        match c {
550            '"' => in_string = true,
551            '[' | '{' => depth = depth.saturating_add(1),
552            ']' | '}' => {
553                depth = depth.saturating_sub(1);
554                if depth == 0 {
555                    let end = offset.saturating_add(c.len_utf8());
556                    return Ok(rest.get(..end).map(str::to_owned));
557                }
558            }
559            _ => {}
560        }
561    }
562    Err(ParseError::TruncatedArray {
563        name: name.to_owned(),
564    })
565}