org.LatencyUtils
Class LatencyStats

java.lang.Object
  org.LatencyUtils.LatencyStats

public class LatencyStats
extends Object

LatencyStats objects are used to track the behavior of latencies recorded using recordLatency(long)). Latency behavior can be examined using detailed interval and accumulated histograms (see Histogram). Recorded latencies are auto-corrected for experienced pauses by leveraging pause detectors and moving window average interval estimators, compensating for coordinated omission.

Correction Technique

Whenever a pause is detected, appropriate pause correction values are captured in each LatencyStats instance, based on that instance's estimated inter-recording intervalEndTimes.

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 (must be separately set using setDefaultPauseDetector(org.LatencyUtils.PauseDetector)), a default histogram update interval (1 sec), a default histogram range and accuracy (1 usec to 1hr, 2 decimal points of accuracy), and a default moving window estimator (1024 entry moving window, time capped at 10 seconds).

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

Method Summary

void	addAccumulatedHistogramTo(org.HdrHistogram.Histogram toHistogram) Add the values of the accumulated latency histogram to the given histogram
void	addIntervalHistogramTo(org.HdrHistogram.Histogram toHistogram) Add the values of the latest interval latency histogram to the given histogram
void	forceIntervalUpdate() Force an update of the interval and accumulated histograms from the current recorded data.
org.HdrHistogram.Histogram	getAccumulatedHistogram() Get a copy of the accumulated latency histogram:
void	getAccumulatedHistogramInto(org.HdrHistogram.Histogram targetHistogram) Place a copy of the accumulated latency histogram's values into the given histogram
IntervalEstimator	getIntervalEstimator() get the IntervalEstimator used by this LatencyStats object
org.HdrHistogram.Histogram	getIntervalHistogram() Get a copy of the latest interval latency histogram:
void	getIntervalHistogramInto(org.HdrHistogram.Histogram targetHistogram) Place a copy of the latest interval latency histogram's values into the given histogram
PauseDetector	getPauseDetector() get the PauseDetector used by this LatencyStats object
org.HdrHistogram.Histogram	getUncorrectedAccumulatedHistogram() Get a copy of the uncorrected accumulated latency histogram (values will not include corrections for detected pauses)
org.HdrHistogram.Histogram	getUncorrectedIntervalHistogram() Get a copy of the uncorrected latest interval latency histogram (values will not include corrections for detected pauses)
void	recordLatency(long latency) Record a latency value in the LatencyStats object
void	resetAccumulatedHistogram() Reset the contents of the accumulated histogram
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 (must be separately set using setDefaultPauseDetector(org.LatencyUtils.PauseDetector)), a default histogram update interval (1 sec), a default histogram range and accuracy (1 usec to 1hr, 2 decimal points of accuracy), and a default moving window estimator (1024 entry moving window, time capped at 10 seconds).

LatencyStats

public LatencyStats(long lowestTrackableLatency,
                    long highestTrackableLatency,
                    int numberOfSignificantValueDigits,
                    long histogramUpdateInterval,
                    int numberOfRecentHistogramIntervalsToTrack,
                    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

histogramUpdateInterval - The length (in nanoseconds) of the automatically updating time interval.

numberOfRecentHistogramIntervalsToTrack - Number of recent intervalEndTimes to track

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

recordLatency

public void recordLatency(long latency)

Record a latency value in the LatencyStats object

Parameters:

latency - latency value (in nanoseconds) to record

getAccumulatedHistogram

public org.HdrHistogram.Histogram getAccumulatedHistogram()

Get a copy of the accumulated latency histogram:

Returns:

a copy of the accumulated latency histogram

getAccumulatedHistogramInto

public void getAccumulatedHistogramInto(org.HdrHistogram.Histogram targetHistogram)

Place a copy of the accumulated latency histogram's values into the given histogram

Parameters:

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

addAccumulatedHistogramTo

public void addAccumulatedHistogramTo(org.HdrHistogram.Histogram toHistogram)

Add the values of the accumulated latency histogram to the given histogram

Parameters:

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

getUncorrectedAccumulatedHistogram

public org.HdrHistogram.Histogram getUncorrectedAccumulatedHistogram()

Get a copy of the uncorrected accumulated latency histogram (values will not include corrections for detected pauses)

Returns:

a copy of the uncorrected accumulated latency histogram

getIntervalHistogram

public org.HdrHistogram.Histogram getIntervalHistogram()

Get a copy of the latest interval latency histogram:

Returns:

a copy of the interval latency histogram

getIntervalHistogramInto

public void getIntervalHistogramInto(org.HdrHistogram.Histogram targetHistogram)

Place a copy of the latest interval latency histogram's values into the given histogram

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 of the latest interval latency histogram to the given histogram

Parameters:

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

getUncorrectedIntervalHistogram

public org.HdrHistogram.Histogram getUncorrectedIntervalHistogram()

Get a copy of the uncorrected latest interval latency histogram (values will not include corrections for detected pauses)

Returns:

a copy of the uncorrected interval latency histogram

forceIntervalUpdate

public void forceIntervalUpdate()

Force an update of the interval and accumulated histograms from the current recorded data. A new interval sample will be performed regardless of the timing of histogramUpdateInterval set at construction time. When histogramUpdateInterval is set to 0, forceIntervalUpdate() provides the only means by which intervalEndTimes are updated.

resetAccumulatedHistogram

public void resetAccumulatedHistogram()

Reset the contents of the accumulated histogram

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