docs: balancer: Elaborate what "average" means.

The wording "average" so far suggested a simple mean count, which it isn't.

It is important to document this, so that the user can follow
why the balancer is active or not.

Source for the logic (deviation computation and threshold check)
in `src/osd/OSDMap.cc`:

`calc_deviations()` - computes per-OSD deviation:

    float target = osd_weight.at(oid) * pgs_per_weight;
    float deviation = (float)opgs.size() - target;

Where `pgs_per_weight` is computed in `calc_pg_upmaps()`:

    float pgs_per_weight = total_pgs / osd_weight_total;

This also has the early threshold + early return:

    if (cur_max_deviation <= max_deviation) {
        ldout(cct, 10) << __func__ << " distribution is almost perfect" << dendl;
        return 0;
    }

`fill_overfull_underfull()` classifies OSDs using `max_deviation`:

    if (odev > max_deviation) {
        overfull.insert(oid);        // deviation > +5 -> source candidate
    }
    if (odev < -(int)max_deviation) {
        underfull.push_back(oid);    // deviation < -5 -> target candidate
    }

Signed-off-by: Niklas Hambüchen <mail@nh2.me>

diff --git a/doc/rados/operations/balancer.rst b/doc/rados/operations/balancer.rst
index 9d92a81e2a2f236675aec1e2fe237580e53d1ca6..a797f9be205fbb272e698f2e6db70d2f5c6a38ba 100644 (file)
--- a/doc/rados/operations/balancer.rst
+++ b/doc/rados/operations/balancer.rst
@@ -63,9 +63,22 @@ at the potential cost of greater impact on client operations.
 There is a separate setting ``upmap_max_deviation`` for how uniform the
 distribution of PGs must be for the module to consider the cluster adequately
 balanced.  At the time of writing (June 2025), this value defaults to ``5``,
-which means that if a given OSD's PG replicas vary by five or fewer above or
-below the cluster's average, it will be considered sufficiently balanced.
-
+which means that if a given OSD's PG shard count deviates by five or fewer
+from its weight-proportional target, it will be considered sufficiently
+balanced.
+
+More precisely, the balancer computes a per-OSD target shard count as::
+
+   target = osd_weight * (total_shards / total_weight)
+
+where ``osd_weight`` is the OSD's CRUSH weight times its reweight
+(the ``REWEIGHT`` value from ``ceph osd df``), ``total_shards`` is
+``pool_size * pg_num`` summed over all balanced pools,
+and ``total_weight`` is the sum of those per-OSD weights.
+The deviation is then ``actual_shard_count - target``.
+If no OSD's absolute deviation exceeds
+``upmap_max_deviation``, the balancer considers the distribution
+sufficiently balanced and makes no changes.
 
 This value of PG replicas/shards (as distinct from logical PGs) is reported
 by the ``ceph osd df`` command under the ``PGS`` column and the variance