doc/rgw: warn about rgw_usage_max_shards consistency

Add documentation warnings explaining that all RGW daemons and
radosgw-admin commands must use the same rgw_usage_max_shards value.
Mismatched shard counts cause writes and reads/trim to target different
objects, resulting in seemingly empty usage logs or failed cleanup.

Also document the --rgw-usage-max-shards command-line parameter for
radosgw-admin as an alternative to global config.

Fixes: https://tracker.ceph.com/issues/76459
Signed-off-by: Olivier Chaze <olivier.chaze@infomaniak.com>

diff --git a/doc/man/8/radosgw.rst b/doc/man/8/radosgw.rst
index 6dee83e946585bc6db4ce9531d7634f570770492..1807ba3750ed79854be5f7239b86810425bc8c7f 100644 (file)
--- a/doc/man/8/radosgw.rst
+++ b/doc/man/8/radosgw.rst
@@ -213,6 +213,15 @@ configures the number of seconds between log flushes, and the flush
 threshold specify how many entries can be kept before resorting to
 synchronous flush.
 
+.. warning:: All RGW instances and ``radosgw-admin`` commands must use the
+   same value for ``rgw_usage_max_shards``. If values differ between daemons
+   or between the cluster and the admin tool, usage log reads and trims
+   will target different objects than where data was written, causing
+   seemingly empty results or failed cleanup. Use
+   ``ceph config set global rgw_usage_max_shards <N>`` to enforce a
+   consistent value across the cluster. Alternatively, ``radosgw-admin``
+   supports the ``--rgw-usage-max-shards`` command-line parameter.
+
 
 Availability
 ============

diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst
index 18df6218b79fb0da4c618ca5a73bf7e41b04122a..28c823b99538e3b109fb559cc2cc8055d48c044d 100644 (file)
--- a/doc/radosgw/admin.rst
+++ b/doc/radosgw/admin.rst
@@ -944,6 +944,14 @@ ID, as in the following example command:
 
    radosgw-admin usage show --show-log-entries=false
 
+.. note:: If ``usage show`` returns empty results even though usage logging is
+   enabled and the cluster is active, verify that ``rgw_usage_max_shards`` is
+   set consistently across all RGW daemons and for ``radosgw-admin``.
+   A mismatch causes reads to target different objects than where data was
+   written. Use ``ceph config set global rgw_usage_max_shards <N>`` to enforce
+   a consistent value. Alternatively, ``radosgw-admin`` supports the
+   ``--rgw-usage-max-shards`` command-line parameter.
+
 
 Trim Usage
 ----------
@@ -959,6 +967,15 @@ example commands:
    radosgw-admin usage trim --uid=johndoe      
    radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31
 
+.. note:: If ``usage trim`` appears to have no effect (e.g., ``usage show`` still
+   returns data or omap keys are not reduced), verify that
+   ``rgw_usage_max_shards`` is set consistently across all RGW daemons and for
+   ``radosgw-admin``. A mismatch causes trim operations to target different
+   objects than where data was written. Use
+   ``ceph config set global rgw_usage_max_shards <N>`` to enforce a consistent
+   value. Alternatively, ``radosgw-admin`` supports the
+   ``--rgw-usage-max-shards`` command-line parameter.
+
 Usage Log Key Transition
 -------------------------
 

diff --git a/src/common/options/rgw.yaml.in b/src/common/options/rgw.yaml.in
index c535064a828e0e6ad270fd7e327af15a2bffd213..147cfe5c8a0b6e910453fe959cf582f96fede870 100644 (file)
--- a/src/common/options/rgw.yaml.in
+++ b/src/common/options/rgw.yaml.in
@@ -1684,7 +1684,12 @@ options:
   level: advanced
   desc: Number of shards for usage log.
   long_desc: The number of RADOS objects that RGW will use in order to store the usage
-    log data.
+    log data. All RGW daemons and radosgw-admin commands must use the same value
+    for this option. If values differ, writes and reads/clears will target
+    different objects, causing usage data to appear empty or not be cleared.
+    Use ``ceph config set global rgw_usage_max_shards <N>`` to ensure consistency
+    across the cluster. Alternatively, ``radosgw-admin`` supports the
+    ``--rgw-usage-max-shards`` command-line parameter.
   fmt_desc: The maximum number of shards for usage logging.
   default: 32
   services: