public class TokenBucket extends Object implements MeasurableStat
TokenBucket is a MeasurableStat implementing a token bucket algorithm
that is usable within a Sensor.
The Quota.bound() defined the refill rate of the bucket while the maximum burst or
the maximum number of credits of the bucket is defined by
* MetricConfig#timeWindowMs() * Quota#bound().
The quota is considered as exhausted when the amount of remaining credits in the bucket
is below zero. The enforcement is done by the Sensor.
Token Bucket vs Rate based Quota:
The current sampled rate based quota does not cope well with bursty workloads. The issue is
that a unique and large sample can hold the average above the quota until it is discarded.
Practically, when this happens, one must wait until the sample is expired to bring the rate
below the quota even though less time would be theoretically required. As an example, let's
imagine that we have:
- Quota (Q) = 5
- Samples (S) = 100
- Window (W) = 1s
A burst of 560 brings the average rate (R) to 5.6 (560 / 100). The expected throttle time is
computed as follow: ((R - Q / Q * S * W)) = ((5.6 - 5) / 5 * 100 * 1) = 12 secs. In practice,
the average rate won't go below the quota before the burst is dropped from the samples so one
must wait 100s (S * W).
The token bucket relies on continuously updated amount of credits. Therefore, it does not
suffers from the above issue. The same example would work as follow:
- Quota (Q) = 5
- Burst (B) = 5 * 1 * 100 = 500 (Q * S * W)
A burst of 560 brings the amount of credits to -60. One must wait 12s (-(-60)/5) to refill the
bucket to zero.| Constructor and Description |
|---|
TokenBucket() |
TokenBucket(TimeUnit unit) |
| Modifier and Type | Method and Description |
|---|---|
double |
measure(MetricConfig config,
long timeMs)
Measure this quantity and return the result as a double
|
void |
record(MetricConfig config,
double value,
long timeMs)
Record the given value
|
String |
toString() |
public TokenBucket()
public TokenBucket(TimeUnit unit)
public double measure(MetricConfig config, long timeMs)
Measurablemeasure in interface Measurableconfig - The configuration for this metrictimeMs - The POSIX time in milliseconds the measurement is being takenpublic void record(MetricConfig config, double value, long timeMs)
Stat