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 d3e1cac48b04528575548b5712adca2b62a518b7..dbd6ed03e967486b05d357f65e537f15f525c020 100644 (file)
--- 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 19efe64ac3666c96a0950fc564d392fe3116f1f9..c5a96d0f1f7b2655c79566c82a8e6ca831b5e9f9 100644 (file)
--- 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 dd3b9d9c4aa9be255badfe7254aeea530c056614..f7f9019d09aaef63474a909831167c9b7f69067f 100644 (file)
--- 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 #