SPB Git

Repository Public License

memory.md 9.2 KB

# Memory metrics

Sources: Collectors/MemoryCollector.swift (MemoryCollector, MemoryMath, VMCounters, MemorySample, MemoryPressureLevel), Metrics/Metric.swift, App/Sources/Features/ComputeViews.swift (MemoryView).

# Vocabulary

Memory figures are easy to misread because several different quantities are all called "memory". ORIX Monitor uses these terms, and only these.

Term Definition in ORIX Monitor Is it RAM?
Physical memory The RAM installed in the Mac (hw.memsize). The identity used + cached files + free = physical always holds. Yes — the total
App memory Anonymous memory that processes allocated themselves, minus what they marked purgeable. Yes
Wired memory Memory the kernel must keep in RAM; it cannot be compressed or paged out. Yes
Compressed memory Physical RAM occupied by the compressor. The data stored there was larger before compression; the original size is not shown. Yes
Memory used App + wired + compressed (the Activity Monitor convention). Yes
Cached files File-backed pages plus purgeable pages: memory the system can reclaim without losing anything. Yes, but reclaimable
Free memory Physical − used − cached. Small values are normal: unused RAM is put to work as cache. Yes
Swap Disk space holding pages moved out of RAM. Not part of physical memory. No — disk
Memory pressure The kernel's own three-level signal (normal, warning, critical). This, not the amount of free memory, tells whether the Mac is short of memory. A state, not an amount
Physical footprint (per process) ri_phys_footprint: the figure Activity Monitor shows as "Memory" for a process. Yes, attributed to one process
Virtual memory Address space reserved by processes. It is not a measure of RAM in use and is not shown. No

The Memory page carries a "How to read these numbers" card with the same definitions.

# Stored metrics

Refresh: every tick of the fast tier — 2 s by default while a window is visible (see telemetry).

Key (MetricID) Name Unit Quality Source API Stored value
memory.used (memUsed) Memory used bytes derived host_statistics64(HOST_VM_INFO64) min(physical, app + wired + compressed)
memory.app (memApp) App memory bytes derived same (internal_page_count − purgeable_count) × page size, floored at 0
memory.wired (memWired) Wired memory bytes measured same wire_count × page size
memory.compressed (memCompressed) Compressed memory bytes measured same compressor_page_count × page size
memory.cached (memCached) Cached files bytes derived same min(physical − used, (external_page_count + purgeable_count) × page size)
memory.free (memFree) Free memory bytes derived same physical − used − cached
memory.pressure (memPressure) Memory pressure level level measured sysctl kern.memorystatus_vm_pressure_level 0 = normal, 1 = warning, 2 = critical
memory.swap (swapUsed) Swap used bytes measured sysctl vm.swapusage xsw_usage.xsu_used
memory.pageins (pageIns) Page-ins pages per second derived host_statistics64(HOST_VM_INFO64) Δ pageins / Δ time
memory.pageouts (pageOuts) Page-outs pages per second derived same Δ pageouts / Δ time

Related: self.memory (selfMemory, bytes, measured) is ri_phys_footprint of ORIX Monitor's own process from proc_pid_rusage(RUSAGE_INFO_V4), stored every tick.

# Accounting — MemoryMath.account(_:pageSize:physical:)

text
appPages   = max(0, internal − purgeable)
app        = appPages   × pageSize
wired      = wire_count × pageSize
compressed = compressor_page_count × pageSize
used       = min(physical, app + wired + compressed)
cached     = min(physical − used, (external + purgeable) × pageSize)
free       = physical − used − cached
  • Why saturating arithmetic. host_statistics64 does not return an atomic snapshot: counters are read one after another while the system keeps running, so their sum can momentarily exceed physical memory. Clamping keeps the identity used + cached + free = physical exact and prevents unsigned underflow. The unit test inconsistentCountersNeverUnderflow feeds deliberately impossible counters; the live test memoryAccountingAddsUp checks the identity on the real machine.
  • Page size comes from host_page_size (shown on the page; 16 KB pages on Apple Silicon are the general rule, but ORIX Monitor reads the value rather than assuming it).
  • Percentage convention. MemorySample.usedFraction = used / physical. Percentages shown for memory (sidebar badge, menu bar "MEM", menu bar panel) are this fraction × 100: 100 % = all installed RAM is app, wired or compressed memory.

