public class LatencyAwarePolicy extends Object implements ChainableLoadBalancingPolicy
When used, this policy will collect the latencies of the queries to each Cassandra node and maintain a per-node latency score (an average). Based on these scores, the policy will penalize (technically, it will ignore them unless no other nodes are up) the nodes that are slower than the best performing node by more than some configurable amount (the exclusion threshold).
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.
Modifier and Type | Class and Description |
---|---|
static class |
LatencyAwarePolicy.Builder
Helper builder object to create a latency aware policy.
|
static class |
LatencyAwarePolicy.Snapshot
An immutable snapshot of the per-host scores (and stats in general)
maintained by
LatencyAwarePolicy to base its decision upon. |
Modifier and Type | Method and Description |
---|---|
static LatencyAwarePolicy.Builder |
builder(LoadBalancingPolicy childPolicy)
Creates a new latency aware policy builder given the child policy
that the resulting policy should wrap.
|
HostDistance |
distance(Host host)
Returns the HostDistance for the provided host.
|
LoadBalancingPolicy |
getChildPolicy()
Returns the child policy.
|
LatencyAwarePolicy.Snapshot |
getScoresSnapshot()
Returns a snapshot of the scores (latency averages) maintained by this
policy.
|
void |
init(Cluster cluster,
Collection<Host> hosts)
Initialize this load balancing policy.
|
Iterator<Host> |
newQueryPlan(String loggedKeyspace,
Statement statement)
Returns the hosts to use for a new query.
|
void |
onAdd(Host host)
Called when a new node is added to the cluster.
|
void |
onDown(Host host)
Called when a node is determined to be down.
|
void |
onRemove(Host host)
Called when a node is removed from the cluster.
|
void |
onSuspected(Host host)
Called when a node is suspected to be dead.
|
void |
onUp(Host host)
Called when a node is determined to be up.
|
public LoadBalancingPolicy getChildPolicy()
ChainableLoadBalancingPolicy
getChildPolicy
in interface ChainableLoadBalancingPolicy
public static LatencyAwarePolicy.Builder builder(LoadBalancingPolicy childPolicy)
childPolicy
- the load balancing policy to wrap with latency
awareness.public void init(Cluster cluster, Collection<Host> hosts)
LoadBalancingPolicy
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.
init
in interface LoadBalancingPolicy
cluster
- the Cluster
instance for which the policy is created.hosts
- the initial hosts to use.public HostDistance distance(Host host)
distance
in interface LoadBalancingPolicy
host
- the host of which to return the distance of.host
as returned by the wrapped policy.public Iterator<Host> newQueryPlan(String loggedKeyspace, Statement statement)
The returned plan will be the same as the plan generated by the
child policy, but with the (initial) exclusion of hosts whose recent
(averaged) latency is more than exclusionThreshold * minLatency
(where minLatency
is the (averaged) latency of the fastest
host).
The hosts that are initially excluded due to their latency will be returned by this iterator, but only only after all non-excluded hosts of the child policy have been returned.
newQueryPlan
in interface LoadBalancingPolicy
loggedKeyspace
- the currently logged keyspace.statement
- the statement for which to build the plan.public LatencyAwarePolicy.Snapshot getScoresSnapshot()
LatencyAwarePolicy.Snapshot
object containing the current
latency scores maintained by this policy.public void onUp(Host host)
Host.StateListener
onUp
in interface Host.StateListener
host
- the host that has been detected up.public void onSuspected(Host host)
Host.StateListener
A node is suspected to be dead when an error occurs on one of it's
opened connection. As soon as an host is suspected, a connection attempt
to that host is immediately tried. If this succeed, then it means that
the connection was disfunctional but that the node was not really down.
If this fails however, this means the node is truly dead, onDown() is
called and further reconnection attempts are scheduled according to the
ReconnectionPolicy
in place.
When this event is triggered, it is possible to call the host
Host.getInitialReconnectionAttemptFuture()
method to wait until the
initial and immediate reconnection attempt succeed or fail.
Note that some StateListener may ignore that event. If a node that
that is suspected down turns out to be truly down (that is, the driver
cannot successfully connect to it right away), then Host.StateListener.onDown(com.datastax.driver.core.Host)
will
be called.
onSuspected
in interface Host.StateListener
public void onDown(Host host)
Host.StateListener
onDown
in interface Host.StateListener
host
- the host that has been detected down.public void onAdd(Host host)
Host.StateListener
The newly added node should be considered up.
onAdd
in interface Host.StateListener
host
- the host that has been newly added.public void onRemove(Host host)
Host.StateListener
onRemove
in interface Host.StateListener
host
- the removed host.Copyright © 2014. All rights reserved.