Class DoubleHistogram
- java.lang.Object
-
- org.HdrHistogram.EncodableHistogram
-
- org.HdrHistogram.DoubleHistogram
-
- All Implemented Interfaces:
java.io.Serializable
,DoubleValueRecorder
- Direct Known Subclasses:
ConcurrentDoubleHistogram
,PackedDoubleHistogram
,SingleWriterDoubleRecorder.InternalDoubleHistogram
,SynchronizedDoubleHistogram
public class DoubleHistogram extends EncodableHistogram implements DoubleValueRecorder, java.io.Serializable
A floating point values High Dynamic Range (HDR) Histogram
It is important to note that
DoubleHistogram
is not thread-safe, and does not support safe concurrent recording by multiple threads. If concurrent operation is required, consider usingsConcurrentDoubleHistogram
,SynchronizedDoubleHistogram
, or (recommended)DoubleRecorder
orSingleWriterDoubleRecorder
which are intended for this purpose.DoubleHistogram
supports the recording and analyzing sampled data value counts across a configurable dynamic range of floating point (double) values, with configurable value precision within the range. Dynamic range is expressed as a ratio between the highest and lowest non-zero values trackable within the histogram at any given time. Value precision is expressed as the number of significant [decimal] 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.Auto-ranging: Unlike integer value based histograms, the specific value range tracked by a
DoubleHistogram
is not specified upfront. Only the dynamic range of values that the histogram can cover is (optionally) specified. E.g. When aDoubleHistogram
is created to track a dynamic range of 3600000000000 (enough to track values from a nanosecond to an hour), values could be recorded into into it in any consistent unit of time as long as the ratio between the highest and lowest non-zero values stays within the specified dynamic range, so recording in units of nanoseconds (1.0 thru 3600000000000.0), milliseconds (0.000001 thru 3600000.0) seconds (0.000000001 thru 3600.0), hours (1/3.6E12 thru 1.0) will all work just as well.Auto-resizing: When constructed with no specified dynamic range (or when auto-resize is turned on with
setAutoResize(boolean)
) aDoubleHistogram
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.Attempts to record non-zero values that range outside of the specified dynamic range (or exceed the limits of of dynamic range when auto-resizing) may results in
ArrayIndexOutOfBoundsException
exceptions, either due to overflow or underflow conditions. These exceptions will only be thrown if recording the value would have resulted in discarding or losing the required value precision of values already recorded in the histogram.See package description for
org.HdrHistogram
for details.- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
DoubleHistogram.AllValues
class
DoubleHistogram.LinearBucketValues
class
DoubleHistogram.LogarithmicBucketValues
class
DoubleHistogram.Percentiles
class
DoubleHistogram.RecordedValues
AnIterable
<DoubleHistogramIterationValue
> through the histogram using aDoubleRecordedValuesIterator
-
Field Summary
Fields Modifier and Type Field Description private boolean
autoResize
private long
configuredHighestToLowestValueRatio
private static java.lang.Class[]
constructorArgTypes
private double
currentHighestValueLimitInAutoRange
private double
currentLowestValueInAutoRange
private static int
DHIST_compressedEncodingCookie
private static int
DHIST_encodingCookie
private static double
highestAllowedValueEver
(package private) AbstractHistogram
integerValuesHistogram
private static long
serialVersionUID
-
Constructor Summary
Constructors Modifier Constructor Description DoubleHistogram(int numberOfSignificantValueDigits)
Construct a new auto-resizing DoubleHistogram using a precision stated as a number of significant decimal digits.DoubleHistogram(int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass)
Construct a new auto-resizing DoubleHistogram using a precision stated as a number of significant decimal digits.DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits)
Construct a new DoubleHistogram with the specified dynamic range (provided inhighestToLowestValueRatio
) and using a precision stated as a number of significant decimal digits.protected
DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass)
Construct a new DoubleHistogram with the specified dynamic range (provided inhighestToLowestValueRatio
) and using a precision stated as a number of significant decimal digits.(package private)
DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, AbstractHistogram internalCountsHistogram)
private
DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, AbstractHistogram internalCountsHistogram, boolean mimicInternalModel)
DoubleHistogram(DoubleHistogram source)
Construct aDoubleHistogram
with the same range settings as a given source, duplicating the source's start/end timestamps (but NOT it's contents)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(DoubleHistogram fromHistogram)
Add the contents of another histogram to this one.void
addWhileCorrectingForCoordinatedOmission(DoubleHistogram fromHistogram, double expectedIntervalBetweenValueSamples)
Add the contents of another histogram to this one, while correcting the incoming data for coordinated omission.DoubleHistogram.AllValues
allValues()
Provide a means of iterating through all histogram values using the finest granularity steps supported by the underlying representation.private void
autoAdjustRangeForValue(double value)
private void
autoAdjustRangeForValueSlowPath(double value)
(package private) static <T extends DoubleHistogram>
TconstructHistogramFromBuffer(int cookie, java.nio.ByteBuffer buffer, java.lang.Class<T> doubleHistogramClass, java.lang.Class<? extends AbstractHistogram> histogramClass, long minBarForHighestToLowestValueRatio)
DoubleHistogram
copy()
Create a copy of this histogram, complete with data and everything.DoubleHistogram
copyCorrectedForCoordinatedOmission(double expectedIntervalBetweenValueSamples)
Get a copy of this histogram, corrected for coordinated omission.void
copyInto(DoubleHistogram targetHistogram)
Copy this histogram into the target histogram, overwriting it's contents.void
copyIntoCorrectedForCoordinatedOmission(DoubleHistogram targetHistogram, double expectedIntervalBetweenValueSamples)
Copy this histogram, corrected for coordinated omission, into the target histogram, overwriting it's contents.static DoubleHistogram
decodeFromByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestToLowestValueRatio)
Construct a new DoubleHistogram by decoding it from a ByteBuffer.static DoubleHistogram
decodeFromByteBuffer(java.nio.ByteBuffer buffer, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, long minBarForHighestToLowestValueRatio)
Construct a new DoubleHistogram by decoding it from a ByteBuffer, using a specified AbstractHistogram subclass for tracking internal counts (e.g.static DoubleHistogram
decodeFromCompressedByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestToLowestValueRatio)
Construct a new DoubleHistogram by decoding it from a compressed form in a ByteBuffer.static DoubleHistogram
decodeFromCompressedByteBuffer(java.nio.ByteBuffer buffer, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, long minBarForHighestToLowestValueRatio)
Construct a new DoubleHistogram by decoding it from a compressed form in a ByteBuffer, using a specified AbstractHistogram subclass for tracking internal counts (e.g.private long
deriveIntegerValueRange(long externalHighestToLowestValueRatio, int numberOfSignificantValueDigits)
private long
deriveInternalHighestToLowestValueRatio(long externalHighestToLowestValueRatio)
int
encodeIntoByteBuffer(java.nio.ByteBuffer buffer)
Encode this histogram into a ByteBufferint
encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer)
Encode this histogram in compressed form into a byte arrayint
encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer, int compressionLevel)
Encode this histogram in compressed form into a byte arrayboolean
equals(java.lang.Object other)
Determine if this histogram is equivalent to another.private int
findCappedContainingBinaryOrderOfMagnitude(double doubleNumber)
private static int
findContainingBinaryOrderOfMagnitude(double doubleNumber)
private static int
findContainingBinaryOrderOfMagnitude(long longNumber)
static DoubleHistogram
fromString(java.lang.String base64CompressedHistogramString)
Construct a new DoubleHistogram by decoding it from a String containing a base64 encoded compressed histogram representation.long
getCountAtValue(double value)
Get the count of recorded values at a specific value (to within the histogram resolution at the value level).double
getCountBetweenValues(double lowValue, double highValue)
Get the count of recorded values within a range of value levels (inclusive to within the histogram's resolution).(package private) double
getCurrentHighestTrackableValue()
get the current highest trackable value in the automatically determined range (keep in mind that this can change because it is auto ranging)(package private) double
getCurrentLowestTrackableNonZeroValue()
get the current lowest (non zero) trackable value the automatically determined range (keep in mind that this can change because it is auto ranging)(package private) double
getDoubleToIntegerValueConversionRatio()
long
getEndTimeStamp()
get the end time stamp [optionally] stored with this histogramint
getEstimatedFootprintInBytes()
Provide a (conservatively high) estimate of the Histogram's total footprint in byteslong
getHighestToLowestValueRatio()
get the Dynamic range of the histogram: the configured ratio between the highest trackable value and the lowest trackable non zero value at any given time.double
getIntegerToDoubleValueConversionRatio()
Get the current conversion ratio from interval integer value representation to double units.private long
getLowestTrackingIntegerValue()
double
getMaxValue()
Get the highest recorded value level in the histogramdouble
getMaxValueAsDouble()
Get the highest recorded value level in the histogram as a doubledouble
getMean()
Get the computed mean value of all recorded values in the histogramdouble
getMinNonZeroValue()
Get the lowest recorded non-zero value level in the histogramdouble
getMinValue()
Get the lowest recorded value level in the histogramint
getNeededByteBufferCapacity()
Get the capacity needed to encode this histogram into a ByteBufferprivate int
getNeededByteBufferCapacity(int relevantLength)
int
getNumberOfSignificantValueDigits()
get the configured numberOfSignificantValueDigitsdouble
getPercentileAtOrBelowValue(double value)
Get the percentile at a given value.long
getStartTimeStamp()
get the start time stamp [optionally] stored with this histogramdouble
getStdDeviation()
Get the computed standard deviation of all recorded values in the histogramjava.lang.String
getTag()
get the tag string [optionally] associated with this histogramlong
getTotalCount()
Get the total count of all recorded values in the histogramdouble
getValueAtPercentile(double percentile)
Get the value at a given percentile.private void
handleShiftValuesException(int numberOfBinaryOrdersOfMagnitude, java.lang.Exception ex)
int
hashCode()
double
highestEquivalentValue(double value)
Get the highest value that is equivalent to the given value within the histogram's resolution.private void
init(long configuredHighestToLowestValueRatio, double lowestTrackableUnitValue, AbstractHistogram integerValuesHistogram)
boolean
isAutoResize()
(package private) static boolean
isCompressedDoubleHistogramCookie(int cookie)
(package private) static boolean
isDoubleHistogramCookie(int cookie)
(package private) static boolean
isNonCompressedDoubleHistogramCookie(int cookie)
DoubleHistogram.LinearBucketValues
linearBucketValues(double valueUnitsPerBucket)
Provide a means of iterating through histogram values using linear steps.DoubleHistogram.LogarithmicBucketValues
logarithmicBucketValues(double valueUnitsInFirstBucket, double logBase)
Provide a means of iterating through histogram values at logarithmically increasing levels.double
lowestEquivalentValue(double value)
Get the lowest value that is equivalent to the given value within the histogram's resolution.double
medianEquivalentValue(double value)
Get a value that lies in the middle (rounded up) of the range of values equivalent the given value.double
nextNonEquivalentValue(double value)
Get the next value that is not equivalent to the given value within the histogram's resolution.void
outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio)
Produce textual representation of the value distribution of histogram data by percentile.void
outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio, boolean useCsvFormat)
Produce textual representation of the value distribution of histogram data by percentile.void
outputPercentileDistribution(java.io.PrintStream printStream, java.lang.Double outputValueUnitScalingRatio)
Produce textual representation of the value distribution of histogram data by percentile.DoubleHistogram.Percentiles
percentiles(int percentileTicksPerHalfDistance)
Provide a means of iterating through histogram values according to percentile levels.private void
readObject(java.io.ObjectInputStream o)
private void
recordCountAtValue(long count, double value)
DoubleHistogram.RecordedValues
recordedValues()
Provide a means of iterating through all recorded histogram values using the finest granularity steps supported by the underlying representation.private void
recordSingleValue(double value)
void
recordValue(double value)
Record a value in the histogramvoid
recordValueWithCount(double value, long count)
Record a value in the histogram (adding to the value's current count)private void
recordValueWithCountAndExpectedInterval(double value, long count, double expectedIntervalBetweenValueSamples)
void
recordValueWithExpectedInterval(double value, double expectedIntervalBetweenValueSamples)
Record a value in the histogram.void
reset()
Reset the contents and stats of this histogramvoid
setAutoResize(boolean autoResize)
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.void
setTag(java.lang.String tag)
Set the tag string associated with this histogramprivate void
setTrackableValueRange(double lowestValueInAutoRange, double highestValueInAutoRange)
private void
shiftCoveredRangeToTheLeft(int numberOfBinaryOrdersOfMagnitude)
private void
shiftCoveredRangeToTheRight(int numberOfBinaryOrdersOfMagnitude)
double
sizeOfEquivalentValueRange(double value)
Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution.void
subtract(DoubleHistogram otherHistogram)
Subtract the contents of another histogram from this one.boolean
valuesAreEquivalent(double value1, double value2)
Determine if two values are equivalent with the histogram's resolution.private void
writeObject(java.io.ObjectOutputStream o)
-
-
-
Field Detail
-
highestAllowedValueEver
private static final double highestAllowedValueEver
-
configuredHighestToLowestValueRatio
private long configuredHighestToLowestValueRatio
-
currentLowestValueInAutoRange
private volatile double currentLowestValueInAutoRange
-
currentHighestValueLimitInAutoRange
private volatile double currentHighestValueLimitInAutoRange
-
integerValuesHistogram
AbstractHistogram integerValuesHistogram
-
autoResize
private boolean autoResize
-
serialVersionUID
private static final long serialVersionUID
- See Also:
- Constant Field Values
-
DHIST_encodingCookie
private static final int DHIST_encodingCookie
- See Also:
- Constant Field Values
-
DHIST_compressedEncodingCookie
private static final int DHIST_compressedEncodingCookie
- See Also:
- Constant Field Values
-
constructorArgTypes
private static final java.lang.Class[] constructorArgTypes
-
-
Constructor Detail
-
DoubleHistogram
public DoubleHistogram(int numberOfSignificantValueDigits)
Construct a new auto-resizing DoubleHistogram using a precision stated as a number of significant decimal digits.- Parameters:
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.
-
DoubleHistogram
public DoubleHistogram(int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass)
Construct a new auto-resizing DoubleHistogram using a precision stated as a number of significant decimal digits. TheDoubleHistogram
will use the specified AbstractHistogram subclass for tracking internal counts (e.g.Histogram
,ConcurrentHistogram
,SynchronizedHistogram
,IntCountsHistogram
,ShortCountsHistogram
).- Parameters:
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.internalCountsHistogramClass
- The class to use for internal counts tracking
-
DoubleHistogram
public DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits)
Construct a new DoubleHistogram with the specified dynamic range (provided inhighestToLowestValueRatio
) and using a precision stated as a number of significant decimal digits.- Parameters:
highestToLowestValueRatio
- specifies the dynamic range to usenumberOfSignificantValueDigits
- 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.
-
DoubleHistogram
protected DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass)
Construct a new DoubleHistogram with the specified dynamic range (provided inhighestToLowestValueRatio
) and using a precision stated as a number of significant decimal digits. TheDoubleHistogram
will use the specified AbstractHistogram subclass for tracking internal counts (e.g.Histogram
,ConcurrentHistogram
,SynchronizedHistogram
,IntCountsHistogram
,ShortCountsHistogram
).- Parameters:
highestToLowestValueRatio
- specifies the dynamic range to use.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.internalCountsHistogramClass
- The class to use for internal counts tracking
-
DoubleHistogram
DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, AbstractHistogram internalCountsHistogram)
-
DoubleHistogram
private DoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, AbstractHistogram internalCountsHistogram, boolean mimicInternalModel)
-
DoubleHistogram
public DoubleHistogram(DoubleHistogram source)
Construct aDoubleHistogram
with the same range settings as a given source, duplicating the source's start/end timestamps (but NOT it's contents)- Parameters:
source
- The source histogram to duplicate
-
-
Method Detail
-
init
private void init(long configuredHighestToLowestValueRatio, double lowestTrackableUnitValue, AbstractHistogram integerValuesHistogram)
-
setTrackableValueRange
private void setTrackableValueRange(double lowestValueInAutoRange, double highestValueInAutoRange)
-
getDoubleToIntegerValueConversionRatio
double getDoubleToIntegerValueConversionRatio()
-
isAutoResize
public boolean isAutoResize()
-
setAutoResize
public void setAutoResize(boolean autoResize)
-
recordValue
public void recordValue(double value) throws java.lang.ArrayIndexOutOfBoundsException
Record a value in the histogram- Specified by:
recordValue
in interfaceDoubleValueRecorder
- Parameters:
value
- The value to be recorded- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value cannot be covered by the histogram's range
-
recordValueWithCount
public void recordValueWithCount(double value, long count) throws java.lang.ArrayIndexOutOfBoundsException
Record a value in the histogram (adding to the value's current count)- Specified by:
recordValueWithCount
in interfaceDoubleValueRecorder
- Parameters:
value
- The value to be recordedcount
- The number of occurrences of this value to record- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value cannot be covered by the histogram's range
-
recordValueWithExpectedInterval
public void recordValueWithExpectedInterval(double value, double expectedIntervalBetweenValueSamples) throws java.lang.ArrayIndexOutOfBoundsException
Record a value in the histogram.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
copyCorrectedForCoordinatedOmission(double)
. The use cases for these 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.
- Specified by:
recordValueWithExpectedInterval
in interfaceDoubleValueRecorder
- Parameters:
value
- The value to recordexpectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value cannot be covered by the histogram's range
-
recordCountAtValue
private void recordCountAtValue(long count, double value) throws java.lang.ArrayIndexOutOfBoundsException
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-
recordSingleValue
private void recordSingleValue(double value) throws java.lang.ArrayIndexOutOfBoundsException
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-
recordValueWithCountAndExpectedInterval
private void recordValueWithCountAndExpectedInterval(double value, long count, double expectedIntervalBetweenValueSamples) throws java.lang.ArrayIndexOutOfBoundsException
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-
autoAdjustRangeForValue
private void autoAdjustRangeForValue(double value)
-
autoAdjustRangeForValueSlowPath
private void autoAdjustRangeForValueSlowPath(double value)
-
shiftCoveredRangeToTheRight
private void shiftCoveredRangeToTheRight(int numberOfBinaryOrdersOfMagnitude)
-
shiftCoveredRangeToTheLeft
private void shiftCoveredRangeToTheLeft(int numberOfBinaryOrdersOfMagnitude)
-
handleShiftValuesException
private void handleShiftValuesException(int numberOfBinaryOrdersOfMagnitude, java.lang.Exception ex)
-
reset
public void reset()
Reset the contents and stats of this histogram- Specified by:
reset
in interfaceDoubleValueRecorder
-
copy
public DoubleHistogram copy()
Create a copy of this histogram, complete with data and everything.- Returns:
- A distinct copy of this histogram.
-
copyCorrectedForCoordinatedOmission
public DoubleHistogram copyCorrectedForCoordinatedOmission(double expectedIntervalBetweenValueSamples)
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. bySee notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
- Parameters:
expectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples- Returns:
- a copy of this histogram, corrected for coordinated omission.
-
copyInto
public void copyInto(DoubleHistogram targetHistogram)
Copy this histogram into the target histogram, overwriting it's contents.- Parameters:
targetHistogram
- the histogram to copy into
-
copyIntoCorrectedForCoordinatedOmission
public void copyIntoCorrectedForCoordinatedOmission(DoubleHistogram targetHistogram, double expectedIntervalBetweenValueSamples)
Copy this histogram, corrected for coordinated omission, into the target histogram, overwriting it's contents. (seecopyCorrectedForCoordinatedOmission(double)
for more detailed explanation about how correction is applied)- Parameters:
targetHistogram
- the histogram to copy intoexpectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
-
add
public void add(DoubleHistogram fromHistogram) throws java.lang.ArrayIndexOutOfBoundsException
Add the contents of another histogram to this one.- Parameters:
fromHistogram
- The other histogram.- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if values in fromHistogram's cannot be covered by this histogram's range
-
addWhileCorrectingForCoordinatedOmission
public void addWhileCorrectingForCoordinatedOmission(DoubleHistogram fromHistogram, double expectedIntervalBetweenValueSamples)
Add the contents of another histogram to this one, while correcting the incoming data 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 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. bySee notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
- Parameters:
fromHistogram
- Other histogram. highestToLowestValueRatio and numberOfSignificantValueDigits must match.expectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if values exceed highestTrackableValue
-
subtract
public void subtract(DoubleHistogram otherHistogram)
Subtract the contents of another histogram from this one.- Parameters:
otherHistogram
- The other histogram.- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if values in fromHistogram's cannot be covered by this histogram's range
-
equals
public boolean equals(java.lang.Object other)
Determine if this histogram is equivalent to another.- Overrides:
equals
in classjava.lang.Object
- Parameters:
other
- the other histogram to compare to- Returns:
- True if this histogram are equivalent with the other.
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
getTotalCount
public long getTotalCount()
Get the total count of all recorded values in the histogram- Returns:
- the total count of all recorded values in the histogram
-
getCurrentLowestTrackableNonZeroValue
double getCurrentLowestTrackableNonZeroValue()
get the current lowest (non zero) trackable value the automatically determined range (keep in mind that this can change because it is auto ranging)- Returns:
- current lowest trackable value the automatically determined range
-
getCurrentHighestTrackableValue
double getCurrentHighestTrackableValue()
get the current highest trackable value in the automatically determined range (keep in mind that this can change because it is auto ranging)- Returns:
- current highest trackable value in the automatically determined range
-
getIntegerToDoubleValueConversionRatio
public double getIntegerToDoubleValueConversionRatio()
Get the current conversion ratio from interval integer value representation to double units. (keep in mind that this can change because it is auto ranging). This ratio can be useful for converting integer values found in iteration, although the preferred form for accessing iteration values would be to use thegetDoubleValueIteratedTo()
andgetDoubleValueIteratedFrom()
accessors toHistogramIterationValue
iterated values.- Returns:
- the current conversion ratio from interval integer value representation to double units.
-
getNumberOfSignificantValueDigits
public int getNumberOfSignificantValueDigits()
get the configured numberOfSignificantValueDigits- Returns:
- numberOfSignificantValueDigits
-
getHighestToLowestValueRatio
public long getHighestToLowestValueRatio()
get the Dynamic range of the histogram: the configured ratio between the highest trackable value and the lowest trackable non zero value at any given time.- Returns:
- the dynamic range of the histogram, expressed as the ratio between the highest trackable value and the lowest trackable non zero value at any given time.
-
sizeOfEquivalentValueRange
public double sizeOfEquivalentValueRange(double value)
Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.- Parameters:
value
- The given value- Returns:
- The lowest value that is equivalent to the given value within the histogram's resolution.
-
lowestEquivalentValue
public double lowestEquivalentValue(double value)
Get the lowest value that is equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.- Parameters:
value
- The given value- Returns:
- The lowest value that is equivalent to the given value within the histogram's resolution.
-
highestEquivalentValue
public double highestEquivalentValue(double value)
Get the highest value that is equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.- Parameters:
value
- The given value- Returns:
- The highest value that is equivalent to the given value within the histogram's resolution.
-
medianEquivalentValue
public double medianEquivalentValue(double value)
Get a value that lies in the middle (rounded up) of the range of values equivalent the given value. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.- Parameters:
value
- The given value- Returns:
- The value lies in the middle (rounded up) of the range of values equivalent the given value.
-
nextNonEquivalentValue
public double nextNonEquivalentValue(double value)
Get the next value that is not equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.- Parameters:
value
- The given value- Returns:
- The next value that is not equivalent to the given value within the histogram's resolution.
-
valuesAreEquivalent
public boolean valuesAreEquivalent(double value1, double value2)
Determine if two values are equivalent with the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.- Parameters:
value1
- first value to comparevalue2
- second value to compare- Returns:
- True if values are equivalent to within the histogram's resolution.
-
getEstimatedFootprintInBytes
public int getEstimatedFootprintInBytes()
Provide a (conservatively high) estimate of the Histogram's total footprint in bytes- Returns:
- a (conservatively high) estimate of the Histogram's total footprint in bytes
-
getStartTimeStamp
public long getStartTimeStamp()
get the start time stamp [optionally] stored with this histogram- Specified by:
getStartTimeStamp
in classEncodableHistogram
- Returns:
- the start time stamp [optionally] stored with this histogram
-
setStartTimeStamp
public void setStartTimeStamp(long timeStampMsec)
Set the start time stamp value associated with this histogram to a given value.- Specified by:
setStartTimeStamp
in classEncodableHistogram
- Parameters:
timeStampMsec
- the value to set the time stamp to, [by convention] in msec since the epoch.
-
getEndTimeStamp
public long getEndTimeStamp()
get the end time stamp [optionally] stored with this histogram- Specified by:
getEndTimeStamp
in classEncodableHistogram
- Returns:
- the end time stamp [optionally] stored with this histogram
-
setEndTimeStamp
public void setEndTimeStamp(long timeStampMsec)
Set the end time stamp value associated with this histogram to a given value.- Specified by:
setEndTimeStamp
in classEncodableHistogram
- Parameters:
timeStampMsec
- the value to set the time stamp to, [by convention] in msec since the epoch.
-
getTag
public java.lang.String getTag()
get the tag string [optionally] associated with this histogram- Specified by:
getTag
in classEncodableHistogram
- Returns:
- tag string [optionally] associated with this histogram
-
setTag
public void setTag(java.lang.String tag)
Set the tag string associated with this histogram- Specified by:
setTag
in classEncodableHistogram
- Parameters:
tag
- the tag string to assciate with this histogram
-
getMinValue
public double getMinValue()
Get the lowest recorded value level in the histogram- Returns:
- the Min value recorded in the histogram
-
getMaxValue
public double getMaxValue()
Get the highest recorded value level in the histogram- Returns:
- the Max value recorded in the histogram
-
getMinNonZeroValue
public double getMinNonZeroValue()
Get the lowest recorded non-zero value level in the histogram- Returns:
- the lowest recorded non-zero value level in the histogram
-
getMaxValueAsDouble
public double getMaxValueAsDouble()
Get the highest recorded value level in the histogram as a double- Specified by:
getMaxValueAsDouble
in classEncodableHistogram
- Returns:
- the highest recorded value level in the histogram as a double
-
getMean
public double getMean()
Get the computed mean value of all recorded values in the histogram- Returns:
- the mean value (in value units) of the histogram data
-
getStdDeviation
public double getStdDeviation()
Get the computed standard deviation of all recorded values in the histogram- Returns:
- the standard deviation (in value units) of the histogram data
-
getValueAtPercentile
public double getValueAtPercentile(double percentile)
Get the value at a given percentile. When the percentile is > 0.0, the value returned is the value that the given the given percentage of the overall recorded value entries in the histogram are either smaller than or equivalent to. When the percentile is 0.0, the value returned is the value that all value entries in the histogram are either larger than or equivalent to.Note that two values are "equivalent" in this statement if
valuesAreEquivalent(double, double)
would return true.- Parameters:
percentile
- The percentile for which to return the associated value- Returns:
- The value that the given percentage of the overall recorded value entries in the histogram are either smaller than or equivalent to. When the percentile is 0.0, returns the value that all value entries in the histogram are either larger than or equivalent to.
-
getPercentileAtOrBelowValue
public double getPercentileAtOrBelowValue(double value)
Get the percentile at a given value. The percentile returned is the percentile of values recorded in the histogram that are smaller than or equivalent to the given value.Note that two values are "equivalent" in this statement if
valuesAreEquivalent(double, double)
would return true.- Parameters:
value
- The value for which to return the associated percentile- Returns:
- The percentile of values recorded in the histogram that are smaller than or equivalent to the given value.
-
getCountBetweenValues
public double getCountBetweenValues(double lowValue, double highValue) throws java.lang.ArrayIndexOutOfBoundsException
Get the count of recorded values within a range of value levels (inclusive to within the histogram's resolution).- Parameters:
lowValue
- The lower value bound on the range for which to provide the recorded count. Will be rounded down withlowestEquivalentValue
.highValue
- The higher value bound on the range for which to provide the recorded count. Will be rounded up withhighestEquivalentValue
.- Returns:
- the total count of values recorded in the histogram within the value range that is >= lowestEquivalentValue(lowValue) and <= highestEquivalentValue(highValue)
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-
getCountAtValue
public long getCountAtValue(double value) throws java.lang.ArrayIndexOutOfBoundsException
Get the count of recorded values at a specific value (to within the histogram resolution at the value level).- Parameters:
value
- The value for which to provide the recorded count- Returns:
- The total count of values recorded in the histogram within the value range that is >= lowestEquivalentValue(value) and <= highestEquivalentValue(value)
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-
percentiles
public DoubleHistogram.Percentiles percentiles(int percentileTicksPerHalfDistance)
Provide a means of iterating through histogram values according to percentile levels. The iteration is performed in steps that start at 0% and reduce their distance to 100% according to the percentileTicksPerHalfDistance parameter, ultimately reaching 100% when all recorded histogram values are exhausted.- Parameters:
percentileTicksPerHalfDistance
- The number of iteration steps per half-distance to 100%.- Returns:
- An
Iterable
<DoubleHistogramIterationValue
> through the histogram using aDoublePercentileIterator
-
linearBucketValues
public DoubleHistogram.LinearBucketValues linearBucketValues(double valueUnitsPerBucket)
Provide a means of iterating through histogram values using linear steps. The iteration is performed in steps of valueUnitsPerBucket in size, terminating when all recorded histogram values are exhausted.- Parameters:
valueUnitsPerBucket
- The size (in value units) of the linear buckets to use- Returns:
- An
Iterable
<DoubleHistogramIterationValue
> through the histogram using aDoubleLinearIterator
-
logarithmicBucketValues
public DoubleHistogram.LogarithmicBucketValues logarithmicBucketValues(double valueUnitsInFirstBucket, double logBase)
Provide a means of iterating through histogram values at logarithmically increasing levels. The iteration is performed in steps that start at valueUnitsInFirstBucket and increase exponentially according to logBase, terminating when all recorded histogram values are exhausted.- Parameters:
valueUnitsInFirstBucket
- The size (in value units) of the first bucket in the iterationlogBase
- The multiplier by which bucket sizes will grow in each iteration step- Returns:
- An
Iterable
<DoubleHistogramIterationValue
> through the histogram using aDoubleLogarithmicIterator
-
recordedValues
public DoubleHistogram.RecordedValues recordedValues()
Provide a means of iterating through all recorded histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all non-zero recorded value counts, and terminates when all recorded histogram values are exhausted.- Returns:
- An
Iterable
<DoubleHistogramIterationValue
> through the histogram using aDoubleRecordedValuesIterator
-
allValues
public DoubleHistogram.AllValues allValues()
Provide a means of iterating through all histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all possible unit value levels, regardless of whether or not there were recorded values for that value level, and terminates when all recorded histogram values are exhausted.- Returns:
- An
Iterable
<DoubleHistogramIterationValue
> through the histogram using aDoubleAllValuesIterator
-
outputPercentileDistribution
public void outputPercentileDistribution(java.io.PrintStream printStream, java.lang.Double outputValueUnitScalingRatio)
Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing five (5) percentile reporting tick points.- Parameters:
printStream
- Stream into which the distribution will be outputoutputValueUnitScalingRatio
- The scaling factor by which to divide histogram recorded values units in output
-
outputPercentileDistribution
public void outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio)
Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing dumpTicksPerHalf percentile reporting tick points.- Parameters:
printStream
- Stream into which the distribution will be outputpercentileTicksPerHalfDistance
- The number of reporting points per exponentially decreasing half-distanceoutputValueUnitScalingRatio
- The scaling factor by which to divide histogram recorded values units in output
-
outputPercentileDistribution
public void outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio, boolean useCsvFormat)
Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing dumpTicksPerHalf percentile reporting tick points.- Parameters:
printStream
- Stream into which the distribution will be outputpercentileTicksPerHalfDistance
- The number of reporting points per exponentially decreasing half-distanceoutputValueUnitScalingRatio
- The scaling factor by which to divide histogram recorded values units in outputuseCsvFormat
- Output in CSV format if true. Otherwise use plain text form.
-
writeObject
private void writeObject(java.io.ObjectOutputStream o) throws java.io.IOException
- Throws:
java.io.IOException
-
readObject
private void readObject(java.io.ObjectInputStream o) throws java.io.IOException, java.lang.ClassNotFoundException
- Throws:
java.io.IOException
java.lang.ClassNotFoundException
-
getNeededByteBufferCapacity
public int getNeededByteBufferCapacity()
Get the capacity needed to encode this histogram into a ByteBuffer- Specified by:
getNeededByteBufferCapacity
in classEncodableHistogram
- Returns:
- the capacity needed to encode this histogram into a ByteBuffer
-
getNeededByteBufferCapacity
private int getNeededByteBufferCapacity(int relevantLength)
-
isDoubleHistogramCookie
static boolean isDoubleHistogramCookie(int cookie)
-
isCompressedDoubleHistogramCookie
static boolean isCompressedDoubleHistogramCookie(int cookie)
-
isNonCompressedDoubleHistogramCookie
static boolean isNonCompressedDoubleHistogramCookie(int cookie)
-
encodeIntoByteBuffer
public int encodeIntoByteBuffer(java.nio.ByteBuffer buffer)
Encode this histogram into a ByteBuffer- Parameters:
buffer
- The buffer to encode into- Returns:
- The number of bytes written to the buffer
-
encodeIntoCompressedByteBuffer
public int encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer, int compressionLevel)
Encode this histogram in compressed form into a byte array- Specified by:
encodeIntoCompressedByteBuffer
in classEncodableHistogram
- Parameters:
targetBuffer
- The buffer to encode intocompressionLevel
- Compression level (for java.util.zip.Deflater).- Returns:
- The number of bytes written to the buffer
-
encodeIntoCompressedByteBuffer
public int encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer)
Encode this histogram in compressed form into a byte array- Parameters:
targetBuffer
- The buffer to encode into- Returns:
- The number of bytes written to the array
-
constructHistogramFromBuffer
static <T extends DoubleHistogram> T constructHistogramFromBuffer(int cookie, java.nio.ByteBuffer buffer, java.lang.Class<T> doubleHistogramClass, java.lang.Class<? extends AbstractHistogram> histogramClass, long minBarForHighestToLowestValueRatio) throws java.util.zip.DataFormatException
- Throws:
java.util.zip.DataFormatException
-
decodeFromByteBuffer
public static DoubleHistogram decodeFromByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestToLowestValueRatio)
Construct a new DoubleHistogram by decoding it from a ByteBuffer.- Parameters:
buffer
- The buffer to decode fromminBarForHighestToLowestValueRatio
- Force highestTrackableValue to be set at least this high- Returns:
- The newly constructed DoubleHistogram
-
decodeFromByteBuffer
public static DoubleHistogram decodeFromByteBuffer(java.nio.ByteBuffer buffer, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, long minBarForHighestToLowestValueRatio)
Construct a new DoubleHistogram by decoding it from a ByteBuffer, using a specified AbstractHistogram subclass for tracking internal counts (e.g.Histogram
,ConcurrentHistogram
,SynchronizedHistogram
,IntCountsHistogram
,ShortCountsHistogram
).- Parameters:
buffer
- The buffer to decode frominternalCountsHistogramClass
- The class to use for internal counts trackingminBarForHighestToLowestValueRatio
- Force highestTrackableValue to be set at least this high- Returns:
- The newly constructed DoubleHistogram
-
decodeFromCompressedByteBuffer
public static DoubleHistogram decodeFromCompressedByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestToLowestValueRatio) throws java.util.zip.DataFormatException
Construct a new DoubleHistogram by decoding it from a compressed form in a ByteBuffer.- Parameters:
buffer
- The buffer to decode fromminBarForHighestToLowestValueRatio
- Force highestTrackableValue to be set at least this high- Returns:
- The newly constructed DoubleHistogram
- Throws:
java.util.zip.DataFormatException
- on error parsing/decompressing the buffer
-
decodeFromCompressedByteBuffer
public static DoubleHistogram decodeFromCompressedByteBuffer(java.nio.ByteBuffer buffer, java.lang.Class<? extends AbstractHistogram> internalCountsHistogramClass, long minBarForHighestToLowestValueRatio) throws java.util.zip.DataFormatException
Construct a new DoubleHistogram by decoding it from a compressed form in a ByteBuffer, using a specified AbstractHistogram subclass for tracking internal counts (e.g.Histogram
,AtomicHistogram
,SynchronizedHistogram
,IntCountsHistogram
,ShortCountsHistogram
).- Parameters:
buffer
- The buffer to decode frominternalCountsHistogramClass
- The class to use for internal counts trackingminBarForHighestToLowestValueRatio
- Force highestTrackableValue to be set at least this high- Returns:
- The newly constructed DoubleHistogram
- Throws:
java.util.zip.DataFormatException
- on error parsing/decompressing the buffer
-
fromString
public static DoubleHistogram fromString(java.lang.String base64CompressedHistogramString) throws java.util.zip.DataFormatException
Construct a new DoubleHistogram by decoding it from a String containing a base64 encoded compressed histogram representation.- Parameters:
base64CompressedHistogramString
- A string containing a base64 encoding of a compressed histogram- Returns:
- A DoubleHistogram decoded from the string
- Throws:
java.util.zip.DataFormatException
- on error parsing/decompressing the input
-
deriveInternalHighestToLowestValueRatio
private long deriveInternalHighestToLowestValueRatio(long externalHighestToLowestValueRatio)
-
deriveIntegerValueRange
private long deriveIntegerValueRange(long externalHighestToLowestValueRatio, int numberOfSignificantValueDigits)
-
getLowestTrackingIntegerValue
private long getLowestTrackingIntegerValue()
-
findContainingBinaryOrderOfMagnitude
private static int findContainingBinaryOrderOfMagnitude(long longNumber)
-
findContainingBinaryOrderOfMagnitude
private static int findContainingBinaryOrderOfMagnitude(double doubleNumber)
-
findCappedContainingBinaryOrderOfMagnitude
private int findCappedContainingBinaryOrderOfMagnitude(double doubleNumber)
-
-