doc: update crushtool.rst

Add --show-retry-exhaustion flag to doc

Signed-off-by: Kamoltat (Junior) Sirivadhna <ksirivad@redhat.com>

diff --git a/doc/man/8/crushtool.rst b/doc/man/8/crushtool.rst
index 4c848659655d0cee9bc80789b42ca749fa29c0c2..f1de7ef37c4f272585b38d65ab65ae00072e3b37 100644 (file)
--- a/doc/man/8/crushtool.rst
+++ b/doc/man/8/crushtool.rst
@@ -151,15 +151,35 @@ pools; it only runs simulations by mapping values in the range
    Displays how many attempts were needed to find a device mapping.
    For instance::
 
-      0:     95224
-      1:      3745
-      2:      2225
+      tries 0:     95224
+      tries 1:      3745
+      tries 2:      2225
       ..
 
    shows that **95224** mappings succeeded without retries, **3745**
    mappings succeeded with one attempts, etc. There are as many rows
    as the value of the **--set-choose-total-tries** option.
 
+.. option:: --show-retry-exhaustion
+
+   Checks whether any PG mappings hit the maximum retry limit
+   (typically 50 tries) and displays a warning if retry exhaustion
+   is detected. This is useful for validating CRUSH rules, especially
+   in stretch cluster configurations with exactly
+   2 datacenters and 4 replicas can potentially fail to map some PGs due to CRUSH's
+   pseudorandom selection repeatedly choosing the same datacenter.
+   Although, the probability is extremely low, we still want to detect this.
+   
+   Outputs either a warning message if exhaustion is detected::
+
+      WARNING: Retry exhaustion detected!
+        5 PG(s) hit the maximum retry limit of 50
+        This indicates CRUSH failed to find optimal placement for some PGs.
+
+   or a success message showing the maximum tries actually needed::
+
+      No retry exhaustion detected (maximum tries needed: 7 / 50)
+
 .. option:: --output-csv
 
    Creates CSV files (in the current directory) containing information