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, 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 org.HdrHistogram.Histogram).

LatencyStats instances maintain internal histogram data that track all recoded latencies. Interval histogram data can be sampled with the getIntervalHistogram, getIntervalHistogramInto, or addIntervalHistogramTo 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 calls.

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

Correction Technique

In addition to tracking the raw latency recordings provided via recordLatency, 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 org.LatencyUtils.SimplePauseDetector, which uses consensus observation of a pause across multiple observing threads as a detection technique.

Custom pause detectors can be provided (by subclassing org.LatencyUtils.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 org.LatencyUtils.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 and Inner Type Summary

Modifier and Type	Class and Description
public static class	LatencyStats.Builder A fluent API builder class for creating LatencyStats objects.
private static class	LatencyStats.PauseTracker PauseTracker is used to feed pause correction histograms whenever a pause is reported:

Field Summary

Modifier and Type	Field and Description
private Histogram	activePauseCorrectionsHistogram
private volatile AtomicHistogram	activeRecordingHistogram
private static LatencyStats.Builder	defaultBuilder
private static PauseDetector	defaultPauseDetector
private final long	highestTrackableLatency
private Histogram	inactivePauseCorrectionsHistogram
private AtomicHistogram	inactiveRawDataHistogram
private final IntervalEstimator	intervalEstimator
private static final TimeServices.ScheduledExecutor	latencyStatsScheduledExecutor
private final long	lowestTrackableLatency
private final int	numberOfSignificantValueDigits
private final PauseDetector	pauseDetector
private final LatencyStats.PauseTracker	pauseTracker
private final WriterReaderPhaser	recordingPhaser

Constructor Summary

Access	Constructor and Description
public	LatencyStats() Create a LatencyStats object with default settings.
public	LatencyStats(final long Lowest trackable latency in latency histograms lowestTrackableLatency, final long Highest trackable latency in latency histograms highestTrackableLatency, final int Number of significant [decimal] digits of accuracy in latency histograms numberOfSignificantValueDigits, final int Length of window in moving window interval estimator intervalEstimatorWindowLength, final long Time cap (in nanoseconds) of window in moving window interval estimator intervalEstimatorTimeCap, final PauseDetector The pause detector to use for identifying and correcting for pauses pauseDetector)

Access

Constructor and Description

public

LatencyStats()

Create a LatencyStats object with default settings.

public

LatencyStats(final long

Lowest trackable latency in latency histograms

lowestTrackableLatency, final long

Highest trackable latency in latency histograms

highestTrackableLatency, final int

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

numberOfSignificantValueDigits, final int

Length of window in moving window interval estimator

intervalEstimatorWindowLength, final long

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

intervalEstimatorTimeCap, final PauseDetector

The pause detector to use for identifying and correcting for pauses

pauseDetector)

Method Summary

Modifier and Type	Method and Description
public synchronized void	addIntervalHistogramTo(Histogram the histogram into which the interval histogram's data should be added toHistogram) Add the values value counts accumulated since the last interval histogram was taken into `toHistogram`.
public static PauseDetector	Returns: the current default pause detector 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.
public IntervalEstimator	Returns: the IntervalEstimator used by this LatencyStats object getIntervalEstimator() get the IntervalEstimator used by this LatencyStats object
public synchronized Histogram	Returns: a copy of the latest interval latency histogram getIntervalHistogram() Get a new interval histogram which will include the value counts accumulated since the last interval histogram was taken.
public synchronized void	getIntervalHistogramInto(Histogram the histogram into which the interval histogram's data should be copied targetHistogram) Place a copy of the value counts accumulated since the last interval histogram was taken into `targetHistogram`.
public synchronized Histogram	Returns: a copy of the latest uncorrected interval latency histogram getLatestUncorrectedIntervalHistogram() Get a copy of the uncorrected latest interval latency histogram.
public synchronized void	getLatestUncorrectedIntervalHistogramInto(Histogram the histogram into which the interval histogram's data should be copied targetHistogram) Place a copy of the values of the latest uncorrected interval latency histogram.
public PauseDetector	Returns: the PauseDetector used by this LatencyStats object getPauseDetector() get the PauseDetector used by this LatencyStats object
private synchronized void	recordDetectedPause(long pauseLength, long pauseEndTime)
public void	recordLatency(long latency value (in nanoseconds) to record latency) Record a latency value in the LatencyStats object
public static void	setDefaultPauseDetector(PauseDetector the pause detector to use as a default when no explicit pause detector is provided pauseDetector) Set the default pause detector for the LatencyStats class.
public synchronized void	stop() Stop operation of this LatencyStats object, removing it from the pause detector's notification list
private synchronized void	swapHistograms()
private void	swapPauseCorrectionHistograms()
private void	swapRecordingHistograms()
private void	trackRecordingInterval()
private synchronized void	updateHistograms()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

activePauseCorrectionsHistogram	back to summary
private Histogram activePauseCorrectionsHistogram

activeRecordingHistogram	back to summary
private volatile AtomicHistogram activeRecordingHistogram

defaultBuilder	back to summary
private static LatencyStats.Builder defaultBuilder

defaultPauseDetector	back to summary
private static PauseDetector defaultPauseDetector

highestTrackableLatency	back to summary
private final long highestTrackableLatency

inactivePauseCorrectionsHistogram	back to summary
private Histogram inactivePauseCorrectionsHistogram

inactiveRawDataHistogram	back to summary
private AtomicHistogram inactiveRawDataHistogram

intervalEstimator	back to summary
private final IntervalEstimator intervalEstimator

latencyStatsScheduledExecutor	back to summary
private static final TimeServices.ScheduledExecutor latencyStatsScheduledExecutor

lowestTrackableLatency	back to summary
private final long lowestTrackableLatency

numberOfSignificantValueDigits	back to summary
private final int numberOfSignificantValueDigits

pauseDetector	back to summary
private final PauseDetector pauseDetector

pauseTracker	back to summary
private final LatencyStats.PauseTracker pauseTracker

recordingPhaser	back to summary
private final WriterReaderPhaser recordingPhaser

Constructor Detail

LatencyStats back to summary

LatencyStats	back to summary
public LatencyStats() Create a LatencyStats object with default settings. use the default pause detector (supplied separately set using `setDefaultPauseDetector`, 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)

public LatencyStats()

Create a LatencyStats object with default settings.

use the default pause detector (supplied separately set using setDefaultPauseDetector, 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	back to summary
public LatencyStats(final long lowestTrackableLatency, final long highestTrackableLatency, final int numberOfSignificantValueDigits, final int intervalEstimatorWindowLength, final long intervalEstimatorTimeCap, final PauseDetector pauseDetector) Parameters lowestTrackableLatency:long Lowest trackable latency in latency histograms highestTrackableLatency:long Highest trackable latency in latency histograms numberOfSignificantValueDigits:int Number of significant [decimal] digits of accuracy in latency histograms intervalEstimatorWindowLength:int Length of window in moving window interval estimator intervalEstimatorTimeCap:long Time cap (in nanoseconds) of window in moving window interval estimator pauseDetector:PauseDetector The pause detector to use for identifying and correcting for pauses

LatencyStats

back to summary

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

Parameters

lowestTrackableLatency:long: Lowest trackable latency in latency histograms
highestTrackableLatency:long: Highest trackable latency in latency histograms
numberOfSignificantValueDigits:int: Number of significant [decimal] digits of accuracy in latency histograms
intervalEstimatorWindowLength:int: Length of window in moving window interval estimator
intervalEstimatorTimeCap:long: Time cap (in nanoseconds) of window in moving window interval estimator
pauseDetector:PauseDetector: The pause detector to use for identifying and correcting for pauses

Method Detail

addIntervalHistogramTo back to summary

addIntervalHistogramTo	back to summary
public synchronized void addIntervalHistogramTo(Histogram toHistogram) Add the values value counts accumulated since the last interval histogram was taken into `toHistogram`. Calling `addIntervalHistogramTo`() will reset the interval value counts, and start accumulating value counts for the next interval. Parameters toHistogram:Histogram the histogram into which the interval histogram's data should be added

public synchronized void addIntervalHistogramTo(Histogram toHistogram)

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

Parameters

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

getDefaultPauseDetector	back to summary
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:PauseDetector the current default pause detector

getDefaultPauseDetector

back to summary

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:PauseDetector: the current default pause detector

getIntervalEstimator	back to summary
public IntervalEstimator getIntervalEstimator() get the IntervalEstimator used by this LatencyStats object Returns:IntervalEstimator the IntervalEstimator used by this LatencyStats object

getIntervalEstimator

back to summary

public IntervalEstimator getIntervalEstimator()

get the IntervalEstimator used by this LatencyStats object

Returns:IntervalEstimator: the IntervalEstimator used by this LatencyStats object

getIntervalHistogram back to summary

getIntervalHistogram	back to summary
public synchronized 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:Histogram a copy of the latest interval latency histogram

public synchronized 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:Histogram: a copy of the latest interval latency histogram

getIntervalHistogramInto back to summary

getIntervalHistogramInto	back to summary
public synchronized void getIntervalHistogramInto(Histogram targetHistogram) Place a copy of the value counts accumulated since the last interval histogram was taken into `targetHistogram`. Calling `getIntervalHistogramInto`() will reset the interval value counts, and start accumulating value counts for the next interval. Parameters targetHistogram:Histogram the histogram into which the interval histogram's data should be copied

public synchronized void getIntervalHistogramInto(Histogram targetHistogram)

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

Parameters

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

getLatestUncorrectedIntervalHistogram back to summary

getLatestUncorrectedIntervalHistogram	back to summary
public synchronized 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`, or `addIntervalHistogramTo`. Returns:Histogram a copy of the latest uncorrected interval latency histogram

public synchronized 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, or addIntervalHistogramTo.

Returns:Histogram: a copy of the latest uncorrected interval latency histogram

getLatestUncorrectedIntervalHistogramInto back to summary

getLatestUncorrectedIntervalHistogramInto	back to summary
public synchronized void getLatestUncorrectedIntervalHistogramInto(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`, or `addIntervalHistogramTo`. Parameters targetHistogram:Histogram the histogram into which the interval histogram's data should be copied

public synchronized void getLatestUncorrectedIntervalHistogramInto(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, or addIntervalHistogramTo.

Parameters

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

getPauseDetector	back to summary
public PauseDetector getPauseDetector() get the PauseDetector used by this LatencyStats object Returns:PauseDetector the PauseDetector used by this LatencyStats object

getPauseDetector

back to summary

public PauseDetector getPauseDetector()

get the PauseDetector used by this LatencyStats object

Returns:PauseDetector: the PauseDetector used by this LatencyStats object

recordDetectedPause	back to summary
private synchronized void recordDetectedPause(long pauseLength, long pauseEndTime)

recordLatency	back to summary
public void recordLatency(long latency) Record a latency value in the LatencyStats object Parameters latency:long latency value (in nanoseconds) to record

recordLatency

back to summary

public void recordLatency(long latency)

Record a latency value in the LatencyStats object

Parameters

latency:long: latency value (in nanoseconds) to record

setDefaultPauseDetector	back to summary
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:PauseDetector the pause detector to use as a default when no explicit pause detector is provided

setDefaultPauseDetector

back to summary

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:PauseDetector: the pause detector to use as a default when no explicit pause detector is provided

stop	back to summary
public synchronized void stop() Stop operation of this LatencyStats object, removing it from the pause detector's notification list

swapHistograms	back to summary
private synchronized void swapHistograms()

swapPauseCorrectionHistograms	back to summary
private void swapPauseCorrectionHistograms()

swapRecordingHistograms	back to summary
private void swapRecordingHistograms()

trackRecordingInterval	back to summary
private void trackRecordingInterval()

updateHistograms	back to summary
private synchronized void updateHistograms()

org.LatencyUtils back to summary

public Class LatencyStats.Builder

Class Inheritance

extends Object

java.lang.Object
org.LatencyUtils.LatencyStats.Builder

A fluent API builder class for creating LatencyStats objects.
Uses the following defaults:

lowestTrackableLatency: 1000 (1 usec)
highestTrackableLatency: 3600000000000L (1 hour)
numberOfSignificantValueDigits: 2
intervalEstimatorWindowLength: 1024
intervalEstimatorTimeCap: 10000000000L (10 sec)
pauseDetector: (use LatencyStats default)

Field Summary

Modifier and Type	Field and Description
private long	highestTrackableLatency
private long	intervalEstimatorTimeCap
private int	intervalEstimatorWindowLength
private long	lowestTrackableLatency
private int	numberOfSignificantValueDigits
private PauseDetector	pauseDetector

Constructor Summary

Access	Constructor and Description
public	Builder()

Method Summary

Modifier and Type	Method and Description
public LatencyStats	build()
public static LatencyStats.Builder	create()
public LatencyStats.Builder	highestTrackableLatency(long highestTrackableLatency)
public LatencyStats.Builder	intervalEstimatorTimeCap(long intervalEstimatorTimeCap)
public LatencyStats.Builder	intervalEstimatorWindowLength(int intervalEstimatorWindowLength)
public LatencyStats.Builder	lowestTrackableLatency(long lowestTrackableLatency)
public LatencyStats.Builder	numberOfSignificantValueDigits(int numberOfSignificantValueDigits)
public LatencyStats.Builder	pauseDetector(PauseDetector pauseDetector)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

highestTrackableLatency	back to summary
private long highestTrackableLatency

intervalEstimatorTimeCap	back to summary
private long intervalEstimatorTimeCap

intervalEstimatorWindowLength	back to summary
private int intervalEstimatorWindowLength

lowestTrackableLatency	back to summary
private long lowestTrackableLatency

numberOfSignificantValueDigits	back to summary
private int numberOfSignificantValueDigits

pauseDetector	back to summary
private PauseDetector pauseDetector

Constructor Detail

Builder	back to summary
public Builder()

Method Detail

build	back to summary
public LatencyStats build()

create	back to summary
public static LatencyStats.Builder create()

highestTrackableLatency	back to summary
public LatencyStats.Builder highestTrackableLatency(long highestTrackableLatency)

intervalEstimatorTimeCap	back to summary
public LatencyStats.Builder intervalEstimatorTimeCap(long intervalEstimatorTimeCap)

intervalEstimatorWindowLength	back to summary
public LatencyStats.Builder intervalEstimatorWindowLength(int intervalEstimatorWindowLength)

lowestTrackableLatency	back to summary
public LatencyStats.Builder lowestTrackableLatency(long lowestTrackableLatency)

numberOfSignificantValueDigits	back to summary
public LatencyStats.Builder numberOfSignificantValueDigits(int numberOfSignificantValueDigits)

pauseDetector	back to summary
public LatencyStats.Builder pauseDetector(PauseDetector pauseDetector)

org.LatencyUtils back to summary

private Class LatencyStats.PauseTracker

Class Inheritance

extends WeakReference<LatencyStats>
implements PauseDetectorListener

java.lang.Object
java.lang.ref.Reference
java.lang.ref.WeakReference
org.LatencyUtils.LatencyStats.PauseTracker

All Implemented Interfaces

org.LatencyUtils.PauseDetectorListener

PauseTracker is used to feed pause correction histograms whenever a pause is reported:

Field Summary

Modifier and Type	Field and Description
pack-priv final PauseDetector	pauseDetector

Constructor Summary

Access	Constructor and Description
pack-priv	PauseTracker(final PauseDetector pauseDetector, final LatencyStats latencyStats)

Method Summary

Modifier and Type	Method and Description
public void	handlePauseEvent(final long Length of reported pause (in nanoseconds) pauseLength, final long Time sampled at end of reported pause (in nanoTime units). pauseEndTime) Implements org.LatencyUtils.PauseDetectorListener.handlePauseEvent. handle a pause event notification.
public void	stop()

Field Detail

pauseDetector	back to summary
pack-priv final PauseDetector pauseDetector

Constructor Detail

PauseTracker	back to summary
pack-priv PauseTracker(final PauseDetector pauseDetector, final LatencyStats latencyStats)

Method Detail

handlePauseEvent

back to summary

public void handlePauseEvent(final long pauseLength, final long pauseEndTime)

Implements org.LatencyUtils.PauseDetectorListener.handlePauseEvent.

Doc from org.LatencyUtils.PauseDetectorListener.handlePauseEvent.

handle a pause event notification.

Parameters

pauseLength:long: Length of reported pause (in nanoseconds)
pauseEndTime:long: Time sampled at end of reported pause (in nanoTime units).

stop	back to summary
public void stop()