com.datastax.driver.core

Class PerHostPercentileTracker

java.lang.Object

com.datastax.driver.core.PerHostPercentileTracker

All Implemented Interfaces:

LatencyTracker

@Beta
public class PerHostPercentileTracker
extends Object
implements LatencyTracker

A LatencyTracker that records latencies for each host over a sliding time interval, and exposes an API to retrieve the latency at a given percentile.

To use this class, build an instance with builderWithHighestTrackableLatencyMillis(long) and register it with your Cluster instance:

 PerHostPercentileTracker tracker = PerHostPercentileTracker
     .builderWithHighestTrackableLatencyMillis(15000)
     .build();

 cluster.register(tracker);
 ...
 tracker.getLatencyAtPercentile(host1, 99.0);
 

This class uses HdrHistogram to record latencies: for each host, there is a "live" histogram where current latencies are recorded, and a "cached", read-only histogram that is used when clients call getLatencyAtPercentile(Host, double). Each time the cached histogram becomes older than the interval, the two histograms are switched. Note that statistics will not be available during the first interval at cluster startup, since we don't have a cached histogram yet.

Note that this class is currently marked "beta": it hasn't been extensively tested yet, and the API is still subject to change.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PerHostPercentileTracker.Builder Helper class to builder PerHostPercentileTracker instances with a fluent interface.

Method Summary

Modifier and Type	Method and Description
static PerHostPercentileTracker.Builder	builderWithHighestTrackableLatencyMillis(long highestTrackableLatencyMillis) Returns a builder to create a new instance.
long	getLatencyAtPercentile(Host host, double percentile) Returns the request latency for a host at a given percentile.
void	onRegister(Cluster cluster) Gets invoked when the tracker is registered with a cluster, or at cluster startup if the tracker was registered at initialization with Cluster.register(LatencyTracker).
void	onUnregister(Cluster cluster) Gets invoked when the tracker is unregistered from a cluster, or at cluster shutdown if the tracker was not unregistered.
void	update(Host host, Statement statement, Exception exception, long newLatencyNanos) A method that is called after each request to a Cassandra node with the duration of that operation.

Methods inherited from class java.lang.Object

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

Method Detail

builderWithHighestTrackableLatencyMillis

public static PerHostPercentileTracker.Builder builderWithHighestTrackableLatencyMillis(long highestTrackableLatencyMillis)

Returns a builder to create a new instance.

Parameters:

highestTrackableLatencyMillis - the highest expected latency. If a higher value is reported, it will be ignored and a warning will be logged. A good rule of thumb is to set it slightly higher than SocketOptions.getReadTimeoutMillis().

Returns:

the builder.

update

public void update(Host host,
                   Statement statement,
                   Exception exception,
                   long newLatencyNanos)

Description copied from interface: LatencyTracker

A method that is called after each request to a Cassandra node with the duration of that operation.

Note that there is no guarantee that this method won't be called concurrently by multiple threads, so implementations should synchronize internally if need be.

Specified by:

update in interface LatencyTracker

Parameters:

host - The Cassandra host on which a request has been performed. This parameter is never null.

statement - The Statement that has been executed. This parameter is never null.

exception - An Exception thrown when receiving the response, or null if the response was successful.

newLatencyNanos - the latency in nanoseconds of the operation. This latency corresponds to the time elapsed between when the query was sent to host and when the response was received by the driver (or the operation timed out, in which newLatencyNanos will approximately be the timeout value).

getLatencyAtPercentile

public long getLatencyAtPercentile(Host host,
                                   double percentile)

Returns the request latency for a host at a given percentile.

Parameters:

host - the host.

percentile - the percentile (for example, 99.0 for the 99th percentile).

Returns:

the latency (in milliseconds) at the given percentile, or a negative value if it's not available yet.

onRegister

public void onRegister(Cluster cluster)

Description copied from interface: LatencyTracker

Gets invoked when the tracker is registered with a cluster, or at cluster startup if the tracker was registered at initialization with Cluster.register(LatencyTracker).

Specified by:

onRegister in interface LatencyTracker

Parameters:

cluster - the cluster that this tracker is registered with.

onUnregister

public void onUnregister(Cluster cluster)

Description copied from interface: LatencyTracker

Gets invoked when the tracker is unregistered from a cluster, or at cluster shutdown if the tracker was not unregistered.

Specified by:

onUnregister in interface LatencyTracker

Parameters:

cluster - the cluster that this tracker was registered with.