PackedHistogram 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.
PackedHistogram 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.
For example, a PackedHistogram could be configured to track the counts of observed integer values between 0 and
3,600,000,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 nanosecond 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).
Auto-resizing: When constructed with no specified value range range (or when auto-resize is turned on with Histogram#setAutoResize) a PackedHistogram 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. for details.
| Modifier and Type | Field and Description |
|---|---|
| private PackedLongArray |
| Access | Constructor and Description |
|---|---|
| public | PackedHistogram(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 PackedHistogram with a lowest discernible value of 1 and an auto-adjusting highestTrackableValue. |
| public | PackedHistogram(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 PackedHistogram given the Highest value to be tracked and a number of significant decimal digits. |
| public | PackedHistogram(final long
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. 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 PackedHistogram given the Lowest and Highest values to be tracked and a number of significant decimal digits. |
| public | PackedHistogram(final AbstractHistogram
The source histogram to duplicate source)Construct a PackedHistogram with the same range settings as a given source histogram, duplicating the source's start/end timestamps (but NOT it's contents) |
| Modifier and Type | Method and Description |
|---|---|
| pack-priv int | |
| pack-priv void | addToCountAtIndex(final int index, final long value)
Overrides org. |
| pack-priv void | |
| public PackedHistogram | copy()
Overrides org. |
| public PackedHistogram | copyCorrectedForCoordinatedOmission(final long
If expectedIntervalBetweenValueSamples is larger than 0, add
auto-generated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamples expectedIntervalBetweenValueSamples)Overrides org. |
| public static PackedHistogram | Returns: The newly constructed histogramThe 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 PackedHistogram | Returns: The newly constructed histogramThe buffer to decode from buffer, final long Force highestTrackableValue to be set at least this high minBarForHighestTrackableValue)Hides org. |
| pack-priv long | |
| pack-priv long | getCountAtNormalizedIndex(final int index)
Overrides org. |
| pack-priv void | |
| private void | |
| pack-priv void | |
| pack-priv void | |
| pack-priv void | setCountAtNormalizedIndex(int index, long value)
Overrides org. |
| packedCounts | back to summary |
|---|---|
| private PackedLongArray packedCounts | |
| PackedHistogram | back to summary |
|---|---|
| public PackedHistogram(final int numberOfSignificantValueDigits) Construct an auto-resizing PackedHistogram 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).
| |
| PackedHistogram | back to summary |
|---|---|
| public PackedHistogram(final long highestTrackableValue, final int numberOfSignificantValueDigits) Construct a PackedHistogram 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.
| |
| PackedHistogram | back to summary |
|---|---|
| public PackedHistogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits) Construct a PackedHistogram 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.
| |
| PackedHistogram | back to summary |
|---|---|
| public PackedHistogram(final AbstractHistogram source) Construct a PackedHistogram with the same range settings as a given source histogram, duplicating the source's start/end timestamps (but NOT it's contents)
| |
| _getEstimatedFootprintInBytes | back to summary |
|---|---|
| pack-priv int _getEstimatedFootprintInBytes() Overrides org.
| |
| addToCountAtIndex | back to summary |
|---|---|
| pack-priv void addToCountAtIndex(final int index, final long value) Overrides org.
| |
| clearCounts | back to summary |
|---|---|
| pack-priv void clearCounts() Overrides org.
| |
| copy | back to summary |
|---|---|
| public PackedHistogram copy() Overrides org. Doc from org. Create a copy of this histogram, complete with data and everything.
| |
| copyCorrectedForCoordinatedOmission | back to summary |
|---|---|
| public PackedHistogram copyCorrectedForCoordinatedOmission(final long expectedIntervalBetweenValueSamples) Overrides org. Doc from org. 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 See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
| |
| decodeFromByteBuffer | back to summary |
|---|---|
| public static PackedHistogram decodeFromByteBuffer(final ByteBuffer buffer, final long minBarForHighestTrackableValue) Hides org. Construct a new histogram by decoding it from a ByteBuffer.
| |
| decodeFromCompressedByteBuffer | back to summary |
|---|---|
| public static PackedHistogram decodeFromCompressedByteBuffer(final ByteBuffer buffer, final long minBarForHighestTrackableValue) throws DataFormatException Hides org. Construct a new histogram by decoding it from a compressed form in a ByteBuffer.
| |
| getCountAtIndex | back to summary |
|---|---|
| pack-priv long getCountAtIndex(final int index) Overrides org.
| |
| getCountAtNormalizedIndex | back to summary |
|---|---|
| pack-priv long getCountAtNormalizedIndex(final int index) Overrides org.
| |
| incrementCountAtIndex | back to summary |
|---|---|
| pack-priv void incrementCountAtIndex(final int index) Overrides org.
| |
| readObject | back to summary |
|---|---|
| private void readObject(final ObjectInputStream o) throws IOException, ClassNotFoundException | |
| resize | back to summary |
|---|---|
| pack-priv void resize(long newHighestTrackableValue) Overrides org.
| |
| setCountAtIndex | back to summary |
|---|---|
| pack-priv void setCountAtIndex(int index, long value) Overrides org.
| |
| setCountAtNormalizedIndex | back to summary |
|---|---|
| pack-priv void setCountAtNormalizedIndex(int index, long value) Overrides org.
| |