From 906dba604de1033c02076b441a1206bdc40bdb2a Mon Sep 17 00:00:00 2001 From: Olivier Chaze Date: Tue, 12 May 2026 16:32:10 +0200 Subject: [PATCH] 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 --- doc/man/8/radosgw.rst | 9 +++++++++ doc/radosgw/admin.rst | 17 +++++++++++++++++ src/common/options/rgw.yaml.in | 7 ++++++- 3 files changed, 32 insertions(+), 1 deletion(-) diff --git a/doc/man/8/radosgw.rst b/doc/man/8/radosgw.rst index 6dee83e94658..1807ba3750ed 100644 --- 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 `` 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 18df6218b79f..28c823b99538 100644 --- 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 `` 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 `` 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 c535064a828e..147cfe5c8a0b 100644 --- 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 `` 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: -- 2.47.3