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