From 4c709c2fcddac0ecf8e46a7a7a0de8eee7f480d4 Mon Sep 17 00:00:00 2001 From: mpl Date: Fri, 7 Feb 2020 17:26:05 +0100 Subject: [PATCH] Improve rate-limiting doc --- docs/configuration/commons.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/configuration/commons.md b/docs/configuration/commons.md index ab973f5a3..dd567b8d2 100644 --- a/docs/configuration/commons.md +++ b/docs/configuration/commons.md @@ -249,8 +249,14 @@ Multiple sets of rates can be added to each frontend, but the time periods must ``` In the above example, frontend1 is configured to limit requests by the client's ip address. -An average of 100 requests every 10 seconds is allowed and an average of 5 requests every 3 seconds. -These can "burst" up to 200 and 10 in each period respectively. +A sustained rate of 100 requests every 10 seconds (10 req/s) is allowed for rateset1, and 5 requests every 3 seconds (~1.67 req/s) for rateset2. +In addition, these can "burst" up to 200 and 10 in each period respectively. + +Another way to describe the above parameters, is to use the [leaky bucket](https://en.wikipedia.org/wiki/Leaky_bucket) analogy: +for rateset1, the size of the bucket is 200 drops, and it is leaking at a rate of 10 drop/s. +If the incoming rate of drops falling into the bucket gets high enough that the bucket gets filled, +any subsequent drop overflows out of the bucket (i.e. the request is discarded). +This situation holds until the incoming rate gets low enough again, and remains that way, for the water level in the bucket to go down. Valid values for `extractorfunc` are: * `client.ip`