fix(dashboard): use balloon-adjusted memory percent on the Memory tile (#1847)

* fix(dashboard): use balloon-adjusted memory percent on the Memory tile

When balloon fields are present, the Memory tile hero, tone, and
gauge bar now use effectiveUsagePercent so they match the used/total
bytes. Health and host RAM alerts still use working-set usagePercent.

* fix(dashboard): align health banner and Memory tile on balloon-adjusted memory

The health banner read the raw working-set percent while the Memory tile
showed the balloon-adjusted one, so a hypervisor ballooning an otherwise
healthy VM could flag it critical. Both now use effectiveUsagePercent,
falling back to the raw percent when balloon fields are absent. Host RAM
alerts keep the working-set percent: ballooned pages are reclaimed by the
hypervisor and cannot be recovered by the guest on demand.

Adds guarded context lines to the Memory tile: Current VM Memory (guest
retained), Current pressure (effective used over retained), Balloon
reclaimable, and, for ZFS nodes, Current memory in use (used plus ARC
reclaimable) above ZFS ARC reclaimable.

Validated with unit tests for both components including boundary cases,
type checks, lint, and visual regression comparison confirming no change
outside the Memory tile.
This commit is contained in:
Anso
2026-08-24 05:57:06 +00:00
committed by GitHub
parent 600cde7586
commit c3c6c1b0c1
6 changed files with 324 additions and 20 deletions
+2 -2
View File
@@ -48,9 +48,9 @@ The gauge bars (and the corresponding numeric values) pick up amber at 80% and r
While the dashboard is loading the CPU tile reads `--` and the caption shows `collecting metrics…`; bars and sparklines render once the first sample arrives.
<Note>
**ZFS hosts:** the memory tile and host RAM alerts are ZFS ARC-aware. Reclaimable ARC cache is treated as available memory rather than used, so a large ARC does not inflate the gauge or trigger false low-memory alerts. The memory tile shows the reclaimable amount as a context line when ARC stats are readable and the reclaimable amount is nonzero. See [ZFS ARC-aware host memory](/getting-started/configuration#zfs-arc-aware-host-memory) for how to expose ARC stats to a Docker install.
**ZFS hosts:** the memory tile and host RAM alerts are ZFS ARC-aware. Reclaimable ARC cache is treated as available memory rather than used, so a large ARC does not inflate the gauge or trigger false low-memory alerts. When ARC stats are readable and the reclaimable amount is nonzero, the memory tile also shows how much raw memory is currently in use and how much of it the ARC can give back on demand. See [ZFS ARC-aware host memory](/getting-started/configuration#zfs-arc-aware-host-memory) for how to expose ARC stats to a Docker install.
**Virtual machines:** the memory tile shows hypervisor-ballooned memory (TrueNAS/KVM, Proxmox) as informational context. Unlike ARC, ballooned pages are host-reclaimed and the guest cannot get them back on demand, so the gauge, health verdict, and alerts continue to use the standard working-set percentage. See [VM memory ballooning](/getting-started/configuration#vm-memory-ballooning) for details.
**Virtual machines:** when balloon data is present (TrueNAS/KVM, Proxmox), the memory tile's percentage, gauge bar, used/total figures, and the dashboard health banner all use the balloon-adjusted values so they agree with each other. The tile adds context lines for the memory currently retained by the VM (`Current VM Memory`), how heavily that retained memory is used (`Current pressure`), and what the hypervisor has reclaimed (`Balloon reclaimable`). Unlike ARC, ballooned pages are host-reclaimed and the guest cannot get them back on demand, so host RAM alerts continue to use the standard working-set percentage to catch a hypervisor squeezing a guest. See [VM memory ballooning](/getting-started/configuration#vm-memory-ballooning) for details.
</Note>
## Stack health
+1 -1
View File
@@ -81,7 +81,7 @@ Sencho checks `SENCHO_ZFS_ARCSTATS_PATH`, then `/host/proc/spl/kstat/zfs/arcstat
On Linux virtual machines with memory ballooning enabled (TrueNAS/KVM, Proxmox, VMware), the hypervisor can reclaim guest memory through a balloon driver. The reclaimed amount is tracked in `/proc/meminfo` on the `Balloon:` line but standard memory counters do not account for it, so a ballooned VM can appear memory-critical when the guest workload is actually healthy.
Sencho reads the `Balloon:` field from `/proc/meminfo` when it is available and shows the ballooned amount on the dashboard memory tile alongside an effective-usage percentage. The memory gauge, health verdict, and host RAM alerts continue to use the standard working-set percentage: unlike ZFS ARC, ballooned memory is reclaimed by the hypervisor and the guest cannot get it back on demand, so balloon data is informational context rather than a factor in alerting or health decisions. When `/proc/meminfo` is unreadable or the `Balloon:` field is absent, the behavior is unchanged.
Sencho reads the `Balloon:` field from `/proc/meminfo` when it is available. When that data is present, the memory tile's percentage, gauge bar, used/total figures, and the dashboard health banner use the balloon-adjusted values so they agree with each other. The tile also shows how much memory the VM currently retains (`Current VM Memory`), how heavily that retained memory is used (`Current pressure`), and what the hypervisor has reclaimed (`Balloon reclaimable`). Host RAM alerts are deliberately stricter: they keep using the standard working-set percentage, because unlike ZFS ARC, ballooned memory is reclaimed by the hypervisor and the guest cannot get it back on demand, so a hypervisor squeezing a guest must still raise an alert even when the adjusted numbers look healthy. When `/proc/meminfo` is unreadable or the `Balloon:` field is absent, the behavior is unchanged.
`/proc/meminfo` is usually visible inside the container at `/proc/meminfo` with no extra configuration. If your runtime does not expose it, mount it read-only: