From 3e2a2c2cbf37b07ba44ac9286029db732c680672 Mon Sep 17 00:00:00 2001
From: Souvik Sarkar <souvik.sarkar@suse.com>
Date: Tue, 21 Jan 2025 21:12:34 +0530
Subject: [PATCH] Additional clarification about %vmeff exceeding 100% in newer
 kernels (#1782)

* note on vmeff clarification

* Editorial fixes as per Daria's suggestion

* Minor typo fix

* Modified content based on Tanja's feedback
---
 xml/utilities.xml | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/xml/utilities.xml b/xml/utilities.xml
index 53a04c4980..d00ae68998 100644
--- a/xml/utilities.xml
+++ b/xml/utilities.xml
@@ -479,6 +479,32 @@ Average:    92.08    211.70 1097.30     0.26 12010.28      0.00      0.00      0
       page swapped out is being reused) or 0 (no pages have been scanned).
       The value should not drop below 30.
      </para>
+     <note>
+      <title>Understanding and addressing <guimenu>%vmeff</guimenu> values exceeding 100% in modern Linux
+      kernels</title>
+      <para>
+       A <guimenu>%vmeff</guimenu> value exceeding 100% means that the number of pages reclaimed (<guimenu>pgsteal</guimenu>) is reported
+       as higher than the number of pages scanned (<guimenu>pgscank</guimenu>) during memory reclamation. This is
+       unexpected because under normal circumstances, the kernel should not reclaim more pages than it scans.
+      </para>
+      <para>
+       In modern Linux kernels (5.x and higher), changes in memory management and page reclamation
+       accounting make <guimenu>%vmeff</guimenu> less reliable as a measure of virtual memory efficiency. These
+       changes include separating background and direct reclaim metrics, tracking memory operations
+       with greater granularity, introducing deferred reclamation, and adding support for NUMA-aware
+       and cgroup-based memory management. Such updates can cause tools like <command>sar</command>
+       to misinterpret metrics like <guimenu>pgsteal</guimenu> and <guimenu>pgscank</guimenu>, resulting in <guimenu>%vmeff</guimenu> value
+       exceeding 100% in certain situations.
+      </para>
+      <para>
+       If <guimenu>%vmeff</guimenu> exceeds 100%, avoid using it as a performance indicator. Instead, analyze memory
+       performance by monitoring <guimenu>pgpgin/s</guimenu> and <guimenu>pgpgout/s</guimenu> for paging activity, <guimenu>majflt/s</guimenu> and <guimenu>fault/s</guimenu>
+       for page faults, and memory utilization details in <filename>/proc/meminfo</filename> (for
+       example, <guimenu>Active</guimenu>, <guimenu>Inactive</guimenu>, <guimenu>Dirty</guimenu> and <guimenu>Writeback</guimenu>). Additionally, correlate these metrics with
+       application-level performance and I/O patterns to identify potential memory bottlenecks or
+       inefficiencies.
+      </para>
+     </note>
     </sect4>
     <sect4 xml:id="sec-util-multi-sar-report-disk">
      <title>Block device statistics report: <command>sar</command> <option>-d</option></title>