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:)
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_statistics64does 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 identityused + cached + free = physicalexact and prevents unsigned underflow. The unit testinconsistentCountersNeverUnderflowfeeds deliberately impossible counters; the live testmemoryAccountingAddsUpchecks 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. |