|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.HdrHistogram.AbstractHistogram
public abstract class AbstractHistogram
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.
Constructor Summary | |
---|---|
AbstractHistogram(long lowestTrackableValue,
long highestTrackableValue,
int numberOfSignificantValueDigits)
Construct a Histogram given the Lowest and Highest values to be tracked and a number of significant decimal digits. |
Method Summary | |
---|---|
void |
add(AbstractHistogram fromHistogram)
Add the contents of another histogram to this one. |
void |
addWhileCorrectingForCoordinatedOmission(AbstractHistogram fromHistogram,
long expectedIntervalBetweenValueSamples)
Add the contents of another histogram to this one, while correcting the incoming data for coordinated omission. |
abstract AbstractHistogram |
copy()
Create a copy of this histogram, complete with data and everything. |
abstract AbstractHistogram |
copyCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)
Get a copy of this histogram, corrected for coordinated omission. |
void |
copyInto(AbstractHistogram targetHistogram)
Copy this histogram into the target histogram, overwriting it's contents. |
void |
copyIntoCorrectedForCoordinatedOmission(AbstractHistogram targetHistogram,
long expectedIntervalBetweenValueSamples)
Copy this histogram, corrected for coordinated omission, into the target histogram, overwriting it's contents. |
int |
encodeIntoByteBuffer(ByteBuffer buffer)
Encode this histogram into a ByteBuffer |
int |
encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer)
Encode this histogram in compressed form into a byte array |
int |
encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer,
int compressionLevel)
Encode this histogram in compressed form into a byte array |
boolean |
equals(Object other)
Determine if this histogram is equivalent to another. |
long |
getEndTimeStamp()
get the end time stamp [optionally] stored with this histogram |
int |
getEstimatedFootprintInBytes()
Provide a (conservatively high) estimate of the Histogram's total footprint in bytes |
long |
getHighestTrackableValue()
get the configured highestTrackableValue |
HistogramData |
getHistogramData()
Provide access to the histogram's data set. |
long |
getLowestTrackableValue()
get the configured lowestTrackableValue |
int |
getNeededByteBufferCapacity()
Get the capacity needed to encode this histogram into a ByteBuffer |
int |
getNumberOfSignificantValueDigits()
get the configured numberOfSignificantValueDigits |
long |
getStartTimeStamp()
get the start time stamp [optionally] stored with this histogram |
boolean |
hasOverflowed()
Determine if this histogram had any of it's value counts overflow. |
long |
highestEquivalentValue(long value)
Get the highest value that is equivalent to the given value within the histogram's resolution. |
long |
lowestEquivalentValue(long value)
Get the lowest value that is equivalent to the given value within the histogram's resolution. |
long |
medianEquivalentValue(long value)
Get a value that lies in the middle (rounded up) of the range of values equivalent the given value. |
long |
nextNonEquivalentValue(long value)
Get the next value that is not equivalent to the given value within the histogram's resolution. |
void |
recordValue(long value)
Record a value in the histogram |
void |
recordValue(long value,
long expectedIntervalBetweenValueSamples)
Deprecated. Record a value in the histogram. This deprecated method has identical behavior to recordValueWithExpectedInterval() . It was renamed to avoid ambiguity. |
void |
recordValueWithCount(long value,
long count)
Record a value in the histogram (adding to the value's current count) |
void |
recordValueWithExpectedInterval(long value,
long expectedIntervalBetweenValueSamples)
Record a value in the histogram. |
void |
reestablishTotalCount()
Reestablish the internal notion of totalCount by recalculating it from recorded values. |
void |
reset()
Reset the contents and stats of this histogram |
void |
setEndTimeStamp(long timeStampMsec)
Set the end time stamp value associated with this histogram to a given value. |
void |
setStartTimeStamp(long timeStampMsec)
Set the start time stamp value associated with this histogram to a given value. |
long |
sizeOfEquivalentValueRange(long value)
Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution. |
boolean |
valuesAreEquivalent(long value1,
long value2)
Determine if two values are equivalent with the histogram's resolution. |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public AbstractHistogram(long lowestTrackableValue, long highestTrackableValue, int numberOfSignificantValueDigits)
lowestTrackableValue
- 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 * lowestTrackableValue).numberOfSignificantValueDigits
- 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.Method Detail |
---|
public abstract AbstractHistogram copy()
public abstract AbstractHistogram copyCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)
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.
expectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add
auto-generated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamples
ArrayIndexOutOfBoundsException
public int getEstimatedFootprintInBytes()
public void copyInto(AbstractHistogram targetHistogram)
targetHistogram
- public void copyIntoCorrectedForCoordinatedOmission(AbstractHistogram targetHistogram, long expectedIntervalBetweenValueSamples)
copyCorrectedForCoordinatedOmission(long)
for more detailed explanation about how correction is applied)
targetHistogram
- expectedIntervalBetweenValueSamples
- public long getLowestTrackableValue()
public long getHighestTrackableValue()
public int getNumberOfSignificantValueDigits()
public long getStartTimeStamp()
public void setStartTimeStamp(long timeStampMsec)
timeStampMsec
- the value to set the time stamp to, [by convention] in msec since the epoch.public long getEndTimeStamp()
public void setEndTimeStamp(long timeStampMsec)
timeStampMsec
- the value to set the time stamp to, [by convention] in msec since the epoch.public void recordValueWithExpectedInterval(long value, long expectedIntervalBetweenValueSamples) throws ArrayIndexOutOfBoundsException
To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, Histogram will auto-generate an additional series of decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records.
Note: This is a at-recording correction method, as opposed to the post-recording correction method provided
by getHistogramCorrectedForCoordinatedOmission
.
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.
See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
value
- The value to recordexpectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add
auto-generated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamples
ArrayIndexOutOfBoundsException
public void recordValue(long value, long expectedIntervalBetweenValueSamples) throws ArrayIndexOutOfBoundsException
recordValueWithExpectedInterval()
. It was renamed to avoid ambiguity.
value
- The value to recordexpectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add
auto-generated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamples
ArrayIndexOutOfBoundsException
public void recordValueWithCount(long value, long count) throws ArrayIndexOutOfBoundsException
value
- The value to be recordedcount
- The number of occurrences of this value to record
ArrayIndexOutOfBoundsException
public void recordValue(long value) throws ArrayIndexOutOfBoundsException
value
- The value to be recorded
ArrayIndexOutOfBoundsException
public void reset()
public void add(AbstractHistogram fromHistogram) throws ArrayIndexOutOfBoundsException
fromHistogram
- The other histogram.
ArrayIndexOutOfBoundsException
- if fromHistogram's highestTrackableValue is larger than this one's.public void addWhileCorrectingForCoordinatedOmission(AbstractHistogram fromHistogram, long expectedIntervalBetweenValueSamples)
To compensate for the loss of sampled values when a recorded value is larger than the expected
interval between value samples, the values added 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-recording 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.
fromHistogram
- The other histogram. highestTrackableValue and largestValueWithSingleUnitResolution must match.expectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add
auto-generated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamples
ArrayIndexOutOfBoundsException
public boolean hasOverflowed()
public void reestablishTotalCount()
In cases of concurrent modifications such as during copying, or due to racy multi-threaded updates on non-atomic or non-synchronized variants, which can result in potential loss of counts and an inconsistent (indicating potential overflow) internal state, calling this method on a histogram will reestablish a consistent internal state based on the potentially lossy counts representations.
Note that this method is not synchronized against concurrent modification in any way, and will only reliably reestablish consistent internal state when no concurrent modification of the histogram is performed while it executes.
Note that in the cases of actual overflow conditions (which can result in negative counts) this self consistent view may be very wrong, and not just slightly lossy.
public boolean equals(Object other)
equals
in class Object
other
- the other histogram to compare to
public HistogramData getHistogramData()
HistogramData
that can be used to query stats and iterate through the default (corrected)
data set.public long sizeOfEquivalentValueRange(long value)
value
- The given value
public long lowestEquivalentValue(long value)
value
- The given value
public long highestEquivalentValue(long value)
value
- The given value
public long medianEquivalentValue(long value)
value
- The given value
public long nextNonEquivalentValue(long value)
value
- The given value
public boolean valuesAreEquivalent(long value1, long value2)
value1
- first value to comparevalue2
- second value to compare
public int getNeededByteBufferCapacity()
public int encodeIntoByteBuffer(ByteBuffer buffer)
buffer
- The buffer to encode into
public int encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer, int compressionLevel)
targetBuffer
- The buffer to encode intocompressionLevel
- Compression level (for java.util.zip.Deflater).
public int encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer)
targetBuffer
- The buffer to encode into
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |