55 lines
2.7 KiB
Markdown
55 lines
2.7 KiB
Markdown
# Resource Manager memory metrics
|
|
|
|
Resource Manager reports two different kinds of memory data. Process totals describe Orca and
|
|
locally managed terminal processes; host totals describe the machine running Orca. They are not
|
|
interchangeable.
|
|
|
|
## Process memory
|
|
|
|
Each snapshot declares one `processMemoryMetric`:
|
|
|
|
| Platform | Metric | Source |
|
|
| ------------ | ------------- | ---------------------------------------------------------- |
|
|
| macOS, Linux | `rss` | `ps` resident set size |
|
|
| Windows | `working-set` | CIM `WorkingSetSize`, with a Typeperf working-set fallback |
|
|
|
|
Orca walks each registered local PTY subtree and claims every PID at most once. App, session,
|
|
worktree, history, and snapshot memory values are sums of those per-process samples.
|
|
|
|
RSS and working set are not unique physical-memory measurements. Shared pages can appear in more
|
|
than one process, and macOS can count the same resident page through multiple mappings in one
|
|
process. A sum can therefore exceed physical RAM. Product copy and diagnostics must identify the
|
|
metric as a sum and must not present it as a percentage of system RAM.
|
|
|
|
Remote SSH and relay sessions do not receive invented local samples. They remain unavailable until
|
|
the executing host supplies resource data. Folder workspaces use the same registered-PTY
|
|
attribution as Git worktrees.
|
|
|
|
## Host memory
|
|
|
|
`HostMemory` keeps immediate free memory separate from memory available without material pressure:
|
|
|
|
- `freeMemory` is Node's host free-memory value.
|
|
- `availableMemory` is the best bounded platform value.
|
|
- `usedMemory` is `totalMemory - availableMemory`.
|
|
- `memoryUsagePercent` is derived from `usedMemory`.
|
|
- `availableMemorySource` identifies how availability was measured.
|
|
|
|
The sources are:
|
|
|
|
| Platform | Preferred source | Fallback |
|
|
| -------- | ----------------------------------------- | ---------------- |
|
|
| macOS | `memory_pressure -Q` available percentage | Node free memory |
|
|
| Linux | `/proc/meminfo` `MemAvailable` | Node free memory |
|
|
| Windows | Node free memory | Node free memory |
|
|
|
|
This percentage describes host availability. It is not derived from the summed process metric.
|
|
|
|
## Bounded collection
|
|
|
|
Resource Manager polls while its popover is open, so every snapshot must remain bounded under a
|
|
large process tree. macOS `footprint` provides a more physical process metric, but collecting it
|
|
across dozens of processes is too expensive for this path. A future physical-footprint backend
|
|
must use a bounded host API or helper and declare a distinct metric before product copy treats it
|
|
as physical memory.
|