net.openhft.chronicle.core.util

Class Histogram

java.lang.Object

net.openhft.chronicle.core.util.Histogram

All Implemented Interfaces:

NanoSampler

Direct Known Subclasses:

RecordingHistogram

public class Histogram
extends Object
implements NanoSampler

A Histogram class represents a histogram of samples. The histogram is defined by a set of buckets, each of which counts the number of samples that fall into its range of values. The range of values for each bucket is determined by a combination of the number of powers of 2 and the number of fraction bits.

Note that this class is marked as SingleThreaded, which means it is not safe for use by multiple threads simultaneously.

This class implements the NanoSampler interface, which provides a method for sampling values in nanoseconds.

Constructor Summary

Constructors

Constructor and Description
Histogram() Creates a new Histogram with default parameters.
Histogram(int powersOf2, int fractionBits) Creates a new Histogram with the specified number of powers of 2 and fraction bits.
Histogram(int powersOf2, int fractionBits, double minValue) Creates a new Histogram with the specified number of powers of 2, fraction bits, and minimum value.

Method Summary

Modifier and Type	Method and Description
void	add(@NotNull Histogram h) Adds the contents of another histogram to this one.
boolean	equals(Object obj)
long	floor()
int	fractionBits() Gets the number of fraction bits used by the histogram.
double[]	getPercentiles() Calculates an array of percentiles based on the total count.
double[]	getPercentiles(double[] percentileFor) Calculates an array of percentiles for the given set of values.
int	hashCode()
void	init(int powersOf2, int fractionBits, long overRange, long totalCount, long floor) Re initialise this histogram from deserialized data
double	max() Gets the maximum value in the histogram.
double	min() Gets the minimum value in the histogram.
long	overRange() Gets the number of values that are over the range of the histogram's buckets.
double	percentageLessThan(double time) Calculates the percentage of values that are less than the given time.
double	percentile(double fraction)
static double[]	percentilesFor(long count) Calculates the percentiles for a given count.
int	powersOf2() Gets the number of powers of 2 used by the histogram.
void	reset()
int	sample(double time) Samples a value and updates the histogram accordingly.
int[]	sampleCount() Gets the array of sample counts per bucket.
void	sampleNanos(long durationNs) Records a sample with the provided duration in nanoseconds.
static @NotNull Histogram	timeMicros()
@NotNull String	toLongMicrosFormat() Returns a string representation of the histogram in a long format suitable for display in microseconds.
@NotNull String	toLongMicrosFormat(@NotNull DoubleFunction<Double> toMicros) Returns a string representation of the histogram in a long format suitable for display in microseconds.
@NotNull String	toMicrosFormat() Returns a string representation of the histogram in a format suitable for display in microseconds.
@NotNull String	toMicrosFormat(@NotNull DoubleFunction<Double> toMicros) Returns a string representation of the histogram in a format suitable for display in microseconds.
@NotNull String	toString()
long	totalCount()
double	typical() Gets the median value in the histogram.
protected String	was()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Histogram

public Histogram()

Creates a new Histogram with default parameters. The default number of powers of 2 is 42 and the default number of fraction bits is 8.

Histogram

public Histogram(int powersOf2,
                 int fractionBits)

Creates a new Histogram with the specified number of powers of 2 and fraction bits.

Parameters:

powersOf2 - the number of powers of 2 to use in the histogram

fractionBits - the number of fraction bits to use in the histogram

Histogram

public Histogram(int powersOf2,
                 int fractionBits,
                 double minValue)

Creates a new Histogram with the specified number of powers of 2, fraction bits, and minimum value.

Parameters:

powersOf2 - the number of powers of 2 to use in the histogram

fractionBits - the number of fraction bits to use in the histogram

minValue - the minimum value for the histogram

Method Detail

timeMicros

@NotNull
public static @NotNull Histogram timeMicros()

Returns:

Histogram for use with System.nanoTime() up to 4 second delay.

percentilesFor

public static double[] percentilesFor(long count)

