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