Package com.datastax.driver.core.policies

Class LatencyAwarePolicy

  • All Implemented Interfaces:
    ChainableLoadBalancingPolicy, LoadBalancingPolicy
    public class LatencyAwarePolicy
extends Object
implements ChainableLoadBalancingPolicy
    A wrapper load balancing policy that adds latency awareness to a child policy.

    When used, this policy will collect the latencies of the queries to each Cassandra node and maintain a per-node average latency score. The nodes that are slower than the best performing node by more than a configurable threshold will be moved to the end of the query plan (that is, they will only be tried if all other nodes failed). Note that this policy only penalizes slow nodes, it does not globally sort the query plan by latency.

    LWT statements: if Statement.isLWT() returns true, this policy does not apply latency-based reordering and returns the child policy's query plan as-is. This is to preserve LWT-specific routing assumptions (for example deterministic replica selection when using TokenAwarePolicy).

    The latency score for a given node is a based on a form of exponential moving average. In other words, the latency score of a node is the average of its previously measured latencies, but where older measurements gets an exponentially decreasing weight. The exact weight applied to a newly received latency is based on the time elapsed since the previous measure (to account for the fact that latencies are not necessarily reported with equal regularity, neither over time nor between different nodes).

    Once a node is excluded from query plans (because its averaged latency grew over the exclusion threshold), its latency score will not be updated anymore (since it is not queried). To give a chance to this node to recover, the policy has a configurable retry period. The policy will not penalize a host for which no measurement has been collected for more than this retry period.

    Please see the LatencyAwarePolicy.Builder class and methods for more details on the possible parameters of this policy.

    Since:
    1.0.4

    • Method Detail

      • builder

        public static LatencyAwarePolicy.Builder 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.
        Returns:
        the created builder.

      • init

        public void init​(Cluster cluster,
                 Collection<Host> hosts)
        Description copied from interface: LoadBalancingPolicy
        Initialize this load balancing policy.

        Note that the driver guarantees that it will call this method exactly once per policy object and will do so before any call to another of the methods of the policy.

        Specified by:
        init in interface LoadBalancingPolicy
        Parameters:
        cluster - the Cluster instance for which the policy is created.
        hosts - the initial hosts to use.

      • distance

        public HostDistance distance​(Host host)
        Returns the HostDistance for the provided host.
        Specified by:
        distance in interface LoadBalancingPolicy
        Parameters:
        host - the host of which to return the distance of.
        Returns:
        the HostDistance to host as returned by the wrapped policy.

      • newQueryPlan

        public Iterator<Host> newQueryPlan​(String loggedKeyspace,
                                   Statement statement)
        Returns the hosts to use for a new query.

        The returned plan will be the same as the plan generated by the child policy, except that nodes that are slower than the best performing node by more than a configurable threshold will be moved to the end (that is, they will only be tried if all other nodes failed). Note that this policy only penalizes slow nodes, it does not globally sort the query plan by latency.

        Specified by:
        newQueryPlan in interface LoadBalancingPolicy
        Parameters:
        loggedKeyspace - the currently logged keyspace.
        statement - the statement for which to build the plan.
        Returns:
        the new query plan.

      • getScoresSnapshot

        public LatencyAwarePolicy.Snapshot getScoresSnapshot()
        Returns a snapshot of the scores (latency averages) maintained by this policy.
        Returns:
        a new (immutable) LatencyAwarePolicy.Snapshot object containing the current latency scores maintained by this policy.

      • onUp

        public void onUp​(Host host)
        Description copied from interface: LoadBalancingPolicy
        Called when a node is determined to be up.
        Specified by:
        onUp in interface LoadBalancingPolicy
        Parameters:
        host - the host that has been detected up.

      • onDown

        public void onDown​(Host host)
        Description copied from interface: LoadBalancingPolicy
        Called when a node is determined to be down.
        Specified by:
        onDown in interface LoadBalancingPolicy
        Parameters:
        host - the host that has been detected down.

      • onAdd

        public void onAdd​(Host host)
        Description copied from interface: LoadBalancingPolicy
        Called when a new node is added to the cluster.

        The newly added node should be considered up.

        Specified by:
        onAdd in interface LoadBalancingPolicy
        Parameters:
        host - the host that has been newly added.

      • close

        public void close()
        Description copied from interface: LoadBalancingPolicy
        Gets invoked at cluster shutdown.

        This gives the policy the opportunity to perform some cleanup, for instance stop threads that it might have started.

        Specified by:
        close in interface LoadBalancingPolicy