com.datastax.driver.core.policies
Class LatencyAwarePolicy.Builder

java.lang.Object
  com.datastax.driver.core.policies.LatencyAwarePolicy.Builder

Enclosing class:

LatencyAwarePolicy

public static class LatencyAwarePolicy.Builder
extends Object

Helper builder object to create a latency aware policy.

This helper allows to configure the different parameters used by LatencyAwarePolicy. The only mandatory option is the child policy that will be wrapped with latency awareness. The other parameters can be set through the method 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 exclude host too agressively or not enough so, the main parameter to check are the exclusion threashold (withExclusionThreshold(double)) and scale (withScale(long, java.util.concurrent.TimeUnit)).

Since:

1.0.4

Constructor Summary

LatencyAwarePolicy.Builder(LoadBalancingPolicy childPolicy)
Creates a new latency aware policy builder given the child policy that the resulting policy should wrap.

Method Summary

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 minimimum 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) Set the update rate for the resulting latency aware policy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LatencyAwarePolicy.Builder

public LatencyAwarePolicy.Builder(LoadBalancingPolicy childPolicy)

Creates a new latency aware policy builder given the child policy that the resulting policy should wrap.

Parameters:

childPolicy - the load balancing policy to wrap with latency awareness.

Method Detail

withExclusionThreshold

public LatencyAwarePolicy.Builder withExclusionThreshold(double exclusionThreshold)

Sets the exclusion threshold to use for the resulting latency aware policy.

The exclusion threshold controls how much worst the average latency of a node must be compared to the faster performing one for it to be penalized by the policy.

The default exclusion threshold (if this method is not called) is 2. In other words, the resulting policy excludes nodes that are more than twice slower than the fastest node.

Parameters:

exclusionThreshold - the exclusion threshold to use. Must be greater or equal to 1.

Returns:

this builder.

Throws:

IllegalArgumentException - if exclusionThreshold < 1.

withScale

public LatencyAwarePolicy.Builder withScale(long scale,
                                            TimeUnit unit)

Sets the scale to use for the resulting latency aware policy.

The scale provides control on how the weight given to older latencies decrease 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 10 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).

Parameters:

scale - the scale to use.

unit - the unit of scale.

Returns:

this builder.

Throws:

IllegalArgumentException - if scale &lte; 0.

withRetryPeriod

public LatencyAwarePolicy.Builder withRetryPeriod(long retryPeriod,
                                                  TimeUnit unit)

Sets the retry period for the resulting latency aware policy.

The retry period defines how long a node may be penalized by the policy before it is given a 2nd change. More precisely, a node is excluded from query plans if both his calculated average latency is exclusionThreshold times slower than the fastest 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 basically how long the policy will exclude a node.

Parameters:

retryPeriod - the retry period to use.

unit - the unit for retryPeriod.

Returns:

this builder.

Throws:

IllegalArgumentException - if retryPeriod < 0.

withUpdateRate

public LatencyAwarePolicy.Builder withUpdateRate(long updateRate,
                                                 TimeUnit unit)

Set the update rate for the resulting latency aware policy. The update rate defines how often the minimum average latency is recomputed. While the average latency score of each node is computed iteratively (updated each time a new latency is collected), the minimum score needs to be recomputed from scratch every time, which is slightly more costly. For that reason, that minimum is only re-calculated at fixed rate and cached between re-calculation.

The default update rate if 100 milliseconds, which should be appropriate for most applications. In particular, note that while we want to avoid to recompute the minimum for every query, that computation is not particularly intensive either and there is no reason to use a very slow rate (more than second is probably unecessarily slow for instance).

Parameters:

updateRate - the update rate to use.

unit - the unit for updateRate.

Returns:

this builder.

Throws:

IllegalArgumentException - if updateRate &lte; 0.

withMininumMeasurements

public LatencyAwarePolicy.Builder withMininumMeasurements(int minMeasure)

Sets the minimimum number of measurements per-host to consider for the resulting latency aware policy.

Penalizing nodes is based on an average of their recently measured average latency. That average is only meaningful if a minimum of measurements have been collected (moreover, a newly started Cassandra node will tend to perform relatively poorly on the first queries due to the JVM warmup). This is what this option controls. If less that minMeasure data points have been collected for a given host, the policy will never penalize that host. Note that the number of collected measurements for a given host is resetted

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 warmup on newly restarted nodes.

Parameters:

minMeasure - the minimum measurements to consider.

Returns:

this builder.

Throws:

IllegalArgumentException - if minMeasure < 0.

build

public LatencyAwarePolicy build()

Builds a new latency aware policy using the options set on this builder.

Returns:

the newly created LatencyAwarePolicy.