public class PackedConcurrentHistogram extends ConcurrentHistogram
PackedConcurrentHistogram guarantees lossless recording of values into the histogram even when the
histogram is updated by multiple threads, and supports auto-resize and shift operations that may
result from or occur concurrently with other recording operations.
PackedConcurrentHistogram tracks value counts in a packed internal representation optimized
for typical histogram recoded values are sparse in the value range and tend to be incremented in small unit counts.
This packed representation tends to require significantly smaller amounts of stoarge when compared to unpacked
representations, but can incur additional recording cost due to resizing and repacking operations that may
occur as previously unrecorded values are encountered.
It is important to note that concurrent recording, auto-sizing, and value shifting are the only thread-safe
behaviors provided by PackedConcurrentHistogram, and that it is not otherwise synchronized. Specifically,
PackedConcurrentHistogram provides no implicit synchronization that would prevent the contents of the
histogram from changing during queries, iterations, copies, or addition operations on the histogram. Callers
wishing to make potentially concurrent, multi-threaded updates that would safely work in the presence of
queries, copies, or additions of histogram objects should either take care to externally synchronize and/or
order their access, use Recorder or SingleWriterRecorder which are intended for
this purpose.
Auto-resizing: When constructed with no specified value range range (or when auto-resize is turned on with AbstractHistogram.setAutoResize(boolean)) a PackedConcurrentHistogram 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.
AbstractHistogram.AllValues, AbstractHistogram.LinearBucketValues, AbstractHistogram.LogarithmicBucketValues, AbstractHistogram.Percentiles, AbstractHistogram.RecordedValues| Constructor and Description |
|---|
PackedConcurrentHistogram(AbstractHistogram 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)
|
PackedConcurrentHistogram(int numberOfSignificantValueDigits)
Construct an auto-resizing ConcurrentHistogram with a lowest discernible value of 1 and an auto-adjusting
highestTrackableValue.
|
PackedConcurrentHistogram(long highestTrackableValue,
int numberOfSignificantValueDigits)
Construct a ConcurrentHistogram given the Highest value to be tracked and a number of significant decimal
digits.
|
PackedConcurrentHistogram(long lowestDiscernibleValue,
long highestTrackableValue,
int numberOfSignificantValueDigits)
Construct a ConcurrentHistogram given the Lowest and Highest values to be tracked and a number of significant
decimal digits.
|
| Modifier and Type | Method and Description |
|---|---|
PackedConcurrentHistogram |
copy()
Create a copy of this histogram, complete with data and everything.
|
PackedConcurrentHistogram |
copyCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)
Get a copy of this histogram, corrected for coordinated omission.
|
static PackedConcurrentHistogram |
decodeFromByteBuffer(ByteBuffer buffer,
long minBarForHighestTrackableValue)
Construct a new histogram by decoding it from a ByteBuffer.
|
static PackedConcurrentHistogram |
decodeFromCompressedByteBuffer(ByteBuffer buffer,
long minBarForHighestTrackableValue)
Construct a new histogram by decoding it from a compressed form in a ByteBuffer.
|
static PackedConcurrentHistogram |
fromString(String base64CompressedHistogramString)
Construct a new ConcurrentHistogram by decoding it from a String containing a base64 encoded
compressed histogram representation.
|
long |
getTotalCount()
Get the total count of all recorded values in the histogram
|
recordConvertedDoubleValueWithCount, setAutoResizeadd, addWhileCorrectingForCoordinatedOmission, allValues, copyInto, copyIntoCorrectedForCoordinatedOmission, encodeIntoByteBuffer, encodeIntoCompressedByteBuffer, encodeIntoCompressedByteBuffer, equals, getCountAtValue, getCountBetweenValues, getEndTimeStamp, getEstimatedFootprintInBytes, getHighestTrackableValue, getLowestDiscernibleValue, getMaxValue, getMaxValueAsDouble, getMean, getMinNonZeroValue, getMinValue, getNeededByteBufferCapacity, getNumberOfSignificantValueDigits, getPercentileAtOrBelowValue, getStartTimeStamp, getStdDeviation, getTag, getValueAtPercentile, hashCode, highestEquivalentValue, isAutoResize, linearBucketValues, logarithmicBucketValues, lowestEquivalentValue, medianEquivalentValue, nextNonEquivalentValue, outputPercentileDistribution, outputPercentileDistribution, outputPercentileDistribution, percentiles, recordedValues, recordValue, recordValue, recordValueWithCount, recordValueWithExpectedInterval, reset, setEndTimeStamp, setStartTimeStamp, setTag, shiftValuesLeft, shiftValuesRight, sizeOfEquivalentValueRange, subtract, supportsAutoResize, toString, valuesAreEquivalentpublic PackedConcurrentHistogram(int numberOfSignificantValueDigits)
numberOfSignificantValueDigits - 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.public PackedConcurrentHistogram(long highestTrackableValue,
int numberOfSignificantValueDigits)
highestTrackableValue - The highest value to be tracked by the histogram. Must be a positive
integer that is >= 2.numberOfSignificantValueDigits - 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.public PackedConcurrentHistogram(long lowestDiscernibleValue,
long highestTrackableValue,
int numberOfSignificantValueDigits)
lowestDiscernibleValue - The lowest value that can be tracked (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 - The highest value to be tracked by the histogram. Must be a positive
integer that is >= (2 * lowestDiscernibleValue).numberOfSignificantValueDigits - 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.public PackedConcurrentHistogram(AbstractHistogram source)
source - The source histogram to duplicatepublic PackedConcurrentHistogram copy()
AbstractHistogramcopy in class ConcurrentHistogrampublic PackedConcurrentHistogram copyCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)
AbstractHistogram
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.
copyCorrectedForCoordinatedOmission in class ConcurrentHistogramexpectedIntervalBetweenValueSamples - If expectedIntervalBetweenValueSamples is larger than 0, add
auto-generated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamplespublic long getTotalCount()
AbstractHistogramgetTotalCount in class ConcurrentHistogrampublic static PackedConcurrentHistogram decodeFromByteBuffer(ByteBuffer buffer, long minBarForHighestTrackableValue)
buffer - The buffer to decode fromminBarForHighestTrackableValue - Force highestTrackableValue to be set at least this highpublic static PackedConcurrentHistogram decodeFromCompressedByteBuffer(ByteBuffer buffer, long minBarForHighestTrackableValue) throws DataFormatException
buffer - The buffer to decode fromminBarForHighestTrackableValue - Force highestTrackableValue to be set at least this highDataFormatException - on error parsing/decompressing the bufferpublic static PackedConcurrentHistogram fromString(String base64CompressedHistogramString) throws DataFormatException
base64CompressedHistogramString - A string containing a base64 encoding of a compressed histogramDataFormatException - on error parsing/decompressing the inputCopyright © 2019. All rights reserved.