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