mbx_cache_core/agent/stats.rs
1use std::collections::{BTreeMap, BTreeSet};
2
3/// Aggregate cache activity for one task session.
4///
5/// The agent produces these; nothing outside this crate has cause to build one.
6/// Saying so keeps a new counter from being a breaking change, which is what
7/// this type exists to accumulate -- reach for [`AgentStats::default`] and
8/// assign the fields a test needs.
9#[derive(Debug, Clone, Default, PartialEq, Eq)]
10#[non_exhaustive]
11pub struct AgentStats {
12 /// Cumulative exclusive wrapper durations, including an unattributed remainder.
13 pub wrapper_phases_ns: BTreeMap<String, u64>,
14 /// End-to-end lifetime of the task-scoped cache session.
15 pub session_duration_ns: u64,
16 /// Number of action-result lookups.
17 pub lookups: u64,
18 /// Compilations no action-result lookup was possible for, because no usable
19 /// action key was available.
20 ///
21 /// Counted separately from a miss, which is a lookup that found nothing.
22 /// Both compile, but only a miss says a lookup happened.
23 pub unconsulted: u64,
24 /// Number of lookups that found a valid local action result.
25 pub hits: u64,
26 /// Number of newly stored content-addressed objects.
27 pub stores: u64,
28 /// Total size of newly stored objects.
29 pub stored_bytes: u64,
30 /// Number of cache hits compiled again for qualification.
31 pub verifications: u64,
32 /// Number of qualification builds that diverged from the cached result.
33 pub divergences: u64,
34 /// CAS payload bytes downloaded from the remote cache.
35 pub downloaded_bytes: u64,
36 /// CAS payload bytes uploaded to the remote cache.
37 pub uploaded_bytes: u64,
38 /// Objects published to the remote cache after the build asked for them.
39 ///
40 /// A store request returns once the object is in the local CAS, so the
41 /// upload it implies happens off the build's critical path. This counts the
42 /// blobs and action results that publication actually completed for.
43 pub background_uploads: u64,
44 /// Queued uploads that did not publish, having been reported and recovered
45 /// from.
46 pub background_upload_failures: u64,
47 /// Framed requests that published several blobs at once.
48 pub remote_blob_pack_uploads: u64,
49 /// Blobs published through those framed requests.
50 pub remote_blob_pack_upload_blobs: u64,
51 /// Time the session spent waiting for queued uploads once the build ended.
52 pub upload_drain_duration_ns: u64,
53 /// Complete actions staged before an adapter requested them.
54 pub prefetched_actions: u64,
55 /// Predictions carried by the task manifest this session loaded.
56 ///
57 /// Zero means no earlier build left a manifest behind -- a genuinely cold
58 /// start. Together with `lookups`, this is what tells a session that loaded
59 /// hundreds of predictions and matched none of them apart from one that had
60 /// nothing to match against; the first means the invocations changed (a
61 /// compiler update does this to every one of them at once), the second that
62 /// the store was empty.
63 pub predictions_loaded: u64,
64 /// Compilations that were not cacheable, counted by reason.
65 pub bypasses: BTreeMap<String, u64>,
66 /// Estimated compiler time avoided by restored action hits.
67 pub avoided_compiler_duration_ns: u64,
68 /// Real compiler work performed in this session, grouped by outcome.
69 pub compiler: BTreeMap<String, CompilerStats>,
70 /// Observed outcomes keyed by crate name and Cargo unit fingerprint.
71 pub unit_outcomes: BTreeMap<String, BTreeSet<String>>,
72 /// Cumulative real compiler time by crate name.
73 pub slow_compilations: BTreeMap<String, u64>,
74 /// Remote cache operations that failed and were degraded to a local result.
75 ///
76 /// A remote cache that cannot be reached, or that answers in a way this
77 /// client refuses, costs hit rate rather than correctness, so every one of
78 /// these is recovered from rather than raised. Counting them is what keeps a
79 /// remote that is failing every request from reading as one that merely had
80 /// nothing to offer.
81 pub remote_failures: u64,
82 /// Number of task manifest requests made to the remote cache.
83 pub remote_manifest_lookups: u64,
84 /// Cumulative time spent requesting remote task manifests.
85 pub remote_manifest_lookup_duration_ns: u64,
86 /// Number of action-result requests made to the remote cache.
87 pub remote_action_lookups: u64,
88 /// Cumulative time spent requesting remote action results.
89 pub remote_action_lookup_duration_ns: u64,
90 /// Number of blob requests made to the remote cache.
91 pub remote_blob_requests: u64,
92 /// Number of packed blob requests made to the remote cache.
93 pub remote_blob_pack_requests: u64,
94 /// Number of verified blobs received through packed responses.
95 pub remote_blob_pack_blobs: u64,
96 /// Cumulative time spent downloading and verifying remote blobs.
97 pub remote_blob_transfer_duration_ns: u64,
98 /// Cumulative time spent ingesting downloaded blobs into the local CAS.
99 pub local_cas_write_duration_ns: u64,
100 /// Number of speculative prefetch runs started for task manifests.
101 pub prefetch_runs: u64,
102 /// Cumulative wall time of speculative task-manifest prefetch runs.
103 pub prefetch_duration_ns: u64,
104 /// Cumulative time spent staging or materializing and validating cached outputs.
105 pub materialization_duration_ns: u64,
106 /// Number of compiler output files restored from action hits.
107 pub restored_output_files: u64,
108 /// Declared size of compiler output files restored from action hits.
109 pub restored_output_bytes: u64,
110 /// Number of restored output files materialized with filesystem reflinks.
111 pub reflinked_output_files: u64,
112 /// Declared size of outputs materialized with filesystem reflinks.
113 pub reflinked_output_bytes: u64,
114 /// Number of restored output files materialized by copying their bytes.
115 pub copied_output_files: u64,
116 /// Declared size of outputs materialized by copying their bytes.
117 pub copied_output_bytes: u64,
118 /// Number of output files kept in place, already holding the cached bytes.
119 pub reused_output_files: u64,
120 /// Declared size of outputs kept in place.
121 pub reused_output_bytes: u64,
122}
123
124/// Count and cumulative wall time for one compiler-invocation outcome.
125///
126/// Non-exhaustive for the same reason as [`AgentStats`], which holds these:
127/// leaving the outer bag open does not help if describing an outcome in more
128/// detail still breaks the type inside it.
129#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
130#[non_exhaustive]
131pub struct CompilerStats {
132 /// Number of compiler invocations observed.
133 pub invocations: u64,
134 /// Cumulative wall time spent in those invocations.
135 pub duration_ns: u64,
136}
137
138impl CompilerStats {
139 /// The counts observed for one outcome.
140 pub fn new(invocations: u64, duration_ns: u64) -> Self {
141 Self {
142 invocations,
143 duration_ns,
144 }
145 }
146}