org.LatencyUtils
Class LatencyStats

java.lang.Object
  org.LatencyUtils.LatencyStats

public class LatencyStats
extends java.lang.Object

LatencyStats objects are used to track and report on the behavior of latencies across measurements. recorded into a a given LatencyStats instance. Latencies are recorded using recordLatency(long), which provides a thread safe, wait free, and lossless recording method. The accumulated behavior across the recorded latencies in a given LatencyStats instance can be examined in detail using interval and accumulated HdrHistogram histograms (see Histogram).

LatencyStats instances maintain internal histogram data that track all recoded latencies. Interval histogram data can be sampled with the getIntervalHistogram(), getIntervalHistogramInto(org.HdrHistogram.Histogram), or addIntervalHistogramTo(org.HdrHistogram.Histogram) calls.

Recorded latencies are auto-corrected for experienced pauses by leveraging pause detectors and moving window average interval estimators, compensating for coordinated omission. While typical histogram use deals with corrected data, LatencyStats instances do keep track of the raw, uncorrected records, which can be accessed via the getLatestUncorrectedIntervalHistogram() and getLatestUncorrectedIntervalHistogramInto(org.HdrHistogram.Histogram) calls.

LatencyStats objects can be instantiated either directly via the provided constructors, or by using the fluent API builder supported by LatencyStats.Builder.

Correction Technique

In addition to tracking the raw latency recordings provided via recordLatency(long), each LatencyStats instance maintains an internal interval estimator that tracks the expected interval between latency recordings. Whenever a stall in measurement is detected by a given pause detector, each LatencyStats instances that uses that pause detector will be notified, and will generate correcting latency entries (that are separately tracked internally). Correcting latency entries are computed to "fill in" detected measurement pauses by projecting the observed recording rate into the pause gap, and creating a linearly diminishing latency measurement for each missed recording interval.

Pause detection and interval estimation are both configurable, and each LatencyStats instance can operate with potentially independent pause detector and interval estimator settings.

A configurable default pause detector is (by default) shared between LatencyStats instances that are not provided with a specific pause detector at instantiation. If the default pause detector is not explicitly set, it will itself default to creating (and starting) a single instance of SimplePauseDetector, which uses consensus observation of a pause across multiple observing threads as a detection technique.

Custom pause detectors can be provided (by subclassing PauseDetector). E.g. a pause detector that pauses GC log output rather than directly measuring observations can be constructed. A custom pause detector can be especially useful in situations where a stall in the operation and latency measurement of an application's is known and detectable by the application level, but would not be detectable as a process-wide stall in execution (which SimplePauseDetector is built to detect).

Interval estimation is done by using a time-capped moving window average estimator, with the expected interval computed to be the average of measurement intervals within the window (with the window being capped by both count and time). See TimeCappedMovingAverageIntervalEstimator for more details. The estimator window length and time cap can both be configured when instantiating a LatencyStats object (defaults are 1024, and 10 seconds).

Nested Class Summary

static class

LatencyStats.Builder A fluent API builder class for creating LatencyStats objects.

Constructor Summary

LatencyStats()
Create a LatencyStats object with default settings.
use the default pause detector (supplied separately set using setDefaultPauseDetector(org.LatencyUtils.PauseDetector), which will itself default to a SimplePauseDetector if not explicitly supplied) use a default histogram update interval (1 sec) use a default histogram range and accuracy (1 usec to 1hr, 2 decimal points of accuracy) and use a default moving window estimator (1024 entry moving window, time capped at 10 seconds)

LatencyStats(long lowestTrackableLatency, long highestTrackableLatency, int numberOfSignificantValueDigits, int intervalEstimatorWindowLength, long intervalEstimatorTimeCap, PauseDetector pauseDetector)

Method Summary

void	addIntervalHistogramTo(org.HdrHistogram.Histogram toHistogram) Add the values value counts accumulated since the last interval histogram was taken into toHistogram.
static PauseDetector	getDefaultPauseDetector() Get the current default pause detector which will be used by newly constructed LatencyStats instances when the constructor is not explicitly provided with one.
IntervalEstimator	getIntervalEstimator() get the IntervalEstimator used by this LatencyStats object
org.HdrHistogram.Histogram	getIntervalHistogram() Get a new interval histogram which will include the value counts accumulated since the last interval histogram was taken.
void	getIntervalHistogramInto(org.HdrHistogram.Histogram targetHistogram) Place a copy of the value counts accumulated since the last interval histogram was taken into targetHistogram.
org.HdrHistogram.Histogram	getLatestUncorrectedIntervalHistogram() Get a copy of the uncorrected latest interval latency histogram.
void	getLatestUncorrectedIntervalHistogramInto(org.HdrHistogram.Histogram targetHistogram) Place a copy of the values of the latest uncorrected interval latency histogram.
PauseDetector	getPauseDetector() get the PauseDetector used by this LatencyStats object
void	recordLatency(long latency) Record a latency value in the LatencyStats object
static void	setDefaultPauseDetector(PauseDetector pauseDetector) Set the default pause detector for the LatencyStats class.
void	stop() Stop operation of this LatencyStats object, removing it from the pause detector's notification list

