com.datastax.driver.core

Class PercentileTracker

java.lang.Object

com.datastax.driver.core.PercentileTracker

All Implemented Interfaces:

LatencyTracker

Direct Known Subclasses:

ClusterWidePercentileTracker, PerHostPercentileTracker

public abstract class PercentileTracker
extends Object
implements LatencyTracker

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

Percentiles may be computed separately for different categories of requests; this is implementation-dependent and determined by computeKey(Host, Statement, Exception).

This class is used by percentile-aware components such as QueryLogger.Builder.withDynamicThreshold(PercentileTracker, double) QueryLogger} and PercentileSpeculativeExecutionPolicy.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PercentileTracker.Builder<B,T> Base class for PercentileTracker implementation builders.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PercentileTracker(long highestTrackableLatencyMillis, int numberOfSignificantValueDigits, int minRecordedValues, long intervalMs) Builds a new instance.

Method Summary

Modifier and Type	Method and Description
protected abstract Object	computeKey(Host host, Statement statement, Exception exception) Computes a key used to categorize measurements.
long	getLatencyAtPercentile(Host host, Statement statement, Exception exception, double percentile) Returns the request latency at a given percentile.
protected boolean	include(Host host, Statement statement, Exception exception) Determines whether a particular measurement should be included.
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

Constructor Detail

PercentileTracker

protected PercentileTracker(long highestTrackableLatencyMillis,
                            int numberOfSignificantValueDigits,
                            int minRecordedValues,
                            long intervalMs)

Builds a new instance.

See Also:

PercentileTracker.Builder

Method Detail

computeKey

protected abstract Object computeKey(Host host,
                                     Statement statement,
                                     Exception exception)

Computes a key used to categorize measurements. Measurements with the same key will be recorded in the same histogram.

It's recommended to keep the number of distinct keys low, in order to limit the memory footprint of the histograms.

Parameters:

host - the host that was queried.

statement - the statement that was executed.

exception - if the query failed, the corresponding exception.

Returns:

the key.

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,
                                   Statement statement,
                                   Exception exception,
                                   double percentile)

Returns the request latency at a given percentile.

Parameters:

host - the host (if this is relevant in the way percentiles are categorized).

statement - the statement (if this is relevant in the way percentiles are categorized).

exception - the exception (if this is relevant in the way percentiles are categorized).

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.

See Also:

computeKey(Host, Statement, Exception)

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.

include

protected boolean include(Host host,
                          Statement statement,
                          Exception exception)

Determines whether a particular measurement should be included.

This is used to ignore measurements that could skew the statistics; for example, we typically want to ignore invalid query errors because they have a very low latency and would make a given cluster/host appear faster than it really is.

Parameters:

host - the host that was queried.

statement - the statement that was executed.

exception - if the query failed, the corresponding exception.

Returns:

whether the measurement should be included.