public static class LatencyAwarePolicy.Builder extends Object
LatencyAwarePolicy
. The only mandatory parameter is the child
policy that will be wrapped with latency awareness. The other parameters
can be set through the methods of this builder, but all have defaults (that
are documented in the javadoc of each method) if you don't.
If you observe that the resulting policy excludes hosts too aggressively or
not enough so, the main parameters to check are the exclusion threshold
(withExclusionThreshold(double)
) and scale (withScale(long, java.util.concurrent.TimeUnit)
).Modifier and Type | Field and Description |
---|---|
static double |
DEFAULT_EXCLUSION_THRESHOLD |
static int |
DEFAULT_MIN_MEASURE |
static long |
DEFAULT_RETRY_PERIOD_NANOS |
static long |
DEFAULT_SCALE_NANOS |
static long |
DEFAULT_UPDATE_RATE_NANOS |
Constructor and Description |
---|
Builder(LoadBalancingPolicy childPolicy)
Creates a new latency aware policy builder given the child policy
that the resulting policy wraps.
|
Modifier and Type | Method and Description |
---|---|
LatencyAwarePolicy |
build()
Builds a new latency aware policy using the options set on this
builder.
|
LatencyAwarePolicy.Builder |
withExclusionThreshold(double exclusionThreshold)
Sets the exclusion threshold to use for the resulting latency aware policy.
|
LatencyAwarePolicy.Builder |
withMininumMeasurements(int minMeasure)
Sets the minimum number of measurements per-host to consider for
the resulting latency aware policy.
|
LatencyAwarePolicy.Builder |
withRetryPeriod(long retryPeriod,
TimeUnit unit)
Sets the retry period for the resulting latency aware policy.
|
LatencyAwarePolicy.Builder |
withScale(long scale,
TimeUnit unit)
Sets the scale to use for the resulting latency aware policy.
|
LatencyAwarePolicy.Builder |
withUpdateRate(long updateRate,
TimeUnit unit)
Sets the update rate for the resulting latency aware policy.
|
public static final double DEFAULT_EXCLUSION_THRESHOLD
public static final long DEFAULT_SCALE_NANOS
public static final long DEFAULT_RETRY_PERIOD_NANOS
public static final long DEFAULT_UPDATE_RATE_NANOS
public static final int DEFAULT_MIN_MEASURE
public Builder(LoadBalancingPolicy childPolicy)
childPolicy
- the load balancing policy to wrap with latency
awareness.public LatencyAwarePolicy.Builder withExclusionThreshold(double exclusionThreshold)
exclusionThreshold
- the exclusion threshold to use. Must be
greater or equal to 1.IllegalArgumentException
- if exclusionThreshold < 1
.public LatencyAwarePolicy.Builder withScale(long scale, TimeUnit unit)
scale
provides control on how the weight given to older latencies
decreases over time. For a given host, if a new latency \(l\) is received at
time \(t\), and the previously calculated average is \(prev\) calculated at
time \(t'\), then the newly calculated average \(avg\) for that host is calculated
thusly:
\[
d = \frac{t - t'}{scale} \\
\alpha = 1 - \left(\frac{\ln(d+1)}{d}\right) \\
avg = \alpha * l + (1-\alpha) * prev
\]
Typically, with a scale
of 100 milliseconds (the default), if a new
latency is measured and the previous measure is 10 millisecond old (so \(d=0.1\)),
then \(\alpha\) will be around \(0.05\). In other words, the new latency will
weight 5% of the updated average. A bigger scale will get less weight to new
measurements (compared to previous ones), a smaller one will give them more weight.
The default scale (if this method is not used) is of 100 milliseconds. If unsure, try
this default scale first and experiment only if it doesn't provide acceptable results
(hosts are excluded too quickly or not fast enough and tuning the exclusion threshold
doesn't help).scale
- the scale to use.unit
- the unit of scale
.IllegalArgumentException
- if scale <e; 0
.public LatencyAwarePolicy.Builder withRetryPeriod(long retryPeriod, TimeUnit unit)
exclusionThreshold
times slower than the fastest node average latency (at the time the query plan is
computed) and his calculated average latency has been updated since
less than retryPeriod
. Since penalized nodes will likely not see their
latency updated, this is basically how long the policy will exclude a node.retryPeriod
- the retry period to use.unit
- the unit for retryPeriod
.IllegalArgumentException
- if retryPeriod < 0
.public LatencyAwarePolicy.Builder withUpdateRate(long updateRate, TimeUnit unit)
updateRate
- the update rate to use.unit
- the unit for updateRate
.IllegalArgumentException
- if updateRate <e; 0
.public LatencyAwarePolicy.Builder withMininumMeasurements(int minMeasure)
minMeasure
data points have been collected for
a given host, the policy will never penalize that host. Also, the
30% first measurement will be entirely ignored (in other words, the
30% * minMeasure
first measurement to a node are entirely
ignored, while the 70%
next ones are accounted in the latency
computed but the node won't get convicted until we've had at least
minMeasure
measurements).
Note that the number of collected measurements for a given host is
reset if the node is restarted.
The default for this option (if this method is not called) is 50.
Note that it is probably not a good idea to put this option too low
if only to avoid the influence of JVM warm-up on newly restarted
nodes.minMeasure
- the minimum measurements to consider.IllegalArgumentException
- if minMeasure < 0
.public LatencyAwarePolicy build()
LatencyAwarePolicy
.