DOC: config: explain the effect of the weights on random's draws

"balance random" draws the servers on the consistent hash ring, where a
server gets 16 points per unit of weight. With the default weight of 1,
the shares of the ring are uneven (between about 2% and 4% for 32
servers, computed from the ring), so some servers are drawn twice as
often as others. Using the same higher weight for all servers, such as
100, makes the shares almost even.

Measured on 32 servers with 4 slow ones (with the peak EWMA option under
review, which compares the response times of the drawn servers), raising
the weight of all servers from 1 to 100 brought the share of the
requests sent to the slow servers from 2.0% to 1.5%, the same as a
uniform draw.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Aleksandar Lazic <al-haproxy@none.at>

diff --git a/doc/configuration.txt b/doc/configuration.txt
index fe77e3fd2aabc46322f95038ead9daceba1752bf..ee08fca77f3f17cd01fbb94c091fe2d4aefb9859 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -6948,6 +6948,15 @@ balance url_param <param> [check_post]
                   the Power of Two Random Choices and is described here :
                   http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf
 
+                  The servers are drawn on the consistent hash ring, where each
+                  server gets 16 points per unit of weight. With the default
+                  weight of 1, the share of the ring of each server is uneven:
+                  in a farm of 32 servers it varies between about 2% and 4%,
+                  and the servers with a larger share are drawn more often.
+                  Using the same higher weight for all servers, such as 100,
+                  makes the shares almost even and the distribution closer to a
+                  uniform draw, at the expense of a larger tree.
+
                   For backends in LOG mode, the number of draws is ignored and
                   a single random is picked since there is no notion of server
                   load. Random log balancing can be useful with large farms or