Repository Public License
1<!--2ORIX Monitor3File: docs/metrics/cpu.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# CPU metrics910Sources: `Collectors/CPUCollector.swift`, `Collectors/ProcessCollector.swift`, `Metrics/Metric.swift` (`MetricCatalog`), `App/Sources/Features/ComputeViews.swift` (`CPUView`).1112## The two percentage conventions1314ORIX Monitor uses two scales and states which one applies wherever a CPU percentage is shown.1516| Scope | Convention | Range | Where |17|---|---|---|---|18| **Whole Mac** (`cpu.total`, `cpu.user`, `cpu.system`, per-core bars) | 100 % = every logical core busy | 0–100 % | CPU page ("100 % = every core busy"), dashboard, menu bar, history, alerts, reports |19| **One process** (`ProcessRecord.cpuPercent`, `self.cpu`) | 100 % = one core fully busy (the Activity Monitor convention) | 0 – 100 × number of cores | Processes page ("of one core"), top-process lists, spike detection, ORIX Monitor's own overhead |2021A process at 250 % is using two and a half cores; on an 18-core Mac that alone contributes about 14 % to the whole-Mac figure. The two numbers are not interchangeable and are never mixed in one chart. Every report repeats the rule in its limitations.2223## Stored metrics2425Refresh: every tick of the fast tier — 2 s by default while a window is visible, 5 s with only the menu bar, doubled on battery or in Low Power Mode when the battery saver is on (see [telemetry](../architecture/telemetry.md)).2627| Key (`MetricID`) | Name | Unit | Quality | Source API | Stored value |28|---|---|---|---|---|---|29| `cpu.total` (`cpuTotal`) | CPU usage | percent | derived | `host_processor_info(PROCESSOR_CPU_LOAD_INFO)` | `(Δuser + Δnice + Δsystem) / Δall ticks × 100`, ticks summed over all logical cores |30| `cpu.user` (`cpuUser`) | CPU user | percent | derived | same | `(Δuser + Δnice) / Δall ticks × 100` |31| `cpu.system` (`cpuSystem`) | CPU system | percent | derived | same | `Δsystem / Δall ticks × 100` |32| `cpu.load1` (`loadAverage1`) | Load average (1 min) | load | measured | `getloadavg(3)` | The kernel's 1-minute run-queue average, as reported |3334Related stored metrics from the process collector:3536| Key | Name | Unit | Quality | Source API | Stored value |37|---|---|---|---|---|---|38| `process.count` (`processCount`) | Processes | count | measured | `proc_listallpids` | Number of processes listed at the last process sample |39| `self.cpu` (`selfCPU`) | ORIX Monitor CPU | percent of one core | derived | `proc_pid_rusage(RUSAGE_INFO_V4)` | `Δ(user + system CPU time) / Δ time × 100` for the app's own process |4041## Formulas4243### Per-core load — `CPUMath.load(previous:current:)`4445The kernel publishes four cumulative tick counters per logical core: user, system, idle, nice. They are 32-bit and wrap.4647```48Δuser = (user₁ ⊖ user₀) + (nice₁ ⊖ nice₀) ⊖ = wrapping 32-bit subtraction49Δsystem = system₁ ⊖ system₀50Δidle = idle₁ ⊖ idle₀51total = Δuser + Δsystem + Δidle52user = Δuser / total system = Δsystem / total idle = Δidle / total53busy = user + system54```5556- Nice time is folded into user time.57- When no tick elapsed (`total == 0`) the result is `CPULoad.zero`, not NaN.58- Wrapping subtraction makes one counter wraparound harmless (`tickCounterWraparoundIsHandled`).5960### Whole-Mac load — `CPUMath.aggregate(previous:current:)`6162The deltas of every core are **summed first**, and the fractions are taken on the sums. This weighs each core by the time it actually accounted for; it is not the average of per-core percentages. The unit test `aggregateWeighsCoresByTicksNotByAverageOfRatios` shows the difference: one core fully busy for 100 ticks and one idle for 300 ticks is 25 % busy, not 50 %.6364If the number of cores differs between two readings the aggregate is `.zero` and `CPUCollector.sample()` returns `nil` for that tick.6566### Per-process CPU — `ProcessMath.cpuPercent(previousNanos:currentNanos:elapsed:)`6768```69cpuPercent = (cpuNanos₁ − cpuNanos₀) / 10⁹ / elapsedSeconds × 10070```7172- `cpuNanos` is `ri_user_time + ri_system_time` from `rusage_info_v4`. Those fields are in **Mach absolute-time units**; `ProcessMath.nanos(machUnits:numer:denom:)` converts them with the timebase from `mach_timebase_info` (125/3 on Apple Silicon) using a full-width multiply so large values cannot overflow. The live test `cpuTimeAgreesWithGetrusage` validates the conversion against `getrusage(RUSAGE_SELF)`.73- `elapsed` is monotonic time between two process samples.74- The value is `nil` (displayed "—") on the first sample of a process, when the counter went backwards, and whenever the stored baseline belongs to a different start time (PID reuse).75- Refresh: the process tier, 4 s by default, scaled with the effective interval.7677## Displayed but not stored7879| Value | Source | Where |80|---|---|---|81| Per-core busy fraction (`CPUSample.cores`) | `host_processor_info` | CPU page "Cores" grid; "Core activity" heatmap over the last 150 samples; dashboard "CPU cores" widget |82| Idle share | same | CPU page |83| 5- and 15-minute load averages | `getloadavg` | CPU page |84| Peak and average in the live window | computed over the in-memory window (up to 150 samples) | CPU page "Load and peaks" |85| Measured interval of the last sample (`CPUSample.interval`) | monotonic clock | CPU page |86| Chip name, physical and logical core counts, core groups | `machdep.cpu.brand_string`, `hw.physicalcpu`, `hw.logicalcpu`, `hw.perflevelN.*` | CPU page header and "Cores" card, About, reports |87| Per-process CPU %, CPU time, thread count | `proc_pid_rusage`, `proc_pidinfo(PROC_PIDTASKINFO)` | Processes page, top-process lists, menu bar panel |8889Per-core history is kept only in memory (`MonitorModel.coreHistory`); it is not written to the store.9091## Core groups9293`CPUTopology.current()` reports the kernel's performance levels: for each level a name and a physical and logical core count. On the audited Mac (Apple M5 Max) the kernel returns two levels named "Super" (6 cores) and "Performance" (12 cores). ORIX Monitor prints those names as given.9495The kernel does **not** say which core index belongs to which level. The CPU page therefore shows cores by number, unlabelled, and says so: "macOS reports how many cores each performance level has, not which core number belongs to which level."9697## Quality classes9899- `derived` — CPU percentages are ratios of measured tick deltas.100- `measured` — the load average and the process count are passed through as the kernel reports them.101102## Limitations103104- **Tick resolution.** Scheduler ticks are coarse; over a very short interval a percentage is quantised. The minimum interval is 1 s in the UI.105- **No baseline, no value.** The first tick after launch, wake, a detected gap or a resume has no CPU percentage; charts start at the second sample.106- **Load average is not a percentage.** It counts runnable and running threads averaged by the kernel and must be read against the core count.107- **Other users' processes have no CPU figure.** The kernel refuses their statistics to an unprivileged app; they are shown with "—" and excluded from rankings. Consequently the per-process figures do not add up to the whole-Mac figure.108- **`cpu.total` includes ORIX Monitor itself.** Its own share is available separately as `self.cpu`.109110## Deliberately not shown111112| Item | Reason |113|---|---|114| CPU frequency | Not published on Apple Silicon by any supported interface. Shown as unavailable. |115| CPU temperature | Only reachable through the SMC or private sensor services. See [thermal](thermal.md). |116| Per-cluster or per-core power | Requires `powermetrics` (root). See [power](power.md). |117| Labels such as "performance core 3" on individual cores | The kernel does not publish the mapping; any label would be a guess. |118| Per-thread CPU usage | Not collected. |119| CPU usage of other users' processes | Needs a privileged helper, which ORIX Monitor does not install. |120