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.
Modifier and Type | Field and Description |
---|---|
private long[] |
counts |
private long |
maxValue |
private long |
minValue |
private long[] |
upperBounds |
Constructor and Description |
---|
Histogram(long[] upperBounds)
Create a new Histogram with a provided list of interval bounds.
|
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.
|
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.
|
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.
|
java.lang.String |
toString() |
private void |
trackRange(long value)
Track minimum and maximum observations
|
private void |
validateBounds(long[] upperBounds)
Validates the input bounds; used by constructor only.
|
private final long[] upperBounds
private final long[] counts
private long minValue
private long maxValue
public Histogram(long[] upperBounds)
upperBounds
- of the intervals. Bounds must be provided in order least to greatest, and
lowest bound must be greater than or equal to 1.java.lang.IllegalArgumentException
- if any of the upper bounds are less than or equal to zerojava.lang.IllegalArgumentException
- if the bounds are not in order, least to greatestprivate void validateBounds(long[] upperBounds)
public int getSize()
public long getUpperBoundAt(int index)
index
- of the upper bound.public long getCountAt(int index)
index
- of the observations counter.public boolean addObservation(long value)
value
- for the observation to be added.private void trackRange(long value)
public void addObservations(Histogram histogram)
Add observations from another Histogram into this one.
Histograms must have the same intervals.
histogram
- from which to add the observation counts.java.lang.IllegalArgumentException
- if interval count or values do not match exactlypublic void clear()
public long getCount()
public long getMin()
public long getMax()
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.
public long getTwoNinesUpperBound()
public long getFourNinesUpperBound()
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
factor
- representing the size of the population.java.lang.IllegalArgumentException
- if factor < 0.0 or factor > 1.0public java.lang.String toString()
toString
in class java.lang.Object