Top Description Inners Fields Constructors Methods
org.HdrHistogram

public abstract Class AbstractHistogram

Additional top-level class in compilation unit: AbstractHistogramBase.

extends AbstractHistogramBase
implements ValueRecorder, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, org.HdrHistogram.ValueRecorder
Known Direct Subclasses
org.HdrHistogram.Histogram, org.HdrHistogram.ShortCountsHistogram, org.HdrHistogram.IntCountsHistogram
Imports
java.io.*, java.lang.reflect.Constructor, .InvocationTargetException, java.nio.ByteBuffer, java.util.Iterator, .Locale, java.util.concurrent.atomic.AtomicLong, .AtomicLongFieldUpdater, java.util.zip.DataFormatException, .Deflater, .Inflater

An abstract base class for integer values High Dynamic Range (HDR) Histograms

AbstractHistogram supports the recording and analyzing sampled data value counts across a configurable integer value range with configurable value precision within the range. Value precision is expressed as the number of significant digits in the value recording, and provides control over value quantization behavior across the value range and the subsequent value resolution at any given level.

For example, a Histogram could be configured to track the counts of observed integer values between 0 and 3,600,000,000 while maintaining a value precision of 3 significant digits across that range. Value quantization within the range will thus be no larger than 1/1,000th (or 0.1%) of any value. This example Histogram could be used to track and analyze the counts of observed response times ranging between 1 microsecond and 1 hour in magnitude, while maintaining a value resolution of 1 microsecond up to 1 millisecond, a resolution of 1 millisecond (or better) up to one second, and a resolution of 1 second (or better) up to 1,000 seconds. At it's maximum tracked value (1 hour), it would still maintain a resolution of 3.6 seconds (or better).

See package description for org.HdrHistogram for details.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public class
AbstractHistogram.AllValues

An java.lang.Iterable<HistogramIterationValue> through the histogram using a AllValuesIterator

public class
AbstractHistogram.LinearBucketValues

An java.lang.Iterable<HistogramIterationValue> through the histogram using a LinearIterator

public class
AbstractHistogram.LogarithmicBucketValues

An java.lang.Iterable<HistogramIterationValue> through the histogram using a LogarithmicIterator

public class
AbstractHistogram.Percentiles

An java.lang.Iterable<HistogramIterationValue> through the histogram using a PercentileIterator

public class
AbstractHistogram.RecordedValues

An java.lang.Iterable<HistogramIterationValue> through the histogram using a RecordedValuesIterator

Field Summary

Modifier and TypeField and Description
private static final int
compressedEncodingCookieBase

private static final Class<T>[]
constructorArgsTypes

private static final int
ENCODING_HEADER_SIZE

private static final int
encodingCookieBase

pack-priv int
leadingZeroCountBase

Number of leading zeros in the largest value that can fit in bucket 0.

pack-priv volatile long
maxValue

private static final AtomicLongFieldUpdater<AbstractHistogram>
maxValueUpdater

pack-priv volatile long
minNonZeroValue

private static final AtomicLongFieldUpdater<AbstractHistogram>
minNonZeroValueUpdater

private static final long
serialVersionUID

pack-priv int
subBucketHalfCount

pack-priv int
subBucketHalfCountMagnitude

pack-priv long
subBucketMask

Biggest value that can fit in bucket 0

pack-priv int
unitMagnitude

Largest k such that 2^k <= lowestDiscernibleValue

pack-priv long
unitMagnitudeMask

Lowest unitMagnitude bits are set

private static final int
V0_ENCODING_HEADER_SIZE

private static final int
V0CompressedEncodingCookieBase

private static final int
V0EncodingCookieBase

private static final int
V1CompressedEncodingCookieBase

private static final int
V1EncodingCookieBase

private static final int
V2CompressedEncodingCookieBase

private static final int
V2EncodingCookieBase

private static final int
V2maxWordSizeInBytes

