net.opentsdb.stats

Class Histogram

java.lang.Object

net.opentsdb.stats.Histogram

public final class Histogram
extends Object

A histogram to keep track of the approximation of a distribution of values.

This is not a general purpose implementation of histogram. It's specifically designed for "small" values (close to 0) as the primary use case is latency histograms.

All values must be positive (>= 0).

The histogram is linear (fixed size buckets) up to a given cutoff point. Beyond that point, the histogram becomes exponential (each bucket is twice as large as the previous one). This gives good granularity for lower values while still allowing a rough classification for the "long tail" of larger values.

Note that this implementation doesn't allow you to directly control the number of buckets in the histogram. The number will depend on the arguments given to the constructor.

This class is not synchronized.

Constructor Summary

Constructors

Constructor and Description
Histogram(int max, short interval, int cutoff) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	add(int value) Adds a value to the histogram.
int	buckets() Returns the number of buckets in this histogram.
int	percentile(int p) Returns the value of the pth percentile in this histogram.
void	printAscii(StringBuilder out) Prints this histogram in a human readable ASCII format.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Histogram

public Histogram(int max,
         short interval,
         int cutoff)

Constructor.

Parameters:

max - The maximum value of the histogram. Any value greater than this will be considered to be "infinity".

interval - The interval (size) of each linear bucket.

cutoff - The value beyond which to switch to exponential buckets. The histogram may actually use this value or a value up to interval greater.

Throws:

IllegalArgumentException - if any of following conditions are not met:

   0 < interval <= max
   0 <= cutoff <= max
 

Method Detail

buckets

public int buckets()

Returns the number of buckets in this histogram.

add

public void add(int value)

Adds a value to the histogram.

This method works in O(1).

Parameters:

value - The value to add.

Throws:

IllegalArgumentException - if the value given is negative.

percentile

public int percentile(int p)

Returns the value of the pth percentile in this histogram.

This method works in O(N) where N is the number of buckets.

Parameters:

p - A strictly positive integer in the range [1; 100]

Throws:

IllegalArgumentException - if p is not valid.

printAscii

public void printAscii(StringBuilder out)

Prints this histogram in a human readable ASCII format.

This is equivalent to calling printAsciiBucket(java.lang.StringBuilder, int) on every bucket.

Parameters:

out - The buffer to which to write the output.

toString

public String toString()

Overrides:

toString in class Object