Methods inherited from class java.lang.Object

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

Constructor Detail

LatencyStats

public LatencyStats()

Create a LatencyStats object with default settings.

• use the default pause detector (supplied separately set using setDefaultPauseDetector(org.LatencyUtils.PauseDetector), which will itself default to a SimplePauseDetector if not explicitly supplied)
• use a default histogram update interval (1 sec)
• use a default histogram range and accuracy (1 usec to 1hr, 2 decimal points of accuracy)
• and use a default moving window estimator (1024 entry moving window, time capped at 10 seconds)

LatencyStats

public LatencyStats(long lowestTrackableLatency,
                    long highestTrackableLatency,
                    int numberOfSignificantValueDigits,
                    int intervalEstimatorWindowLength,
                    long intervalEstimatorTimeCap,
                    PauseDetector pauseDetector)

Parameters:

lowestTrackableLatency - Lowest trackable latency in latency histograms

highestTrackableLatency - Highest trackable latency in latency histograms

numberOfSignificantValueDigits - Number of significant [decimal] digits of accuracy in latency histograms

intervalEstimatorWindowLength - Length of window in moving window interval estimator

intervalEstimatorTimeCap - Time cap (in nanoseconds) of window in moving window interval estimator

pauseDetector - The pause detector to use for identifying and correcting for pauses

Method Detail

setDefaultPauseDetector

public static void setDefaultPauseDetector(PauseDetector pauseDetector)

Set the default pause detector for the LatencyStats class. Used by constructors that do not explicitly provide a pause detector.

Parameters:

pauseDetector - the pause detector to use as a default when no explicit pause detector is provided

getDefaultPauseDetector

public static PauseDetector getDefaultPauseDetector()

Get the current default pause detector which will be used by newly constructed LatencyStats instances when the constructor is not explicitly provided with one.

Returns:

the current default pause detector

recordLatency

public void recordLatency(long latency)

Record a latency value in the LatencyStats object

Parameters:

latency - latency value (in nanoseconds) to record

getIntervalHistogram

public org.HdrHistogram.Histogram getIntervalHistogram()

Get a new interval histogram which will include the value counts accumulated since the last interval histogram was taken.

Calling getIntervalHistogram()() will reset the interval value counts, and start accumulating value counts for the next interval.

Returns:

a copy of the latest interval latency histogram

getIntervalHistogramInto

public void getIntervalHistogramInto(org.HdrHistogram.Histogram targetHistogram)

Place a copy of the value counts accumulated since the last interval histogram was taken into targetHistogram. Calling getIntervalHistogramInto(org.HdrHistogram.Histogram)() will reset the interval value counts, and start accumulating value counts for the next interval.

Parameters:

targetHistogram - the histogram into which the interval histogram's data should be copied

addIntervalHistogramTo

public void addIntervalHistogramTo(org.HdrHistogram.Histogram toHistogram)

Add the values value counts accumulated since the last interval histogram was taken into toHistogram. Calling getIntervalHistogramInto(org.HdrHistogram.Histogram)() will reset the interval value counts, and start accumulating value counts for the next interval.

Parameters:

toHistogram - the histogram into which the interval histogram's data should be added

getLatestUncorrectedIntervalHistogram

public org.HdrHistogram.Histogram getLatestUncorrectedIntervalHistogram()

Get a copy of the uncorrected latest interval latency histogram. Values will not include corrections for detected pauses. The interval histogram copies will include all values points captured up to the latest call to call to one of getIntervalHistogram(), getIntervalHistogramInto(org.HdrHistogram.Histogram), or addIntervalHistogramTo(org.HdrHistogram.Histogram).

Returns:

a copy of the latest uncorrected interval latency histogram

getLatestUncorrectedIntervalHistogramInto

public void getLatestUncorrectedIntervalHistogramInto(org.HdrHistogram.Histogram targetHistogram)

Place a copy of the values of the latest uncorrected interval latency histogram. Values will not include corrections for detected pauses. The interval histogram copies will include all values points captured up to the latest call to call to one of getIntervalHistogram(), getIntervalHistogramInto(org.HdrHistogram.Histogram), or addIntervalHistogramTo(org.HdrHistogram.Histogram).

Parameters:

targetHistogram - the histogram into which the interval histogram's data should be copied

stop

public void stop()

Stop operation of this LatencyStats object, removing it from the pause detector's notification list

getIntervalEstimator

public IntervalEstimator getIntervalEstimator()

get the IntervalEstimator used by this LatencyStats object

Returns:

the IntervalEstimator used by this LatencyStats object

getPauseDetector

public PauseDetector getPauseDetector()

get the PauseDetector used by this LatencyStats object

Returns:

the PauseDetector used by this LatencyStats object