Inherited from org.HdrHistogram.AbstractHistogramBase:
autoResizebucketCountconstructionIdentityCountcountsArrayLengthdoubleToIntegerValueConversionRatioendTimeStampMsechighestTrackableValueidentityintegerToDoubleValueConversionRatiointermediateUncompressedByteArrayintermediateUncompressedByteBufferlowestDiscernibleValuenumberOfSignificantValueDigitspercentileIteratorrecordedValuesIteratorstartTimeStampMsecsubBucketCounttagwordSizeInBytes

Constructor Summary

AccessConstructor and Description
protected
AbstractHistogram(final int
The number of significant decimal digits to which the histogram will maintain value resolution and separation. Must be a non-negative integer between 0 and 5.
numberOfSignificantValueDigits)

Construct an auto-resizing histogram with a lowest discernible value of 1 and an auto-adjusting highestTrackableValue.

protected
AbstractHistogram(final long
The lowest value that can be discerned (distinguished from 0) by the histogram. Must be a positive integer that is >= 1. May be internally rounded down to nearest power of 2.
lowestDiscernibleValue, final long
The highest value to be tracked by the histogram. Must be a positive integer that is >= (2 * lowestDiscernibleValue).
highestTrackableValue, final int
The number of significant decimal digits to which the histogram will maintain value resolution and separation. Must be a non-negative integer between 0 and 5.
numberOfSignificantValueDigits)

Construct a histogram given the Lowest and Highest values to be tracked and a number of significant decimal digits.

protected
AbstractHistogram(final AbstractHistogram
The source histogram to duplicate
source)

Construct a histogram with the same range settings as a given source histogram, duplicating the source's start/end timestamps (but NOT it's contents)

Method Summary

Modifier and TypeMethod and Description
pack-priv abstract int
_getEstimatedFootprintInBytes()

public void
add(final AbstractHistogram
The other histogram.
otherHistogram)

Add the contents of another histogram to this one.

pack-priv abstract void
addToCountAtIndex(int index, long value)

pack-priv abstract void
addToTotalCount(long value)

public void
addWhileCorrectingForCoordinatedOmission(final AbstractHistogram
The other histogram. highestTrackableValue and largestValueWithSingleUnitResolution must match.
otherHistogram, final long
If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
expectedIntervalBetweenValueSamples)

Add the contents of another histogram to this one, while correcting the incoming data for coordinated omission.

public AbstractHistogram.AllValues

Returns:

An java.lang.Iterable<HistogramIterationValue> through the histogram using a AllValuesIterator
allValues()

Provide a means of iterating through all histogram values using the finest granularity steps supported by the underlying representation.

pack-priv abstract void
clearCounts()

public abstract AbstractHistogram

Returns:

A distinct copy of this histogram.
copy()

Create a copy of this histogram, complete with data and everything.

public abstract AbstractHistogram

Returns:

a copy of this histogram, corrected for coordinated omission.
copyCorrectedForCoordinatedOmission(long
If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
expectedIntervalBetweenValueSamples)

Get a copy of this histogram, corrected for coordinated omission.

public void
copyInto(final AbstractHistogram
the histogram to copy into
targetHistogram)

Copy this histogram into the target histogram, overwriting it's contents.

public void
copyIntoCorrectedForCoordinatedOmission(final AbstractHistogram
the histogram to copy into
targetHistogram, final long
If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
expectedIntervalBetweenValueSamples)

Copy this histogram, corrected for coordinated omission, into the target histogram, overwriting it's contents.

pack-priv int
countsArrayIndex(final long value)

private int
countsArrayIndex(final int bucketIndex, final int subBucketIndex)

pack-priv static <T extends AbstractHistogram> T
decodeFromByteBuffer(final ByteBuffer buffer, final Class<T> histogramClass, final long minBarForHighestTrackableValue)

private static <T extends AbstractHistogram> T
decodeFromByteBuffer(final ByteBuffer buffer, final Class<T> histogramClass, final long minBarForHighestTrackableValue, final Inflater decompressor)

pack-priv static <T extends AbstractHistogram> T
decodeFromCompressedByteBuffer(final ByteBuffer buffer, final Class<T> histogramClass, final long minBarForHighestTrackableValue)

pack-priv final int
determineArrayLengthNeeded(long highestTrackableValue)

