From: Dhairya Parmar <dparmar@redhat.com>
Date: Mon, 15 Jun 2026 12:33:05 +0000 (+0530)
Subject: doc/cephfs: add note explainin the new batching technique
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=627af6cfc76acc7b3580f0ff7e6b0443b0ea9fff;p=ceph.git

doc/cephfs: add note explainin the new batching technique

Partially-Fixes: https://tracker.ceph.com/issues/76422
Signed-off-by: Dhairya Parmar <dparmar@redhat.com>
---

diff --git a/doc/cephfs/cephfs-journal-tool.rst b/doc/cephfs/cephfs-journal-tool.rst
index d3e1cac48b0..dbd6ed03e96 100644
--- a/doc/cephfs/cephfs-journal-tool.rst
+++ b/doc/cephfs/cephfs-journal-tool.rst
@@ -150,6 +150,8 @@ Filtering:
 * ``--dname <string>`` only include events referring to this named dentry within a directory
   fragment (may only be used in conjunction with ``--frag``)
 * ``--client <int>`` only include events from this client session ID
+* ``--max-rss <bytes>`` (works only with ``recover_dentries`` for now) limits the RSS of the cephfs-journal-tool
+  by scanning and flushing journal events in batches
 
 Filters may be combined on an AND basis (i.e. only the intersection of events from each filter).
 
diff --git a/doc/cephfs/disaster-recovery-experts.rst b/doc/cephfs/disaster-recovery-experts.rst
index 19efe64ac36..c5a96d0f1f7 100644
--- a/doc/cephfs/disaster-recovery-experts.rst
+++ b/doc/cephfs/disaster-recovery-experts.rst
@@ -65,6 +65,18 @@ InoTables of each ``in`` MDS rank, to indicate that any written inodes' numbers
 are now in use. In simple cases, this will result in an entirely valid backing
 store state.
 
+.. warning::
+   
+    Large journal sizes can cause the tool's Resident Set Size (RSS) to spike
+    significantly. Use the ``--max-rss <bytes>`` flag to limit memory usage, keeping the following
+    in mind:
+
+    * **Performance Impact:** Do not set this value too low. Restricting memory excessively will
+        severely degrade runtime performance and prolong the recovery process.
+    * **30% Buffer Rule:** Maintain a safety buffer of at least 30% relative to the tool's total
+        memory budget. For example, if 100 GiB can be allotted to the tool, cap its RSS limit at
+        70 GiB: ``--max-rss 75161927680``.
+
 .. warning::
 
     The resulting state of the backing store is not guaranteed to be
diff --git a/doc/cephfs/disaster-recovery.rst b/doc/cephfs/disaster-recovery.rst
index dd3b9d9c4aa..f7f9019d09a 100644
--- a/doc/cephfs/disaster-recovery.rst
+++ b/doc/cephfs/disaster-recovery.rst
@@ -85,6 +85,18 @@ Using first-damage.py
 
       cephfs-journal-tool --rank=<fs_name>:0 event recover_dentries summary
 
+   .. warning::
+
+      Large journal sizes can cause the tool's Resident Set Size (RSS) to
+      spike significantly. To prevent excessive memory consumption, use the
+      ``--max-rss <bytes>`` flag to cap the RSS. 
+
+      Avoid setting this value too low, as it will severely degrade runtime
+      performance and prolong recovery. It is best practice to maintain a memory
+      buffer of at least 30% of the tool's total budget. For example, if 100 GiB
+      is to be allotted to the tool, cap the RSS at 70 GiB
+      (``--max-rss 75161927680``).
+
 #. Reset the journal:
    
    .. prompt:: bash #