Top Description Fields Constructors Methods
org.HdrHistogram

public Class Histogram

extends AbstractHistogram
Class Inheritance
Known Direct Subclasses
org.HdrHistogram.PackedHistogram, org.HdrHistogram.SingleWriterRecorder.InternalHistogram, org.HdrHistogram.SynchronizedHistogram, org.HdrHistogram.AtomicHistogram, org.HdrHistogram.ConcurrentHistogram
Imports
java.io.IOException, .ObjectInputStream, java.nio.ByteBuffer, java.util.Arrays, java.util.zip.DataFormatException

A High Dynamic Range (HDR) Histogram

Histogram 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 its maximum tracked value (1 hour), it would still maintain a resolution of 3.6 seconds (or better).

Histogram tracks value counts in long fields. Smaller field types are available in the IntCountsHistogram and ShortCountsHistogram implementations of org.HdrHistogram.AbstractHistogram.

Auto-resizing: When constructed with no specified value range range (or when auto-resize is turned on with Histogram#setAutoResize) a Histogram will auto-resize its dynamic range to include recorded values as they are encountered. Note that recording calls that cause auto-resizing may take longer to execute, as resizing incurs allocation and copying of internal data structures.

See package description for org.HdrHistogram for details.

Field Summary

Modifier and TypeField and Description
pack-priv long[]
counts

pack-priv int
normalizingIndexOffset

pack-priv long
totalCount

Inherited from org.HdrHistogram.AbstractHistogram:
leadingZeroCountBasemaxValueminNonZeroValuesubBucketHalfCountsubBucketHalfCountMagnitudesubBucketMaskunitMagnitudeunitMagnitudeMask

Constructor Summary

AccessConstructor and Description
public
Histogram(final int
Specifies the precision to use. This is 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.

public
Histogram(final long
The highest value to be tracked by the histogram. Must be a positive integer that is >= 2.
highestTrackableValue, final int
Specifies the precision to use. This is 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 Highest value to be tracked and a number of significant decimal digits.

public
Histogram(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
Specifies the precision to use. This is 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.

public
Histogram(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 its contents)

pack-priv
Histogram(final AbstractHistogram source, boolean allocateCountsArray)

pack-priv
Histogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits, boolean allocateCountsArray)

Method Summary

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

Implements abstract org.HdrHistogram.AbstractHistogram._getEstimatedFootprintInBytes.

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

Implements abstract org.HdrHistogram.AbstractHistogram.addToCountAtIndex.

pack-priv void
addToTotalCount(final long value)

Implements abstract org.HdrHistogram.AbstractHistogram.addToTotalCount.

pack-priv void
clearCounts()

Implements abstract org.HdrHistogram.AbstractHistogram.clearCounts.

public Histogram
copy()

Implements abstract org.HdrHistogram.AbstractHistogram.copy.

Create a copy of this histogram, complete with data and everything.
public Histogram
copyCorrectedForCoordinatedOmission(final long
If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
expectedIntervalBetweenValueSamples)

Implements abstract org.HdrHistogram.AbstractHistogram.copyCorrectedForCoordinatedOmission.

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

Returns:

The newly constructed histogram
decodeFromByteBuffer(final ByteBuffer
The buffer to decode from
buffer, final long
Force highestTrackableValue to be set at least this high
minBarForHighestTrackableValue)

Construct a new histogram by decoding it from a ByteBuffer.

public static Histogram

Returns:

The newly constructed histogram
decodeFromCompressedByteBuffer(final ByteBuffer
The buffer to decode from
buffer, final long
Force highestTrackableValue to be set at least this high
minBarForHighestTrackableValue)

Hides org.HdrHistogram.EncodableHistogram.decodeFromCompressedByteBuffer.

Construct a new histogram by decoding it from a compressed form in a ByteBuffer.
public static Histogram

Returns:

A Histogream decoded from the string
fromString(final String
A string containing a base64 encoding of a compressed histogram
base64CompressedHistogramString)

Construct a new Histogram by decoding it from a String containing a base64 encoded compressed histogram representation.

pack-priv long
getCountAtIndex(final int index)

Implements abstract org.HdrHistogram.AbstractHistogram.getCountAtIndex.

pack-priv long
getCountAtNormalizedIndex(final int index)

Implements abstract org.HdrHistogram.AbstractHistogram.getCountAtNormalizedIndex.

pack-priv int
getNormalizingIndexOffset()

Implements abstract org.HdrHistogram.AbstractHistogram.getNormalizingIndexOffset.

public long
getTotalCount()

Implements abstract org.HdrHistogram.AbstractHistogram.getTotalCount.

Get the total count of all recorded values in the histogram
pack-priv void
incrementCountAtIndex(final int index)

Implements abstract org.HdrHistogram.AbstractHistogram.incrementCountAtIndex.

pack-priv void
incrementTotalCount()

Implements abstract org.HdrHistogram.AbstractHistogram.incrementTotalCount.

private void
readObject(final ObjectInputStream o)

Hides org.HdrHistogram.AbstractHistogram.readObject.

pack-priv void
resize(long newHighestTrackableValue)

Implements abstract org.HdrHistogram.AbstractHistogram.resize.

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

Implements abstract org.HdrHistogram.AbstractHistogram.setCountAtIndex.

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

Implements abstract org.HdrHistogram.AbstractHistogram.setCountAtNormalizedIndex.

pack-priv void
setIntegerToDoubleValueConversionRatio(double integerToDoubleValueConversionRatio)

Implements abstract org.HdrHistogram.AbstractHistogramBase.setIntegerToDoubleValueConversionRatio.

pack-priv void
setNormalizingIndexOffset(int normalizingIndexOffset)

Implements abstract org.HdrHistogram.AbstractHistogram.setNormalizingIndexOffset.

pack-priv void
setTotalCount(final long totalCount)

Implements abstract org.HdrHistogram.AbstractHistogram.setTotalCount.

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

Implements abstract org.HdrHistogram.AbstractHistogram.shiftNormalizingIndexByOffset.

Inherited from org.HdrHistogram.AbstractHistogram:
addaddWhileCorrectingForCoordinatedOmissionallValuescopyIntocopyIntoCorrectedForCoordinatedOmissioncountsArrayIndexdecodeFromByteBufferdecodeFromCompressedByteBufferdetermineArrayLengthNeededencodeIntoByteBufferencodeIntoCompressedByteBufferencodeIntoCompressedByteBufferequalsestablishInternalTackingValuesestablishInternalTackingValuesestablishSizefillBufferFromCountsArraygetBucketIndexgetBucketsNeededToCoverValuegetCountAtValuegetCountBetweenValuesgetEndTimeStampgetEstimatedFootprintInBytesgetHighestTrackableValuegetLengthForNumberOfBucketsgetLowestDiscernibleValuegetMaxValuegetMaxValueAsDoublegetMeangetMinNonZeroValuegetMinValuegetNeededByteBufferCapacitygetNeededByteBufferCapacitygetNeededPayloadByteBufferCapacitygetNeededV0PayloadByteBufferCapacitygetNumberOfSignificantValueDigitsgetPercentileAtOrBelowValuegetStartTimeStampgetStdDeviationgetSubBucketIndexgetTaggetValueAtPercentilehashCodehighestEquivalentValueisAutoResizelinearBucketValueslogarithmicBucketValueslowestEquivalentValuemedianEquivalentValuenextNonEquivalentValuenonConcurrentNormalizingIndexShiftnormalizeIndexnumberOfSubbucketsoutputPercentileDistributionoutputPercentileDistributionoutputPercentileDistributionpercentilesrecordConvertedDoubleValuerecordConvertedDoubleValueWithCountrecordedValuesrecordValuerecordValuerecordValueWithCountrecordValueWithExpectedIntervalresetsetAutoResizesetEndTimeStampsetStartTimeStampsetTagshiftValuesLeftshiftValuesLeftshiftValuesRightshiftValuesRightsizeOfEquivalentValueRangesubtractsupportsAutoResizetoStringupdateMinAndMaxvalueFromIndexvaluesAreEquivalent

Field Detail

countsback to summary
pack-priv long[] counts
normalizingIndexOffsetback to summary
pack-priv int normalizingIndexOffset
totalCountback to summary
pack-priv long totalCount

Constructor Detail

Histogramback to summary
public Histogram(final int numberOfSignificantValueDigits)

Construct an auto-resizing histogram with a lowest discernible value of 1 and an auto-adjusting highestTrackableValue. Can auto-resize up to track values up to (Long.MAX_VALUE / 2).

Parameters
numberOfSignificantValueDigits:int

Specifies the precision to use. This is 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.

Histogramback to summary
public Histogram(final long highestTrackableValue, final int numberOfSignificantValueDigits)

Construct a Histogram given the Highest value to be tracked and a number of significant decimal digits. The histogram will be constructed to implicitly track (distinguish from 0) values as low as 1.

Parameters
highestTrackableValue:long

The highest value to be tracked by the histogram. Must be a positive integer that is >= 2.

numberOfSignificantValueDigits:int

Specifies the precision to use. This is 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.

Histogramback to summary
public Histogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits)

Construct a Histogram given the Lowest and Highest values to be tracked and a number of significant decimal digits. Providing a lowestDiscernibleValue is useful is situations where the units used for the histogram's values are much smaller that the minimal accuracy required. E.g. when tracking time values stated in nanosecond units, where the minimal accuracy required is a microsecond, the proper value for lowestDiscernibleValue would be 1000.

Parameters
lowestDiscernibleValue: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.

highestTrackableValue:long

The highest value to be tracked by the histogram. Must be a positive integer that is >= (2 * lowestDiscernibleValue).

numberOfSignificantValueDigits:int

Specifies the precision to use. This is 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.

Histogramback to summary
public Histogram(final AbstractHistogram source)

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

Parameters
source:AbstractHistogram

The source histogram to duplicate

Histogramback to summary
pack-priv Histogram(final AbstractHistogram source, boolean allocateCountsArray)
Histogramback to summary
pack-priv Histogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits, boolean allocateCountsArray)

Method Detail

_getEstimatedFootprintInBytesback to summary
pack-priv int _getEstimatedFootprintInBytes()

Implements abstract org.HdrHistogram.AbstractHistogram._getEstimatedFootprintInBytes.

Annotations
@Override
addToCountAtIndexback to summary
pack-priv void addToCountAtIndex(final int index, final long value)

Implements abstract org.HdrHistogram.AbstractHistogram.addToCountAtIndex.

Annotations
@Override
addToTotalCountback to summary
pack-priv void addToTotalCount(final long value)

Implements abstract org.HdrHistogram.AbstractHistogram.addToTotalCount.

Annotations
@Override
clearCountsback to summary
pack-priv void clearCounts()

Implements abstract org.HdrHistogram.AbstractHistogram.clearCounts.

Annotations
@Override
copyback to summary
public Histogram copy()

Implements abstract org.HdrHistogram.AbstractHistogram.copy.

Doc from org.HdrHistogram.AbstractHistogram.copy.

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

Returns:Histogram

A distinct copy of this histogram.

Annotations
@Override
copyCorrectedForCoordinatedOmissionback to summary
public Histogram copyCorrectedForCoordinatedOmission(final long expectedIntervalBetweenValueSamples)

Implements abstract org.HdrHistogram.AbstractHistogram.copyCorrectedForCoordinatedOmission.

Doc from org.HdrHistogram.AbstractHistogram.copyCorrectedForCoordinatedOmission.

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

To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, the new histogram will include an auto-generated additional series of decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records for each count found in the current histogram that is larger than the expectedIntervalBetweenValueSamples.

Note

This is a post-correction method, as opposed to the at-recording correction method provided by recordValueWithExpectedInterval. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue. by

See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.

Parameters
expectedIntervalBetweenValueSamples:long

If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples

Returns:Histogram

a copy of this histogram, corrected for coordinated omission.

Annotations
@Override
decodeFromByteBufferback to summary
public static Histogram decodeFromByteBuffer(final ByteBuffer buffer, final long minBarForHighestTrackableValue)

Construct a new histogram by decoding it from a ByteBuffer.

Parameters
buffer:ByteBuffer

The buffer to decode from

minBarForHighestTrackableValue:long

Force highestTrackableValue to be set at least this high

Returns:Histogram

The newly constructed histogram

decodeFromCompressedByteBufferback to summary
public static Histogram decodeFromCompressedByteBuffer(final ByteBuffer buffer, final long minBarForHighestTrackableValue) throws DataFormatException

Hides org.HdrHistogram.EncodableHistogram.decodeFromCompressedByteBuffer.

Construct a new histogram by decoding it from a compressed form in a ByteBuffer.

Parameters
buffer:ByteBuffer

The buffer to decode from

minBarForHighestTrackableValue:long

Force highestTrackableValue to be set at least this high

Returns:Histogram

The newly constructed histogram

Exceptions
DataFormatException:
on error parsing/decompressing the buffer
fromStringback to summary
public static Histogram fromString(final String base64CompressedHistogramString) throws DataFormatException

Construct a new Histogram by decoding it from a String containing a base64 encoded compressed histogram representation.

Parameters
base64CompressedHistogramString:String

A string containing a base64 encoding of a compressed histogram

Returns:Histogram

A Histogream decoded from the string

Exceptions
DataFormatException:
on error parsing/decompressing the input
getCountAtIndexback to summary
pack-priv long getCountAtIndex(final int index)

Implements abstract org.HdrHistogram.AbstractHistogram.getCountAtIndex.

Annotations
@Override
getCountAtNormalizedIndexback to summary
pack-priv long getCountAtNormalizedIndex(final int index)

Implements abstract org.HdrHistogram.AbstractHistogram.getCountAtNormalizedIndex.

Annotations
@Override
getNormalizingIndexOffsetback to summary
pack-priv int getNormalizingIndexOffset()

Implements abstract org.HdrHistogram.AbstractHistogram.getNormalizingIndexOffset.

Annotations
@Override
getTotalCountback to summary
public long getTotalCount()

Implements abstract org.HdrHistogram.AbstractHistogram.getTotalCount.

Doc from org.HdrHistogram.AbstractHistogram.getTotalCount.

Get the total count of all recorded values in the histogram

Returns:long

the total count of all recorded values in the histogram

Annotations
@Override
incrementCountAtIndexback to summary
pack-priv void incrementCountAtIndex(final int index)

Implements abstract org.HdrHistogram.AbstractHistogram.incrementCountAtIndex.

Annotations
@Override
incrementTotalCountback to summary
pack-priv void incrementTotalCount()

Implements abstract org.HdrHistogram.AbstractHistogram.incrementTotalCount.

Annotations
@Override
readObjectback to summary
private void readObject(final ObjectInputStream o) throws IOException, ClassNotFoundException

Hides org.HdrHistogram.AbstractHistogram.readObject.

resizeback to summary
pack-priv void resize(long newHighestTrackableValue)

Implements abstract org.HdrHistogram.AbstractHistogram.resize.

Annotations
@Override
setCountAtIndexback to summary
pack-priv void setCountAtIndex(int index, long value)

Implements abstract org.HdrHistogram.AbstractHistogram.setCountAtIndex.

Annotations
@Override
setCountAtNormalizedIndexback to summary
pack-priv void setCountAtNormalizedIndex(int index, long value)

Implements abstract org.HdrHistogram.AbstractHistogram.setCountAtNormalizedIndex.

Annotations
@Override
setIntegerToDoubleValueConversionRatioback to summary
pack-priv void setIntegerToDoubleValueConversionRatio(double integerToDoubleValueConversionRatio)

Implements abstract org.HdrHistogram.AbstractHistogramBase.setIntegerToDoubleValueConversionRatio.

Annotations
@Override
setNormalizingIndexOffsetback to summary
pack-priv void setNormalizingIndexOffset(int normalizingIndexOffset)

Implements abstract org.HdrHistogram.AbstractHistogram.setNormalizingIndexOffset.

Annotations
@Override
setTotalCountback to summary
pack-priv void setTotalCount(final long totalCount)

Implements abstract org.HdrHistogram.AbstractHistogram.setTotalCount.

Annotations
@Override
shiftNormalizingIndexByOffsetback to summary
pack-priv void shiftNormalizingIndexByOffset(int offsetToAdd, boolean lowestHalfBucketPopulated, double newIntegerToDoubleValueConversionRatio)

Implements abstract org.HdrHistogram.AbstractHistogram.shiftNormalizingIndexByOffset.

Annotations
@Override