public synchronized int

Returns:

The number of bytes written to the buffer
encodeIntoByteBuffer(final ByteBuffer
The buffer to encode into
buffer)

Encode this histogram into a ByteBuffer

public synchronized int

Returns:

The number of bytes written to the buffer
encodeIntoCompressedByteBuffer(final ByteBuffer
The buffer to encode into
targetBuffer, final int
Compression level (for java.util.zip.Deflater).
compressionLevel)

Implements abstract org.HdrHistogram.EncodableHistogram.encodeIntoCompressedByteBuffer.

Encode this histogram in compressed form into a byte array
public int

Returns:

The number of bytes written to the array
encodeIntoCompressedByteBuffer(final ByteBuffer
The buffer to encode into
targetBuffer)

Encode this histogram in compressed form into a byte array

public boolean

Returns:

True if this histogram are equivalent with the other.
equals(final Object
the other histogram to compare to
other)

Overrides java.lang.Object.equals.

Determine if this histogram is equivalent to another.
pack-priv void
establishInternalTackingValues()

pack-priv void
establishInternalTackingValues(final int lengthToCover)

pack-priv final void
establishSize(long newHighestTrackableValue)

The buckets (each of which has subBucketCount sub-buckets, here assumed to be 2048 as an example) overlap: 

The 0'th bucket covers from 0...2047 in multiples of 1, using all 2048 sub-buckets
The 1'th bucket covers from 2048..4097 in multiples of 2, using only the top 1024 sub-buckets
The 2'th bucket covers from 4096..8191 in multiple of 4, using only the top 1024 sub-buckets
...
pack-priv synchronized void
fillBufferFromCountsArray(ByteBuffer buffer)

private int
fillCountsArrayFromSourceBuffer(ByteBuffer sourceBuffer, int lengthInBytes, int wordSizeInBytes)

pack-priv int

Returns:

the lowest (and therefore highest precision) bucket index that can represent the value
getBucketIndex(final long value)

pack-priv int
getBucketsNeededToCoverValue(final long value)

private int
getCompressedEncodingCookie()

private static int
getCookieBase(final int cookie)

pack-priv abstract long
getCountAtIndex(int index)

pack-priv abstract long
getCountAtNormalizedIndex(int index)

public long

Returns:

The total count of values recorded in the histogram within the value range that is >= lowestEquivalentValue(value) and <= highestEquivalentValue(value)
getCountAtValue(final long
The value for which to provide the recorded count
value)

Get the count of recorded values at a specific value (to within the histogram resolution at the value level).

public long

Returns:

the total count of values recorded in the histogram within the value range that is >= lowestEquivalentValue(lowValue) and <= highestEquivalentValue(highValue)
getCountBetweenValues(final long
The lower value bound on the range for which to provide the recorded count. Will be rounded down with lowestEquivalentValue.
lowValue, final long
The higher value bound on the range for which to provide the recorded count. Will be rounded up with highestEquivalentValue.
highValue)