Calculates the percentiles for a given count.

Parameters:

count - the count of values

Returns:

an array of doubles representing the calculated percentiles

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

@NotNull
public @NotNull String toString()

Overrides:

toString in class Object

init

public void init(int powersOf2,
                 int fractionBits,
                 long overRange,
                 long totalCount,
                 long floor)

Re initialise this histogram from deserialized data

fractionBits

public int fractionBits()

Gets the number of fraction bits used by the histogram.

Returns:

the number of fraction bits

powersOf2

public int powersOf2()

Gets the number of powers of 2 used by the histogram.

Returns:

the number of powers of 2

overRange

public long overRange()

Gets the number of values that are over the range of the histogram's buckets.

Returns:

the over range count

sampleCount

public int[] sampleCount()

Gets the array of sample counts per bucket.

Returns:

the array of sample counts

add

public void add(@NotNull
                @NotNull Histogram h)

Adds the contents of another histogram to this one. The other histogram must have the same number of powers of 2 and fraction bits as this one.

Parameters:

h - the other histogram

Throws:

AssertionError - if the other histogram does not have the same number of powers of 2 and fraction bits

sample

public int sample(double time)

Samples a value and updates the histogram accordingly. The value is placed into a bucket based on its size, with the bucket ranges determined by the powers of 2 and fraction bits specified when the histogram was created.

Parameters:

time - the value to sample

Returns:

the bucket that the value was placed in

min

public double min()

Gets the minimum value in the histogram.

Returns:

the minimum value

typical

public double typical()

Gets the median value in the histogram.

Returns:

the median value

max

public double max()

Gets the maximum value in the histogram.

Returns:

the maximum value

percentile

public double percentile(double fraction)

percentageLessThan

public double percentageLessThan(double time)

Calculates the percentage of values that are less than the given time.

Parameters:

time - the time to compare the values against

Returns:

the percentage of values less than the given time

getPercentiles

public double[] getPercentiles()

Calculates an array of percentiles based on the total count.

Returns:

an array of percentiles

getPercentiles

public double[] getPercentiles(double[] percentileFor)

Calculates an array of percentiles for the given set of values.

Parameters:

percentileFor - an array of values for which to calculate percentiles

Returns:

an array of calculated percentiles

toMicrosFormat

@NotNull
public @NotNull String toMicrosFormat()

Returns a string representation of the histogram in a format suitable for display in microseconds. This is a convenience method that uses a default function to convert the values to microseconds.

Returns:

a string representation of the histogram

toMicrosFormat

@NotNull
public @NotNull String toMicrosFormat(@NotNull
                                               @NotNull DoubleFunction<Double> toMicros)

Returns a string representation of the histogram in a format suitable for display in microseconds. The given function is used to convert the values to microseconds.

Parameters:

toMicros - a function that converts a value to microseconds

Returns:

a string representation of the histogram

toLongMicrosFormat

@NotNull
public @NotNull String toLongMicrosFormat()

Returns a string representation of the histogram in a long format suitable for display in microseconds. This is a convenience method that uses a default function to convert the values to microseconds.

Returns:

a string representation of the histogram

toLongMicrosFormat

@NotNull
public @NotNull String toLongMicrosFormat(@NotNull
                                                   @NotNull DoubleFunction<Double> toMicros)

Returns a string representation of the histogram in a long format suitable for display in microseconds. The given function is used to convert the values to microseconds.

Parameters:

toMicros - a function that converts a value to microseconds

Returns:

a string representation of the histogram

was

protected String was()

totalCount

public long totalCount()

floor

public long floor()

reset

public void reset()

sampleNanos

public void sampleNanos(long durationNs)

Description copied from interface: NanoSampler

Records a sample with the provided duration in nanoseconds.

This method must be called from a single thread only. If called from multiple threads or if provided with a negative duration, the result is unspecified and no errors or exceptions should be thrown.

Specified by:

sampleNanos in interface NanoSampler

Parameters:

durationNs - The duration of the sample in nanoseconds. Must be non-negative.