ValueRecorder
public class Recorder extends Object implements ValueRecorder
Histogram
samples from
live recorded data without interrupting or stalling active recording of values. Each interval
histogram provided contains all value counts accumulated since the previous interval histogram
was taken.
This pattern is commonly used in logging interval histogram information while recording is ongoing.
Recorder
supports concurrent
recordValue(long)
or
recordValueWithExpectedInterval(long, long)
calls.
Recording calls are waitfree on architectures that support atomic increment operations, and
are lockfree on architectures that do not.
A common pattern for using a Recorder
looks like this:
Recorder recorder = new Recorder(2); // Two decimal point accuracy
Histogram intervalHistogram = null;
...
[start of some loop construct that periodically wants to grab an interval histogram]
...
// Get interval histogram, recycling previous interval histogram:
intervalHistogram = recorder.getIntervalHistogram(intervalHistogram);
histogramLogWriter.outputIntervalHistogram(intervalHistogram);
...
[end of loop construct]
Constructor  Description 

Recorder(int numberOfSignificantValueDigits) 
Construct an autoresizing
Recorder with a lowest discernible value of
1 and an autoadjusting highestTrackableValue. 
Recorder(long highestTrackableValue,
int numberOfSignificantValueDigits) 
Construct a
Recorder given the highest value to be tracked and a number of significant
decimal digits. 
Recorder(long lowestDiscernibleValue,
long highestTrackableValue,
int numberOfSignificantValueDigits) 
Construct a
Recorder given the Lowest and highest values to be tracked and a number
of significant decimal digits. 
Modifier and Type  Method  Description 

Histogram 
getIntervalHistogram() 
Get a new instance of an interval histogram, which will include a stable, consistent view of all value
counts accumulated since the last interval histogram was taken.

Histogram 
getIntervalHistogram(Histogram histogramToRecycle) 
Get an interval histogram, which will include a stable, consistent view of all value counts
accumulated since the last interval histogram was taken.

Histogram 
getIntervalHistogram(Histogram histogramToRecycle,
boolean enforeContainingInstance) 
Get an interval histogram, which will include a stable, consistent view of all value counts
accumulated since the last interval histogram was taken.

void 
getIntervalHistogramInto(Histogram targetHistogram) 
Place a copy of the value counts accumulated since accumulated (since the last interval histogram
was taken) into
targetHistogram . 
void 
recordValue(long value) 
Record a value

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

void 
reset() 
Reset any value counts accumulated thus far.

public Recorder(int numberOfSignificantValueDigits)
Recorder
with a lowest discernible value of
1 and an autoadjusting highestTrackableValue. Can autoresize up to track values up to (Long.MAX_VALUE / 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 nonnegative integer between 0 and 5.public Recorder(long highestTrackableValue, int numberOfSignificantValueDigits)
Recorder
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.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 nonnegative integer between 0 and 5.public Recorder(long lowestDiscernibleValue, long highestTrackableValue, int numberOfSignificantValueDigits)
Recorder
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.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 nonnegative integer between 0 and 5.public void recordValue(long value) throws ArrayIndexOutOfBoundsException
recordValue
in interface ValueRecorder
value
 the value to recordArrayIndexOutOfBoundsException
 (may throw) if value is exceeds highestTrackableValuepublic void recordValueWithCount(long value, long count) throws ArrayIndexOutOfBoundsException
recordValueWithCount
in interface ValueRecorder
value
 The value to be recordedcount
 The number of occurrences of this value to recordArrayIndexOutOfBoundsException
 (may throw) if value is exceeds highestTrackableValuepublic 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 autogenerate an additional series of decreasinglysmaller (down to the expectedIntervalBetweenValueSamples) value records.
See related notes AbstractHistogram.recordValueWithExpectedInterval(long, long)
for more explanations about coordinated omission and expected interval correction.
*
recordValueWithExpectedInterval
in interface ValueRecorder
value
 The value to recordexpectedIntervalBetweenValueSamples
 If expectedIntervalBetweenValueSamples is larger than 0, add
autogenerated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamplesArrayIndexOutOfBoundsException
 (may throw) if value is exceeds highestTrackableValuepublic Histogram getIntervalHistogram()
Calling getIntervalHistogram()
will reset
the value counts, and start accumulating value counts for the next interval.
public Histogram getIntervalHistogram(Histogram histogramToRecycle)
getIntervalHistogram(histogramToRecycle)
accepts a previously returned interval histogram that can be recycled internally to avoid allocation
and content copying operations, and is therefore significantly more efficient for repeated use than
getIntervalHistogram()
and
getIntervalHistogramInto()
. The provided
histogramToRecycle
must
be either be null or an interval histogram returned by a previous call to
getIntervalHistogram(histogramToRecycle)
or
getIntervalHistogram()
.
NOTE: The caller is responsible for not recycling the same returned interval histogram more than once. If the same interval histogram instance is recycled more than once, behavior is undefined.
Calling getIntervalHistogram(histogramToRecycle)
will reset the value counts, and start accumulating value
counts for the next interval
histogramToRecycle
 a previously returned interval histogram (from this instance of
Recorder
) that may be recycled to avoid allocation and
copy operations.public Histogram getIntervalHistogram(Histogram histogramToRecycle, boolean enforeContainingInstance)
getIntervalHistogram(histogramToRecycle)
accepts a previously returned interval histogram that can be recycled internally to avoid allocation
and content copying operations, and is therefore significantly more efficient for repeated use than
getIntervalHistogram()
and
getIntervalHistogramInto()
. The provided
histogramToRecycle
must
be either be null or an interval histogram returned by a previous call to
getIntervalHistogram(histogramToRecycle)
or
getIntervalHistogram()
.
NOTE: The caller is responsible for not recycling the same returned interval histogram more than once. If the same interval histogram instance is recycled more than once, behavior is undefined.
Calling getIntervalHistogram(histogramToRecycle)
will reset the value counts, and start accumulating value
counts for the next interval
histogramToRecycle
 a previously returned interval histogram that may be recycled to avoid allocation and
copy operations.enforeContainingInstance
 if true, will only allow recycling of histograms previously returned from this
instance of Recorder
. If false, will allow recycling histograms
previously returned by other instances of Recorder
.public void getIntervalHistogramInto(Histogram targetHistogram)
targetHistogram
.
Calling getIntervalHistogramInto()
will reset
the value counts, and start accumulating value counts for the next interval.targetHistogram
 the histogram into which the interval histogram's data should be copiedpublic void reset()
reset
in interface ValueRecorder
Copyright © 2019. All rights reserved.