com.lmax.disruptor.collections

Class Histogram

java.lang.Object

com.lmax.disruptor.collections.Histogram

public final class Histogram
extends java.lang.Object

Histogram for tracking the frequency of observations of values below interval upper bounds.

This class is useful for recording timings across a large number of observations when high performance is required.

The interval bounds are used to define the ranges of the histogram buckets. If provided bounds are [10,20,30,40,50] then there will be five buckets, accessible by index 0-4. Any value 0-10 will fall into the first interval bar, values 11-20 will fall into the second bar, and so on.

Constructor Summary

Constructors

Constructor and Description
Histogram(long[] upperBounds) Create a new Histogram with a provided list of interval bounds.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	addObservation(long value) Add an observation to the histogram and increment the counter for the interval it matches.
void	addObservations(Histogram histogram) Add observations from another Histogram into this one. Histograms must have the same intervals.
void	clear() Clear the list of interval counters
long	getCount() Count total number of recorded observations.
long	getCountAt(int index) Get the count of observations at a given index.
long	getFourNinesUpperBound() Calculate the upper bound within which 99.99% of observations fall.
long	getMax() Get the maximum observed value.
java.math.BigDecimal	getMean() Calculate the mean of all recorded observations. The mean is calculated by summing the mid points of each interval multiplied by the count for that interval, then dividing by the total count of observations.
long	getMin() Get the minimum observed value.
int	getSize() Size of the list of interval bars (ie: count of interval bars).
long	getTwoNinesUpperBound() Calculate the upper bound within which 99% of observations fall.
long	getUpperBoundAt(int index) Get the upper bound of an interval for an index.
long	getUpperBoundForFactor(double factor) Get the interval upper bound for a given factor of the observation population. Note this does not get the actual percentile measurement, it only gets the bucket
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Histogram

public Histogram(long[] upperBounds)

Create a new Histogram with a provided list of interval bounds.

Parameters:

upperBounds - of the intervals. Bounds must be provided in order least to greatest, and lowest bound must be greater than or equal to 1.

Throws:

java.lang.IllegalArgumentException - if any of the upper bounds are less than or equal to zero

java.lang.IllegalArgumentException - if the bounds are not in order, least to greatest

Method Detail

getSize

public int getSize()

Size of the list of interval bars (ie: count of interval bars).

Returns:

size of the interval bar list.

getUpperBoundAt

public long getUpperBoundAt(int index)

Get the upper bound of an interval for an index.

Parameters:

index - of the upper bound.

Returns:

the interval upper bound for the index.

getCountAt

public long getCountAt(int index)

Get the count of observations at a given index.

Parameters:

index - of the observations counter.

Returns:

the count of observations at a given index.

addObservation

public boolean addObservation(long value)

Add an observation to the histogram and increment the counter for the interval it matches.

Parameters:

value - for the observation to be added.

Returns:

return true if in the range of intervals and successfully added observation; otherwise false.

addObservations

public void addObservations(Histogram histogram)

Add observations from another Histogram into this one.

Histograms must have the same intervals.

Parameters:

histogram - from which to add the observation counts.

Throws:

java.lang.IllegalArgumentException - if interval count or values do not match exactly

clear

public void clear()

Clear the list of interval counters

getCount

public long getCount()

Count total number of recorded observations.

Returns:

the total number of recorded observations.

getMin

public long getMin()

Get the minimum observed value.

Returns:

the minimum value observed.

getMax

public long getMax()

Get the maximum observed value.

Returns:

the maximum of the observed values;

getMean

public java.math.BigDecimal getMean()

Calculate the mean of all recorded observations.

The mean is calculated by summing the mid points of each interval multiplied by the count for that interval, then dividing by the total count of observations. The max and min are considered for adjusting the top and bottom bin when calculating the mid point, this minimises skew if the observed values are very far away from the possible histogram values.

Returns:

the mean of all recorded observations.

getTwoNinesUpperBound

public long getTwoNinesUpperBound()

Calculate the upper bound within which 99% of observations fall.

Returns:

the upper bound for 99% of observations.

getFourNinesUpperBound

public long getFourNinesUpperBound()

Calculate the upper bound within which 99.99% of observations fall.

Returns:

the upper bound for 99.99% of observations.

getUpperBoundForFactor

public long getUpperBoundForFactor(double factor)

Get the interval upper bound for a given factor of the observation population.

Note this does not get the actual percentile measurement, it only gets the bucket

Parameters:

factor - representing the size of the population.

Returns:

the interval upper bound.

Throws:

java.lang.IllegalArgumentException - if factor < 0.0 or factor > 1.0

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object