Reading rule
Use pressure, available memory, GPU working-set headroom, and active swap or compression I/O together when diagnosing a local-inference stall. A single metric rarely establishes the cause.
This page is the prose definition. The searoom command ships a machine-readable catalog of the 49 fields it emits — unit, range, nullability, source, derivation, thresholds and limitations for each — as searoom metrics --json, published as the metric catalog. The command line reference covers the rest of that contract.
Memory
Memory used
Memory used is active plus wired plus compressed memory, capped at physical memory. Searoom treats this as the non-readily-reclaimable working set.
This intentionally differs from a simple total - free pages calculation and may differ slightly from Activity Monitor.
Memory
Memory available and cached
Available memory is physical memory minus Searoom's working set. It includes memory macOS can reclaim, so it is more useful than the raw free-page count for judging whether another workload can fit.
Cached memory is the inactive, purgeable, and speculative subset of available memory. Searoom caps it at the available total.
Pressure
Memory pressure
Searoom reads the macOS system memory-pressure level when it is available and also derives a level from working-set utilization. It keeps the more severe of the two.
The numeric trend begins with the working-set ratio. When the selected system state is more severe, Searoom raises the trend to a matching floor so the graph does not contradict the state label.
Pressure
Utilization thresholds
Searoom maps utilization below 70% to nominal, 70% to below 85% to elevated, 85% to below 95% to constrained, and 95% or above to critical.
These thresholds apply to utilization-derived signals. A macOS-provided memory or thermal state can be more severe than the utilization tier.
Memory
Swap used and swap I/O
Swap used is the current allocation reported by vm.swapusage. Existing swap allocation does not by itself mean the Mac is currently stalling.
Swap I/O is the byte rate derived from deltas of the Mach swapins and swapouts counters. The first sample is zero because it establishes the baseline. Counter rollback also produces zero for that interval.
Memory
Compressed memory and compression I/O
Compressed memory is the macOS compressor's share of the working set and is already counted inside memory used. Compression and decompression rates are byte rates from deltas of Mach page counters, with the same first-sample zero baseline as swap I/O.
Rising compression churn alongside climbing memory pressure often precedes swap activity, which makes it an early exhaustion signal rather than a failure by itself.
Compute
CPU utilization
CPU utilization is the change in aggregate Mach CPU ticks over the sampling interval, from the same kernel statistics interface. The first sample is zero because no previous counter exists.
Derived pressure
CPU pressure
CPU pressure is the greater of CPU utilization and the one-minute load average divided by the active logical CPU count.
It is a Searoom-derived saturation signal. It is not macOS PSI and is not an Apple pressure API.
Best effort
GPU utilization and pressure
GPU utilization comes from read-only IORegistry signals where a supported key exists. GPU pressure is a Searoom-derived signal: the greater of GPU utilization and the ratio of in-use GPU system memory to the Metal-recommended working-set size.
In-use memory is a read-only IORegistry value bounded by physical memory; the working-set budget comes from Metal's recommendedMaxWorkingSetSize. Without a supported utilization signal, utilization, pressure, and working-set metrics are all unavailable. No zero is substituted.
Best effort
GPU working-set memory
The GPU memory card compares in-use GPU system memory against the Metal-recommended working-set budget, which approximates how much memory the GPU can use with good performance before overcommitting.
On Apple Silicon this budget is a fraction of unified memory. Approaching or exceeding it is the leading signal for Metal allocation pressure during local model inference, and it raises the derived GPU pressure described above even when utilization is low.
System state
Thermal pressure
Thermal pressure is the current macOS thermal state reported by ProcessInfo. It describes system thermal constraint and does not require a direct temperature sensor.
Best effort
Temperature source
Searoom prefers a validated CPU or package temperature from read-only SMC access. If that is unavailable, it may show the AppleSmartBattery pack temperature and labels the source BAT.
A battery-pack reading is not CPU temperature. On the M5 Pro generation the package sensors read directly through the Tp04, Tp08 and Tp0C keys, so those Macs show a package temperature labelled CPU PACKAGE rather than the battery fallback. If neither source is available, temperature is unavailable.
Best effort
Fan speed
Fan readings use read-only, best-effort AppleSMC access, whose key names Apple does not publish and which are catalogued only by community reference. Key names and availability vary by Mac model and macOS release. Searoom does not control fans and does not use a privileged helper.
Throughput
Network throughput
Download and upload rates aggregate active non-loopback interfaces. VPN and virtual interfaces can make the aggregate differ from a physical-link view. Counter rollback produces zero for that interval.
Throughput
Disk throughput
Disk read and write rates are deltas of IORegistry byte counters over monotonic time. They describe recent activity rather than remaining disk capacity.
Capacity
Disk capacity
Remaining capacity reads the root volume through the same interface Finder uses; the root shares its APFS container with the Data volume, so one number covers user data.
Available space excludes purgeable files, so it can read lower than Finder after large deletions that macOS has not reclaimed yet. Disk capacity is a neutral reading: Searoom does not turn a well-used disk into a pressure state.
Power
Battery and Low Power Mode
Searoom reports battery percentage and external-power state when the system exposes them. Low Power Mode is the current state from ProcessInfo; macOS may reduce CPU and GPU performance while it is enabled.
Accountability
Searoom's own impact
The final telemetry line shows Searoom's own process CPU, resident memory, and current sample cadence. Process CPU is elapsed process CPU time divided by wall time and can exceed 100% when multiple cores are used.
Dashboard
Top processes
The dashboard ranks the five heaviest readable processes by CPU rate and the five by resident memory, refreshed at the sampling interval like the other live readings. A process CPU rate is CPU seconds per wall second and can exceed 100% when a process uses several cores, the same unclamped quantity as Searoom's own cost line.
Enumeration is a public sysctl kern.proc read of the whole process table; sandboxed helpers and other-user processes that refuse the probe are omitted, never shown as zero, because macOS keeps their CPU and memory figures private without privileges, and ps reads those only because it is setuid root. A column with no measurable consumers says so rather than inventing entries. The ranking is display state only and is never persisted: process names stay out of stored history.
Summary
Sustained pressure
The dashboard header reports how long the current overall pressure level has been held continuously. The figure is bounded by the retained history window; a + suffix means the run spans every retained sample, so the window rather than the Mac limits the count.
Sustained levels matter more than momentary spikes when judging whether a workload genuinely exhausts capacity.
Summary
Overall pressure
The menu-bar state is the most severe available level among CPU, memory, thermal, and GPU pressure. Unavailable has lower priority than every observed state; four unavailable inputs produce unavailable.
Reproduce a reading
Run searoom sample for one primed JSON sample: the command primes every rate baseline before emitting, so the first sample already carries meaningful disk I/O. The legacy Searoom --dump-sample still prints the frozen 41-field shape. Include the Mac model, macOS version, Searoom version, workload, local model, and quantization when publishing a result.