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

protected int	bucketNb Number of real buckets (=buckets.length-2).
protected Bucket[]	buckets Array of buckets, sorted by ranges.
private LogTemplate<Split>	logTemplate Log template used to log quantiles.
protected long	max Upper bound of all real buckets.
protected long	min Lower bound of all real buckets.

Constructor Summary

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

Method Summary

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.
private double	computeQuantile(double ration, int totalCount) Computes given quantile.
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.
private int	checkAndGetTotalCount() Computes expected count and check used buckets number.
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.
private String	toString(boolean bars)

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.

logTemplate

private LogTemplate<Split> logTemplate

Log template used to log quantiles.

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

checkAndGetTotalCount

private int checkAndGetTotalCount()
                           throws IllegalStateException

Computes expected count and check used buckets number.

Throws:

IllegalStateException

computeQuantile

private double computeQuantile(double ration,
                               int totalCount)
                        throws IllegalStateException,
                               IllegalArgumentException

Computes given quantile.

Parameters:

ration - Nth quantile: 0.5 is median

totalCount - Total count over all buckets

Returns:

Quantile

Throws:

IllegalStateException - Buckets are poorly configured and quantile can not be computed

IllegalArgumentException

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

toString

private String toString(boolean bars)

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()