SPB Git

Repository Public License

cpu.md 7.8 KB

# CPU metrics

Sources: Collectors/CPUCollector.swift, Collectors/ProcessCollector.swift, Metrics/Metric.swift (MetricCatalog), App/Sources/Features/ComputeViews.swift (CPUView).

# The two percentage conventions

ORIX Monitor uses two scales and states which one applies wherever a CPU percentage is shown.

Scope Convention Range Where
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
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

A 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.

# Stored metrics

Refresh: 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).

Key (MetricID) Name Unit Quality Source API Stored value
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
cpu.user (cpuUser) CPU user percent derived same (Δuser + Δnice) / Δall ticks × 100
cpu.system (cpuSystem) CPU system percent derived same Δsystem / Δall ticks × 100
cpu.load1 (loadAverage1) Load average (1 min) load measured getloadavg(3) The kernel's 1-minute run-queue average, as reported

Related stored metrics from the process collector:

Key Name Unit Quality Source API Stored value
process.count (processCount) Processes count measured proc_listallpids Number of processes listed at the last process sample
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

# Formulas

# Per-core load — CPUMath.load(previous:current:)

The kernel publishes four cumulative tick counters per logical core: user, system, idle, nice. They are 32-bit and wrap.

text
Δuser   = (user₁ ⊖ user₀) + (nice₁ ⊖ nice₀)        ⊖ = wrapping 32-bit subtraction
Δsystem =  system₁ ⊖ system₀
Δidle   =  idle₁ ⊖ idle₀
total   = Δuser + Δsystem + Δidle
user = Δuser / total      system = Δsystem / total      idle = Δidle / total
busy = user + system
  • Nice time is folded into user time.
  • When no tick elapsed (total == 0) the result is CPULoad.zero, not NaN.
  • Wrapping subtraction makes one counter wraparound harmless (tickCounterWraparoundIsHandled).

# Whole-Mac load — CPUMath.aggregate(previous:current:)

The 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 %.

If the number of cores differs between two readings the aggregate is .zero and CPUCollector.sample() returns nil for that tick.

# Per-process CPU — ProcessMath.cpuPercent(previousNanos:currentNanos:elapsed:)

text
cpuPercent = (cpuNanos₁ − cpuNanos₀) / 10⁹ / elapsedSeconds × 100
  • 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).
  • elapsed is monotonic time between two process samples.
  • 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).
  • Refresh: the process tier, 4 s by default, scaled with the effective interval.

# Displayed but not stored

Value Source Where
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
Idle share same CPU page
5- and 15-minute load averages getloadavg CPU page
Peak and average in the live window computed over the in-memory window (up to 150 samples) CPU page "Load and peaks"
Measured interval of the last sample (CPUSample.interval) monotonic clock CPU page
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
Per-process CPU %, CPU time, thread count proc_pid_rusage, proc_pidinfo(PROC_PIDTASKINFO) Processes page, top-process lists, menu bar panel

Per-core history is kept only in memory (MonitorModel.coreHistory); it is not written to the store.

# Core groups

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.

The 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."

# Quality classes

  • derived — CPU percentages are ratios of measured tick deltas.
  • measured — the load average and the process count are passed through as the kernel reports them.

# Limitations

  • Tick resolution. Scheduler ticks are coarse; over a very short interval a percentage is quantised. The minimum interval is 1 s in the UI.
  • 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.
  • Load average is not a percentage. It counts runnable and running threads averaged by the kernel and must be read against the core count.
  • 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.
  • cpu.total includes ORIX Monitor itself. Its own share is available separately as self.cpu.

# Deliberately not shown

Item Reason
CPU frequency Not published on Apple Silicon by any supported interface. Shown as unavailable.
CPU temperature Only reachable through the SMC or private sensor services. See thermal.
Per-cluster or per-core power Requires powermetrics (root). See power.
Labels such as "performance core 3" on individual cores The kernel does not publish the mapping; any label would be a guess.
Per-thread CPU usage Not collected.
CPU usage of other users' processes Needs a privileged helper, which ORIX Monitor does not install.
Files main
Menu

Theme