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

resource_tracker/metrics/
cpu.rs
