resource_tracker/metrics/cpu.rs
1use serde::{Deserialize, Serialize};
2
3/// CPU metrics derived from /proc/stat tick deltas.
4#[derive(Debug, Clone, Default, Serialize, Deserialize)]
5pub struct CpuMetrics {
6 /// Aggregate CPU utilization expressed as fractional cores in use (0.0..N_cores).
7 /// e.g. 4.6 on a 16-core host means ~4.6 vCPUs are fully utilized.
8 /// Not clamped; values very slightly above N_cores are valid under kernel rounding.
9 /// N_cores is available via host discovery (host_vcpus).
10 pub utilization_pct: f64,
11
12 /// Cgroup/container utilization expressed as fractional cores in use
13 /// (Δcgroup_usage_secs / Δwall_secs), when cgroup accounting is available.
14 /// None when no cgroup CPU counter can be read.
15 pub cgroup_utilization_pct: Option<f64>,
16
17 /// Cgroup/container CPU time consumed during this interval (seconds),
18 /// derived from cumulative cgroup CPU usage counters.
19 /// None when no cgroup CPU counter can be read.
20 pub cgroup_usage_secs: Option<f64>,
21
22 /// Per-core utilization indexed by logical CPU number (0.0–100.0 each).
23 pub per_core_pct: Vec<f64>,
24
25 /// User+nice mode CPU time consumed across all cores in this interval (seconds).
26 /// Equivalent to Δ(user+nice ticks) / ticks_per_second.
27 /// Matches Python resource-tracker's `utime` column.
28 pub utime_secs: f64,
29
30 /// System mode CPU time consumed across all cores in this interval (seconds).
31 /// Equivalent to Δ(system ticks) / ticks_per_second.
32 /// Matches Python resource-tracker's `stime` column.
33 pub stime_secs: f64,
34
35 /// CPU steal time amount, in virtual environment, aggregated for all cores
36 pub steal_time_secs: f64,
37
38 /// CPU steal percent, in virtual environment, aggregated for all cores
39 pub steal_time_pct: f64,
40
41 /// Per-core CPU steal time percents, indexed by logical CPU number
42 pub per_core_steal_time_pct: Vec<f64>,
43
44 /// Number of processes currently in a runnable state (from /proc/stat
45 /// `procs_running`). Matches Python resource-tracker's `processes` column.
46 pub process_count: u32,
47
48 /// Fractional cores actively consumed by the tracked process tree
49 /// (root process + all descendants), derived from `/proc/<pid>/stat` tick
50 /// deltas divided by elapsed wall-clock ticks.
51 /// e.g. 2.0 means the tree is consuming the equivalent of 2 full cores.
52 /// None when no process PID is being tracked.
53 pub process_cores_used: Option<f64>,
54
55 /// Number of live descendant processes under the tracked root PID.
56 /// Does not include the root process itself.
57 /// None when no process PID is being tracked.
58 pub process_child_count: Option<u32>,
59
60 /// User-mode CPU seconds consumed by the process tree this interval.
61 /// Sum of utime tick deltas / ticks_per_second across all tree members.
62 /// None when no PID is tracked.
63 pub process_utime_secs: Option<f64>,
64
65 /// System-mode CPU seconds consumed by the process tree this interval.
66 /// Sum of stime tick deltas / ticks_per_second across all tree members.
67 /// None when no PID is tracked.
68 pub process_stime_secs: Option<f64>,
69
70 /// Proportional set size of the process tree (sum of PSS from
71 /// `/proc/pid/smaps_rollup`) in MiB, sampled each interval (not a delta).
72 /// Preferred process memory metric; matches Python `memory_mib`. Serialized
73 /// as `process_pss_mib` in JSON; CSV column remains `process_memory_mib`.
74 /// None when no PID is tracked.
75 pub process_pss_mib: Option<u64>,
76
77 /// Resident set size of the process tree (sum of VmRSS from
78 /// `/proc/pid/status`) in MiB, sampled each interval (not a delta).
79 /// Retained for consumers that need RSS; may exceed physical RAM when shared
80 /// mappings are summed across the tree. None when no PID is tracked.
81 pub process_rss_mib: Option<u64>,
82
83 /// Disk bytes actually read from storage by the process tree this interval.
84 /// Delta of /proc/pid/io read_bytes across all tree members.
85 /// None when no PID is tracked or /proc/pid/io is unreadable.
86 pub process_disk_read_bytes: Option<u64>,
87
88 /// Disk bytes actually written to storage by the process tree this interval.
89 /// Delta of /proc/pid/io write_bytes across all tree members.
90 /// None when no PID is tracked or /proc/pid/io is unreadable.
91 pub process_disk_write_bytes: Option<u64>,
92
93 /// Fractional GPUs actively consumed by the tracked process tree, expressed
94 /// as the equivalent number of fully-utilized GPUs (same convention as
95 /// `process_cores_used`). e.g. 0.5 means the tree is using half of one GPU.
96 /// NVIDIA: derived from SM utilization via nvmlDeviceGetProcessUtilization
97 /// (no accounting mode required), summed across matched PIDs and devices,
98 /// then divided by 100.
99 /// AMD: derived from drm-engine-gfx cumulative ns via FdInfoStat delta tracking.
100 /// None when no GPU is present, NVML/AMD data is unavailable, or no samples returned.
101 pub process_gpu_usage: Option<f64>,
102
103 /// Total VRAM consumed by the tracked process tree across all GPUs (MiB).
104 /// NVIDIA: sum of used_gpu_memory from NVML running-process lists.
105 /// AMD: sum of drm-memory-vram from /proc/pid/fdinfo for matched devices.
106 /// None when no PID is tracked or no GPU is present on the host.
107 pub process_gpu_vram_mib: Option<f64>,
108
109 /// Number of GPUs on which at least one process in the tracked tree has
110 /// allocated VRAM or appears in the running-process list.
111 /// None when no PID is tracked or no GPU is present on the host.
112 pub process_gpu_utilized: Option<u32>,
113
114 /// PIDs in the tracked process tree (root + all descendants).
115 /// Populated by CpuCollector; used by main.rs to query per-process GPU stats.
116 /// Skipped in JSON/CSV output -- internal routing field only.
117 #[serde(skip)]
118 pub process_tree_pids: Vec<i32>,
119}