SPB Git

Repository Public License

memory.md 9.2 KB 120 lines markdown

1<!--2ORIX Monitor3File: docs/metrics/memory.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Memory metrics910Sources: `Collectors/MemoryCollector.swift` (`MemoryCollector`, `MemoryMath`, `VMCounters`, `MemorySample`, `MemoryPressureLevel`), `Metrics/Metric.swift`, `App/Sources/Features/ComputeViews.swift` (`MemoryView`).1112## Vocabulary1314Memory figures are easy to misread because several different quantities are all called "memory". ORIX Monitor uses these terms, and only these.1516| Term | Definition in ORIX Monitor | Is it RAM? |17|---|---|---|18| **Physical memory** | The RAM installed in the Mac (`hw.memsize`). The identity *used + cached files + free = physical* always holds. | Yes — the total |19| **App memory** | Anonymous memory that processes allocated themselves, minus what they marked purgeable. | Yes |20| **Wired memory** | Memory the kernel must keep in RAM; it cannot be compressed or paged out. | Yes |21| **Compressed memory** | Physical RAM **occupied by the compressor**. The data stored there was larger before compression; the original size is not shown. | Yes |22| **Memory used** | App + wired + compressed (the Activity Monitor convention). | Yes |23| **Cached files** | File-backed pages plus purgeable pages: memory the system can reclaim without losing anything. | Yes, but reclaimable |24| **Free memory** | Physical − used − cached. Small values are normal: unused RAM is put to work as cache. | Yes |25| **Swap** | Disk space holding pages moved out of RAM. **Not part of physical memory.** | No — disk |26| **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 |27| **Physical footprint** (per process) | `ri_phys_footprint`: the figure Activity Monitor shows as "Memory" for a process. | Yes, attributed to one process |28| **Virtual memory** | Address space reserved by processes. It is not a measure of RAM in use and **is not shown**. | No |2930The Memory page carries a "How to read these numbers" card with the same definitions.3132## Stored metrics3334Refresh: every tick of the fast tier — 2 s by default while a window is visible (see [telemetry](../architecture/telemetry.md)).3536| Key (`MetricID`) | Name | Unit | Quality | Source API | Stored value |37|---|---|---|---|---|---|38| `memory.used` (`memUsed`) | Memory used | bytes | derived | `host_statistics64(HOST_VM_INFO64)` | `min(physical, app + wired + compressed)` |39| `memory.app` (`memApp`) | App memory | bytes | derived | same | `(internal_page_count − purgeable_count) × page size`, floored at 0 |40| `memory.wired` (`memWired`) | Wired memory | bytes | measured | same | `wire_count × page size` |41| `memory.compressed` (`memCompressed`) | Compressed memory | bytes | measured | same | `compressor_page_count × page size` |42| `memory.cached` (`memCached`) | Cached files | bytes | derived | same | `min(physical − used, (external_page_count + purgeable_count) × page size)` |43| `memory.free` (`memFree`) | Free memory | bytes | derived | same | `physical − used − cached` |44| `memory.pressure` (`memPressure`) | Memory pressure level | level | measured | `sysctl kern.memorystatus_vm_pressure_level` | 0 = normal, 1 = warning, 2 = critical |45| `memory.swap` (`swapUsed`) | Swap used | bytes | measured | `sysctl vm.swapusage` | `xsw_usage.xsu_used` |46| `memory.pageins` (`pageIns`) | Page-ins | pages per second | derived | `host_statistics64(HOST_VM_INFO64)` | `Δ pageins / Δ time` |47| `memory.pageouts` (`pageOuts`) | Page-outs | pages per second | derived | same | `Δ pageouts / Δ time` |4849Related: `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.5051## Accounting — `MemoryMath.account(_:pageSize:physical:)`5253```54appPages   = max(0, internal − purgeable)55app        = appPages   × pageSize56wired      = wire_count × pageSize57compressed = compressor_page_count × pageSize58used       = min(physical, app + wired + compressed)59cached     = min(physical − used, (external + purgeable) × pageSize)60free       = physical − used − cached61```6263- **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.64- **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).65- **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.6667## Pressure6869`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.7071The 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](../architecture/alerts.md)).7273The pressure badge always shows the word (Normal / Warning / Critical) and a symbol next to the colour.7475## Swap and paging7677| Value | Source | Stored | Meaning |78|---|---|---|---|79| Swap used | `vm.swapusage` → `xsu_used` | yes | Bytes of swap space currently holding pages |80| Swap allocated | `vm.swapusage` → `xsu_total` | no | Size of the swap files macOS has created; it grows and shrinks on its own |81| Page-ins/s | `Δ vm_statistics64.pageins / Δt` | yes | Pages read in from disk (files or swap) |82| Page-outs/s | `Δ vm_statistics64.pageouts / Δt` | yes | Pages written out to disk |83| Swap-ins/s | `Δ swapins / Δt` | no | Pages brought back from swap |84| Swap-outs/s | `Δ swapouts / Δt` | no | Pages moved to swap |8586Rates 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.8788`VMCounters` also reads `compressions` and `decompressions`, `free`, `active`, `inactive` and `speculative` page counts. They are collected but not displayed or stored.8990## Displayed values9192Memory 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).9394Elsewhere: dashboard "Memory" widget, sidebar badge, menu bar indicator and panel, History, Memory Analysis and System Overview reports.9596## Quality classes9798- `measured` — wired, compressed, pressure, swap used: passed through from one kernel value (times the page size).99- `derived` — used, app, cached, free and the paging rates: computed from several counters or from deltas.100101## Limitations102103- **"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.104- **Cached files include purgeable memory**, which is anonymous rather than file-backed. The name follows Activity Monitor's label.105- **Compressed is the compressor's footprint**, not the amount of data it holds; the compression ratio is not shown.106- **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.107- **Pressure is sampled.** A brief excursion to warning between two samples is not seen.108- **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.109110## Deliberately not shown111112| Item | Reason |113|---|---|114| Virtual memory size (system or per process) | It measures reserved address space, not RAM in use, and is routinely misread as a leak. |115| "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. |116| A "memory pressure percentage" | The kernel publishes a level, not a percentage. Any percentage would be invented. |117| A "free up memory" or purge action | It would only evict caches the system manages correctly by itself. |118| Memory of other users' processes | Needs a privileged helper, which ORIX Monitor does not install. |119| Compression ratio / uncompressed size | Not derived; only the compressor's physical footprint is reported. |120
Files main
Menu

Theme