Struct scylla::transport::load_balancing::LatencyAwarenessBuilder

pub struct LatencyAwarenessBuilder { /* private fields */ }

The builder of LatencyAwareness module of DefaultPolicy.

(For more information about latency awareness, see DefaultPolicyBuilder::latency_awareness()). It is intended to be created and configured by the user and then passed to DefaultPolicyBuilder, like this:

Example

use scylla::load_balancing::{
    LatencyAwarenessBuilder, DefaultPolicy
};

let latency_awareness_builder = LatencyAwarenessBuilder::new()
    .exclusion_threshold(3.)
    .minimum_measurements(200);

let policy = DefaultPolicy::builder()
    .latency_awareness(latency_awareness_builder)
    .build();

Implementations

impl LatencyAwarenessBuilder

pub fn new() -> Self

Creates a builder of LatencyAwareness module of DefaultPolicy.

pub fn minimum_measurements(self, minimum_measurements: usize) -> Self

Sets minimum measurements for latency awareness (if there have been fewer measurements taken for a node, the node will not be penalised).

Penalising nodes is based on an average of their recently measured average latency. This average is only meaningful if a minimum of measurements have been collected. This is what this option controls. If fewer than minimum_measurements data points have been collected for a given host, the policy will never penalise that host. Note that the number of collected measurements for a given host is reset if the node is restarted. The default for this option is 50.

pub fn retry_period(self, retry_period: Duration) -> Self

Sets retry period for latency awareness (max time that a node is being penalised).

The retry period defines how long a node may be penalised by the policy before it is given a 2nd chance. More precisely, a node is excluded from query plans if both his calculated average latency is exclusion_threshold 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 retry_period. Since penalised nodes will likely not see their latency updated, this is basically how long the policy will exclude a node.

pub fn exclusion_threshold(self, exclusion_threshold: f64) -> Self

Sets exclusion threshold for latency awareness (a threshold for a node to be penalised).

The exclusion threshold controls how much worse the average latency of a node must be compared to the fastest performing node for it to be penalised by the policy. For example, if set to 2, the resulting policy excludes nodes that are more than twice slower than the fastest node.

pub fn update_rate(self, update_rate: Duration) -> Self

Sets update rate for latency awareness (how often is the global minimal average latency updated).

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 this reason, the minimum is only re-calculated at the given 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 unnecessarily slow for instance).

pub fn scale(self, scale: Duration) -> Self

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

The 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 = (t - t') / scale
alpha = 1 - (ln(d+1) / d)
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).

Trait Implementations

impl Clone for LatencyAwarenessBuilder

fn clone(&self) -> LatencyAwarenessBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LatencyAwarenessBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LatencyAwarenessBuilder

fn default() -> Self

Returns the “default value” for a type.