com.netflix.stats.distribution
Class Histogram

java.lang.Object
  com.netflix.stats.distribution.Distribution
      com.netflix.stats.distribution.Histogram

All Implemented Interfaces:

DataCollector, DistributionMBean, HistogramMBean

public class Histogram
extends Distribution
implements HistogramMBean

This extends Distribution by tracking counts of values per "bucket" and the ability to find the (approximate) median value.

Note that this implements HistogramMBean and so can be registered as an MBean and accessed via JMX if desired.

Constructor Summary

Histogram(double[] bucketLimits)
Creates a new initially empty Histogram.

Histogram(double min, double max, double step)
Creates a new initially empty Histogram with uniformally sized buckets.

Method Summary

void	clear() Clears out the distribution, resetting it to its initial state.
long	getBucketCount(int i) Gets the number of values recorded in a bucket.
long[]	getBucketCounts() Gets the number of values recorded in each bucket.
double	getBucketMaximum(int i) Gets the maximum for values recorded in a bucket.
double[]	getBucketMaximums() Gets the maximum bound for the histogram buckets.
double	getBucketMinimum(int i) Gets the minimum for values recorded in a bucket.
double[]	getBucketMinimums() Gets the minimum bound for the histogram buckets.
double	getMedian() Gets the approximate median value, that is the value where half of the observed values are less than the median and half are greater.
int	getNumBuckets() Gets the total number of buckets.
double	getPercentile(int percent) Gets the (approximate) percentile value, that is the value where some desired percent of the observed values are less than the percentile value and the remainder are greater.
long	getPercentileRank(double value) Gets the (approximate) percentage of observed values that are less than a given value.
void	noteValue(double val) Adds a value to the collected data.

Methods inherited from class com.netflix.stats.distribution.Distribution

add, getMaximum, getMean, getMinimum, getNumValues, getStdDev, getVariance, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.netflix.stats.distribution.DistributionMBean

getMaximum, getMean, getMinimum, getNumValues, getStdDev, getVariance

Constructor Detail

Histogram

public Histogram(double[] bucketLimits)

Creates a new initially empty Histogram.

Parameters:

bucketLimits - an array of max values for each bucket; the values must be sorted in increasing order. The first bucket records values in the range (-infinity .. bucketLimits[0]), the last bucket records values in the range (bucketLimits[bucketLimits.length-1] .. +infinity)

Histogram

public Histogram(double min,
                 double max,
                 double step)

Creates a new initially empty Histogram with uniformally sized buckets.

Parameters:

min - the upper limit for the first bucket

max - the upper limit for the final bucket (excluding the catch-all bucket)

step - the size of the range of each bucket

Method Detail

noteValue

public void noteValue(double val)

Adds a value to the collected data. This must run very quickly, and so can safely be called in time-critical code.

Specified by:

noteValue in interface DataCollector

Overrides:

noteValue in class Distribution

clear

public void clear()

Clears out the distribution, resetting it to its initial state.

Specified by:

clear in interface DistributionMBean

Overrides:

clear in class Distribution

getNumBuckets

public int getNumBuckets()

Gets the total number of buckets. Note that this includes any buckets added to handle out-of-range values.

Specified by:

getNumBuckets in interface HistogramMBean

getBucketCount

public long getBucketCount(int i)

Gets the number of values recorded in a bucket.

getBucketMinimum

public double getBucketMinimum(int i)

Gets the minimum for values recorded in a bucket. This is an inclusive minimum; values equal to the bucket limit are counted in this bucket.

getBucketMaximum

public double getBucketMaximum(int i)

Gets the maximum for values recorded in a bucket. This is an exclusive maximum; values equal to the bucket limit are counted in the subsequent bucket.

getBucketCounts

public long[] getBucketCounts()

Gets the number of values recorded in each bucket.

Specified by:

getBucketCounts in interface HistogramMBean

getBucketMinimums

public double[] getBucketMinimums()

Gets the minimum bound for the histogram buckets. This is an inclusive minimum; values equal to the bucket limit are counted in this bucket.

Specified by:

getBucketMinimums in interface HistogramMBean

getBucketMaximums

public double[] getBucketMaximums()

Gets the maximum bound for the histogram buckets. This is an exclusive maximum; values equal to the bucket limit are counted in the subsequent bucket.

Specified by:

getBucketMaximums in interface HistogramMBean

getMedian

public double getMedian()

Gets the approximate median value, that is the value where half of the observed values are less than the median and half are greater.

Specified by:

getMedian in interface HistogramMBean

getPercentile

public double getPercentile(int percent)

Gets the (approximate) percentile value, that is the value where some desired percent of the observed values are less than the percentile value and the remainder are greater.

Specified by:

getPercentile in interface HistogramMBean

getPercentileRank

public long getPercentileRank(double value)

Gets the (approximate) percentage of observed values that are less than a given value.

Specified by:

getPercentileRank in interface HistogramMBean