# Pressure

kern.memorystatus_vm_pressure_level returns 1, 2 or 4. MemoryPressureLevel(kernelValue:) maps them to normal (0), warning (1) and critical (2); any other value is treated as normal, and so is a failed read.

The level is stored as a number so that it can be charted, averaged per bucket and used by alert rules. Because averages of a level can be fractional, thresholds are placed halfway between levels: "above 0.5" means warning or higher, "above 1.5" means critical. The default alert rules and the memoryPressure finding use exactly these (see alerts).

The pressure badge always shows the word (Normal / Warning / Critical) and a symbol next to the colour.

# Swap and paging

Value Source Stored Meaning
Swap used vm.swapusage → xsu_used yes Bytes of swap space currently holding pages
Swap allocated vm.swapusage → xsu_total no Size of the swap files macOS has created; it grows and shrinks on its own
Page-ins/s Δ vm_statistics64.pageins / Δt yes Pages read in from disk (files or swap)
Page-outs/s Δ vm_statistics64.pageouts / Δt yes Pages written out to disk
Swap-ins/s Δ swapins / Δt no Pages brought back from swap
Swap-outs/s Δ swapouts / Δt no Pages moved to swap

Rates use CounterMath with monotonic elapsed time; they are nil on the first sample and after any baseline reset. The unit is pages per second, not bytes; multiply by the page size shown on the same card to convert.

VMCounters also reads compressions and decompressions, free, active, inactive and speculative page counts. They are collected but not displayed or stored.

# Displayed values

Memory page (MemoryView): the used readout with its breakdown bar and legend (app, wired, compressed, cached, free); a stacked live chart of app, wired and compressed memory on a 0…physical scale; the pressure chart; the "Swap and paging" card; the definitions card; top processes by memory (physical footprint, own processes only).

Elsewhere: dashboard "Memory" widget, sidebar badge, menu bar indicator and panel, History, Memory Analysis and System Overview reports.

# Quality classes

  • measured — wired, compressed, pressure, swap used: passed through from one kernel value (times the page size).
  • derived — used, app, cached, free and the paging rates: computed from several counters or from deltas.

# Limitations

  • "App memory" follows a convention, not a kernel field. It is computed the way Activity Monitor is understood to compute it (internal minus purgeable). Apple does not publish Activity Monitor's exact formula, so small differences from its display are possible.
  • Cached files include purgeable memory, which is anonymous rather than file-backed. The name follows Activity Monitor's label.
  • Compressed is the compressor's footprint, not the amount of data it holds; the compression ratio is not shown.
  • Per-process memory is unavailable for other users' processes. Their cells show "—", and the per-process figures therefore do not sum to "memory used". Shared memory also means footprints are not strictly additive.
  • Pressure is sampled. A brief excursion to warning between two samples is not seen.
  • Free memory is not a health indicator. ORIX Monitor says so in the interface and builds its alerts and findings on pressure and swap growth instead.

# Deliberately not shown

Item Reason
Virtual memory size (system or per process) It measures reserved address space, not RAM in use, and is routinely misread as a leak.
"Inactive", "active" and "speculative" page counts Internal page-queue states that do not map to anything a user can act on; they are folded into the breakdown above.
A "memory pressure percentage" The kernel publishes a level, not a percentage. Any percentage would be invented.
A "free up memory" or purge action It would only evict caches the system manages correctly by itself.
Memory of other users' processes Needs a privileged helper, which ORIX Monitor does not install.
Compression ratio / uncompressed size Not derived; only the compressor's physical footprint is reported.
Files main
Menu

Theme