org.javasimon.callback.quantiles

Class Buckets

java.lang.Object

org.javasimon.callback.quantiles.Buckets

All Implemented Interfaces:

LogMessageSource<Split>

Direct Known Subclasses:

ExponentialBuckets, LinearBuckets

public abstract class Buckets
extends Object
implements LogMessageSource<Split>

List of buckets and quantiles computer. Samples are not kept in buckets only the counter indicates their presence.
Some details impact quantiles computation precision:

• Not enough samples: The more samples you have, the more precise interpolation are
• Not enough buckets: the more buckets are used, the more regular the distribution is and the more memory you'll need as well!
• All samples in one bucket: samples should be evenly distributed on buckets. If all samples go into the same bucket, you should consider changing the min/max/number settings

Since:

3.2

Author:

Gerald Quintana

Field Summary

Fields

Modifier and Type	Field and Description
protected int	bucketNb Number of real buckets (=buckets.length-2).
protected Bucket[]	buckets Array of buckets, sorted by ranges.
protected long	max Upper bound of all real buckets.
protected long	min Lower bound of all real buckets.

Constructor Summary

Constructors

Constructor and Description
Buckets(long min, long max, int bucketNb) Constructor, initializes buckets.

Method Summary

Methods

Modifier and Type	Method and Description
void	addValue(long value) Searches the appropriate bucket and add the value in it.
void	addValues(Collection<Long> values) For each value, search the appropriate bucket and add the value in it.
void	clear() Clears all buckets.
protected double	estimateQuantile(Bucket bucket, double expectedCount, double lastCount) Interpolate quantile located in given Bucket using linear regression.
protected Bucket	getBucketForValue(long value) Get the bucket containing the given value.
int	getBucketNb()
List<Bucket>	getBuckets() Returns the bucket list.
String	getLogMessage(Split lastSplit) Transforms buckets and quantiles into a loggable message.
LogTemplate<Split>	getLogTemplate()
long	getMax()
double	getMedian() Computes median.
long	getMin()
double	getQuantile(double ratio) Computes quantile.
Double[]	getQuantiles(double... ratios) Computes many quantiles.
Double[]	getQuartiles() Computes first (=0.25), second (=median=0.5) and third (=0.75) quartiles.
void	log(Split lastSplit) Logs eventually buckets config and quantiles.
BucketsSample	sample() Sample buckets and quantiles state.
void	setLogTemplate(LogTemplate<Split> logTemplate)
String	toString() String containing: min/max/number configuration and 50%, 75% and 90% quantiles if available.

Methods inherited from class java.lang.Object

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

Field Detail

buckets

protected final Bucket[] buckets

Array of buckets, sorted by ranges. The first and last buckets are special: The first bucket is range -infinity to min, The last bucket is range max to +infinity. Other buckets are regular ones with constant width

bucketNb

protected final int bucketNb

Number of real buckets (=buckets.length-2).

min

protected final long min

Lower bound of all real buckets.

max

protected final long max

Upper bound of all real buckets.

Constructor Detail

Buckets

public Buckets(long min,
       long max,
       int bucketNb)

Constructor, initializes buckets.

Parameters:

min - Min of all values

max - Max of all values

bucketNb - Number of buckets

Method Detail

estimateQuantile

protected double estimateQuantile(Bucket bucket,
                      double expectedCount,
                      double lastCount)

Interpolate quantile located in given Bucket using linear regression.

• Quantile is between Bucket.min and Bucket.max
• Expected count is between last count and last count+Bucket.count

Parameters:

bucket - Current bucket containing the quantile

expectedCount - Searched value

lastCount - Value of the bucket lower bound

Returns:

Compute quantile

getBucketForValue

protected Bucket getBucketForValue(long value)

Get the bucket containing the given value. Bucket should be sorted, the bucket whose min/max bounds are around the value is returned.

Parameters:

value - Value

Returns:

Bucket containing given value

addValue

public void addValue(long value)

Searches the appropriate bucket and add the value in it.

addValues

public void addValues(Collection<Long> values)

For each value, search the appropriate bucket and add the value in it.

getQuantile

public double getQuantile(double ratio)

Computes quantile.

Parameters:

ratio - Nth quantile, 0.5 is median. Expects values between 0 and 1.

Returns:

quantile

getMedian

public double getMedian()

Computes median.

Returns:

Median

getQuartiles

public Double[] getQuartiles()

Computes first (=0.25), second (=median=0.5) and third (=0.75) quartiles.

getQuantiles

public Double[] getQuantiles(double... ratios)

Computes many quantiles.

Parameters:

ratios - Nth quantiles, 0.5 is median. Expects values between 0 and 1.

Returns:

quantiles or null, if computation failed

getLogTemplate

public LogTemplate<Split> getLogTemplate()

setLogTemplate

public void setLogTemplate(LogTemplate<Split> logTemplate)

sample

public BucketsSample sample()

Sample buckets and quantiles state.

toString

public String toString()

String containing: min/max/number configuration and 50%, 75% and 90% quantiles if available. Warning this method can be expensive as it is performing computation.

Overrides:

toString in class Object

clear

public void clear()

Clears all buckets.

getBuckets

public List<Bucket> getBuckets()

Returns the bucket list.

Returns:

list of buckets

getLogMessage

public String getLogMessage(Split lastSplit)

Transforms buckets and quantiles into a loggable message.

Specified by:

getLogMessage in interface LogMessageSource<Split>

Parameters:

lastSplit - Context

Returns:

Message

log

public void log(Split lastSplit)

Logs eventually buckets config and quantiles.

getBucketNb

public int getBucketNb()

getMin

public long getMin()

getMax

public long getMax()