Get the count of recorded values within a range of value levels (inclusive to within the histogram's resolution).

private int
getEncodingCookie()

public long

Returns:

the end time stamp [optionally] stored with this histogram
getEndTimeStamp()

Implements abstract org.HdrHistogram.EncodableHistogram.getEndTimeStamp.

get the end time stamp [optionally] stored with this histogram
public int

Returns:

a (conservatively high) estimate of the Histogram's total footprint in bytes
getEstimatedFootprintInBytes()

Provide a (conservatively high) estimate of the Histogram's total footprint in bytes

public long

Returns:

highestTrackableValue
getHighestTrackableValue()

get the configured highestTrackableValue

pack-priv int
getLengthForNumberOfBuckets(final int numberOfBuckets)

If we have N such that subBucketCount * 2^N > max value, we need storage for N+1 buckets, each with enough slots to hold the top half of the subBucketCount (the lower half is covered by previous buckets), and the +1 being used for the lower half of the 0'th bucket.

public long

Returns:

lowestDiscernibleValue
getLowestDiscernibleValue()

get the configured lowestDiscernibleValue

public long

Returns:

the Max value recorded in the histogram
getMaxValue()

Get the highest recorded value level in the histogram.

public double

Returns:

the Max value recorded in the histogram
getMaxValueAsDouble()

Implements abstract org.HdrHistogram.EncodableHistogram.getMaxValueAsDouble.

Get the highest recorded value level in the histogram as a double
public double

Returns:

the mean value (in value units) of the histogram data
getMean()

Get the computed mean value of all recorded values in the histogram

public long

Returns:

the lowest recorded non-zero value level in the histogram
getMinNonZeroValue()

Get the lowest recorded non-zero value level in the histogram.

public long

Returns:

the Min value recorded in the histogram
getMinValue()

Get the lowest recorded value level in the histogram.

public int

Returns:

the capacity needed to encode this histogram into a ByteBuffer
getNeededByteBufferCapacity()

Implements abstract org.HdrHistogram.EncodableHistogram.getNeededByteBufferCapacity.

Get the capacity needed to encode this histogram into a ByteBuffer
pack-priv int
getNeededByteBufferCapacity(final int relevantLength)

pack-priv int
getNeededPayloadByteBufferCapacity(final int relevantLength)

pack-priv int
getNeededV0PayloadByteBufferCapacity(final int relevantLength)

pack-priv abstract int
getNormalizingIndexOffset()

public int

Returns:

numberOfSignificantValueDigits
getNumberOfSignificantValueDigits()

get the configured numberOfSignificantValueDigits

public double

Returns:

The percentile of values recorded in the histogram that are smaller than or equivalent to the given value.
getPercentileAtOrBelowValue(final long
The value for which to return the associated percentile
value)

Get the percentile at a given value.

public long

Returns:

the start time stamp [optionally] stored with this histogram
getStartTimeStamp()

Implements abstract org.HdrHistogram.EncodableHistogram.getStartTimeStamp.

get the start time stamp [optionally] stored with this histogram
public double

Returns:

the standard deviation (in value units) of the histogram data
getStdDeviation()

Get the computed standard deviation of all recorded values in the histogram

pack-priv int
getSubBucketIndex(final long value, final int bucketIndex)

public String

Returns:

tag string [optionally] associated with this histogram
getTag()

Implements abstract org.HdrHistogram.EncodableHistogram.getTag.

get the tag string [optionally] associated with this histogram
public abstract long

Returns:

the total count of all recorded values in the histogram
getTotalCount()

Get the total count of all recorded values in the histogram

public long

Returns:

The largest value that (100% - percentile) [+/- 1 ulp] of the overall recorded value entries in the histogram are either larger than or equivalent to. Returns 0 if no recorded values exist.
getValueAtPercentile(final double
The percentile for which to return the associated value
percentile)

Get the value at a given percentile.

private static int
getWordSizeInBytesFromCookie(final int cookie)

private void
handleRecordException(final long count, final long value, Exception ex)

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for the object.
public long

Returns:

The highest value that is equivalent to the given value within the histogram's resolution.
highestEquivalentValue(final long
The given value
value)

Get the highest value that is equivalent to the given value within the histogram's resolution.

pack-priv abstract void
incrementCountAtIndex(int index)

pack-priv abstract void
incrementTotalCount()

private void
init(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits, final double integerToDoubleValueConversionRatio, final int normalizingIndexOffset)

public boolean

Returns:

autoResize setting
isAutoResize()

Indicate whether or not the histogram is set to auto-resize and auto-adjust it's highestTrackableValue

public AbstractHistogram.LinearBucketValues

Returns:

An java.lang.Iterable<HistogramIterationValue> through the histogram using a LinearIterator
linearBucketValues(final long
The size (in value units) of the linear buckets to use
valueUnitsPerBucket)

Provide a means of iterating through histogram values using linear steps.

public AbstractHistogram.LogarithmicBucketValues

Returns:

An java.lang.Iterable<HistogramIterationValue> through the histogram using a LogarithmicIterator
logarithmicBucketValues(final long
The size (in value units) of the first bucket in the iteration
valueUnitsInFirstBucket, final double
The multiplier by which bucket sizes will grow in each iteration step
logBase)

Provide a means of iterating through histogram values at logarithmically increasing levels.

public long

Returns:

The lowest value that is equivalent to the given value within the histogram's resolution.
lowestEquivalentValue(final long
The given value
value)

Get the lowest value that is equivalent to the given value within the histogram's resolution.

public long

Returns:

The value lies in the middle (rounded up) of the range of values equivalent the given value.
medianEquivalentValue(final long
The given value
value)

Get a value that lies in the middle (rounded up) of the range of values equivalent the given value.

public long

Returns:

The next value that is not equivalent to the given value within the histogram's resolution.
nextNonEquivalentValue(final long
The given value
value)

Get the next value that is not equivalent to the given value within the histogram's resolution.

pack-priv void
nonConcurrentNormalizingIndexShift(int shiftAmount, boolean lowestHalfBucketPopulated)

pack-priv int

Returns:

The value `index - normalizingIndexOffset` modulo arrayLength (always nonnegative)
normalizeIndex(int index, int normalizingIndexOffset, int arrayLength)

pack-priv static int
numberOfSubbuckets(final int numberOfSignificantValueDigits)

private int
oneAtATimeHashStep(int h, final int v)

public void
outputPercentileDistribution(final PrintStream
Stream into which the distribution will be output

printStream, final Double
The scaling factor by which to divide histogram recorded values units in output
outputValueUnitScalingRatio)

Produce textual representation of the value distribution of histogram data by percentile.

public void
outputPercentileDistribution(final PrintStream
Stream into which the distribution will be output

printStream, final int
The number of reporting points per exponentially decreasing half-distance

percentileTicksPerHalfDistance, final Double
The scaling factor by which to divide histogram recorded values units in output
outputValueUnitScalingRatio)

Produce textual representation of the value distribution of histogram data by percentile.

public void
outputPercentileDistribution(final PrintStream
Stream into which the distribution will be output

printStream, final int
The number of reporting points per exponentially decreasing half-distance

percentileTicksPerHalfDistance, final Double
The scaling factor by which to divide histogram recorded values units in output
outputValueUnitScalingRatio, final boolean
Output in CSV format if true. Otherwise use plain text form.
useCsvFormat)

Produce textual representation of the value distribution of histogram data by percentile.

public AbstractHistogram.Percentiles

Returns:

An java.lang.Iterable<HistogramIterationValue> through the histogram using a PercentileIterator
percentiles(final int
The number of iteration steps per half-distance to 100%.
percentileTicksPerHalfDistance)

Provide a means of iterating through histogram values according to percentile levels.

private void
readObject(final ObjectInputStream o)

pack-priv void
recordConvertedDoubleValue(final double value)

public void
recordConvertedDoubleValueWithCount(final double value, final long count)

private void
recordCountAtValue(final long count, final long value)

public AbstractHistogram.RecordedValues

Returns:

An java.lang.Iterable<HistogramIterationValue> through the histogram using a RecordedValuesIterator
recordedValues()

Provide a means of iterating through all recorded histogram values using the finest granularity steps supported by the underlying representation.

private String
recordedValuesToString()

private void
recordSingleValue(final long value)

private void
recordSingleValueWithExpectedInterval(final long value, final long expectedIntervalBetweenValueSamples)

public void
recordValue(final long
The value to be recorded
value)

Implements org.HdrHistogram.ValueRecorder.recordValue.

Record a value in the histogram
public void
recordValue(final long
The value to record
value, final long
If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
expectedIntervalBetweenValueSamples)

Deprecated Record a value in the histogram. This deprecated method has identical behavior to recordValueWithExpectedInterval(). It was renamed to avoid ambiguity.
public void
recordValueWithCount(final long
The value to be recorded
value, final long
The number of occurrences of this value to record
count)

Implements org.HdrHistogram.ValueRecorder.recordValueWithCount.

Record a value in the histogram (adding to the value's current count)
private void
recordValueWithCountAndExpectedInterval(final long value, final long count, final long expectedIntervalBetweenValueSamples)

public void
recordValueWithExpectedInterval(final long
The value to record
value, final long
If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
expectedIntervalBetweenValueSamples)

Implements org.HdrHistogram.ValueRecorder.recordValueWithExpectedInterval.

Record a value in the histogram.
public void
reset()

Implements org.HdrHistogram.ValueRecorder.reset.

Reset the contents and stats of this histogram
private void
resetMaxValue(final long maxValue)

private void
resetMinNonZeroValue(final long minNonZeroValue)

pack-priv abstract void
resize(long newHighestTrackableValue)

public void
setAutoResize(boolean
autoResize setting
autoResize)

Control whether or not the histogram can auto-resize and auto-adjust it's highestTrackableValue

pack-priv abstract void
setCountAtIndex(int index, long value)

pack-priv abstract void
setCountAtNormalizedIndex(int index, long value)

public void
setEndTimeStamp(final long
the value to set the time stamp to, [by convention] in msec since the epoch.
timeStampMsec)

Implements abstract org.HdrHistogram.EncodableHistogram.setEndTimeStamp.

Set the end time stamp value associated with this histogram to a given value.
pack-priv abstract void
setNormalizingIndexOffset(int normalizingIndexOffset)

public void
setStartTimeStamp(final long
the value to set the time stamp to, [by convention] in msec since the epoch.
timeStampMsec)

Implements abstract org.HdrHistogram.EncodableHistogram.setStartTimeStamp.

Set the start time stamp value associated with this histogram to a given value.
public void
setTag(String
the tag string to assciate with this histogram
tag)

Implements abstract org.HdrHistogram.EncodableHistogram.setTag.

Set the tag string associated with this histogram
pack-priv abstract void
setTotalCount(long totalCount)

private void
shiftLowestHalfBucketContentsLeft(int shiftAmount, int preShiftZeroIndex)

pack-priv abstract void
shiftNormalizingIndexByOffset(int offsetToAdd, boolean lowestHalfBucketPopulated, double newIntegerToDoubleValueConversionRatio)

public void
shiftValuesLeft(final int
The number of binary orders of magnitude to shift by
numberOfBinaryOrdersOfMagnitude)

Shift recorded values to the left (the equivalent of a << shift operation on all recorded values).

pack-priv void
shiftValuesLeft(final int numberOfBinaryOrdersOfMagnitude, final double newIntegerToDoubleValueConversionRatio)

public void
shiftValuesRight(final int
The number of binary orders of magnitude to shift by
numberOfBinaryOrdersOfMagnitude)

Shift recorded values to the right (the equivalent of a >> shift operation on all recorded values).

pack-priv void
shiftValuesRight(final int numberOfBinaryOrdersOfMagnitude, final double newIntegerToDoubleValueConversionRatio)

public long

Returns:

The size of the range of values equivalent to the given value.
sizeOfEquivalentValueRange(final long
The given value
value)

Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution.

public void
subtract(final AbstractHistogram
The other histogram.
otherHistogram)

Subtract the contents of another histogram from this one.

public boolean

Returns:

autoResize setting
supportsAutoResize()

Indicate whether or not the histogram is capable of supporting auto-resize functionality.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
private void
updatedMaxValue(final long
new maxValue to set
value)

Set internally tracked maxValue to new value if new value is greater than current one.

pack-priv void
updateMinAndMax(final long value)

private void
updateMinNonZeroValue(final long
new minNonZeroValue to set
value)

Set internally tracked minNonZeroValue to new value if new value is smaller than current one.

private long
valueFromIndex(final int bucketIndex, final int subBucketIndex)

pack-priv final long
valueFromIndex(final int index)

public boolean

Returns:

True if values are equivalent with the histogram's resolution.
valuesAreEquivalent(final long
first value to compare
value1, final long
second value to compare
value2)

Determine if two values are equivalent with the histogram's resolution.

private void
writeObject(final ObjectOutputStream o)

Inherited from org.HdrHistogram.AbstractHistogramBase:
getDoubleToIntegerValueConversionRatiogetIntegerToDoubleValueConversionRationonConcurrentSetIntegerToDoubleValueConversionRatiosetIntegerToDoubleValueConversionRatio