feat: add virtual memory compatibility for zfs arc architectures

CREDITS

@@ -832,6 +832,10 @@ N: Anthony Ryan
 W: https://github.com/anthonyryan1
 I: 2272
 
+N: Hudson Gerwing
+W: https://github.com/hewdoe
+I: 2385
+
 N: Sam Gross
 W: https://github.com/colesbury
 I: 2401, 2427

HISTORY.rst

@@ -8,6 +8,7 @@ XXXX-XX-XX
 **Enhancements**
 
 - 2471_: use Vulture CLI tool to detect dead code.
+- 2385_, [Linux]: add support for zfs arc memory stats. (patch by Hudson Gerwing)
 
 **Bug fixes**
 

psutil/__init__.py

@@ -184,7 +184,7 @@
 
     # functions
     "pid_exists", "pids", "process_iter", "wait_procs",             # proc
-    "virtual_memory", "swap_memory",                                # memory
+    "virtual_memory", "swap_memory", "apply_zfs_arcstats",          # memory
     "cpu_times", "cpu_percent", "cpu_times_percent", "cpu_count",   # cpu
     "cpu_stats",  # "cpu_freq", "getloadavg"
     "net_io_counters", "net_connections", "net_if_addrs",           # network
@@ -2048,6 +2048,14 @@ def swap_memory():
     return _psplatform.swap_memory()
 
 
+def apply_zfs_arcstats(vm_stats):
+    """Apply ZFS ARC stats to virtual memory stats."""
+    # Only applicable to linux distros
+    if LINUX:
+        return _psplatform.apply_zfs_arcstats(vm_stats)
+    raise NotImplementedError("ZFS ARC stats are only available on Linux")
+
+
 # =====================================================================
 # --- disks/partitions related functions
 # =====================================================================

psutil/_pslinux.py

@@ -603,6 +603,57 @@ def swap_memory():
     return _common.sswap(total, used, free, percent, sin, sout)
 
 
+def apply_zfs_arcstats(vm_stats: svmem):
+    """Apply ZFS ARC (Adaptive Replacement Cache) stats to
+    input virtual memory call results"""
+    mems = {}
+
+    try:
+        with open_binary('%s/spl/kstat/zfs/arcstats' % get_procfs_path()) as f:
+            for line in f:
+                fields = line.split()
+                try:
+                    mems[fields[0]] = int(fields[2])
+                except ValueError:
+                    # Not a key: value line
+                    continue
+
+        zfs_min = mems[b'c_min']
+        zfs_size = mems[b'size']
+    except (KeyError, FileNotFoundError):
+        msg = ("ZFS ARC memory is not configured on this device, "
+               "no modification made to virtual memory stats")
+        warnings.warn(msg, RuntimeWarning, stacklevel=2)
+        return vm_stats
+
+    # ZFS ARC memory consumption is not reported by /proc/meminfo.
+    # Running this func will include reclaimable ZFS ARC
+    # memory in the returned values.
+    # See:
+    # https://www.reddit.com/r/zfs/comments/ha0p7f/understanding_arcstat_and_free/
+    # https://github.com/openzfs/zfs/issues/10255
+
+    shrinkable_size = max(zfs_size - zfs_min, 0)
+    used = vm_stats.used + vm_stats.shared - shrinkable_size
+    cached = vm_stats.cached - vm_stats.shared + shrinkable_size
+    available = vm_stats.available + shrinkable_size
+    percent = usage_percent(vm_stats.total - available, vm_stats.total, round_=1)
+
+    return svmem(
+        vm_stats.total,
+        available,
+        percent,
+        used,
+        vm_stats.free,
+        vm_stats.active,
+        vm_stats.inactive,
+        vm_stats.buffers,
+        cached,
+        vm_stats.shared,
+        vm_stats.slab,
+    )
+
+
 # =====================================================================
 # --- CPU
 # =====================================================================