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

resource_tracker/metrics/
cpu.rs
