com.github.rollingmetrics.histogram.hdr

Class RollingHdrHistogramBuilder

java.lang.Object

com.github.rollingmetrics.histogram.hdr.RollingHdrHistogramBuilder

public class RollingHdrHistogramBuilder
extends Object

The builder for creation and registration histograms, timers and reservoirs.

Basic examples of usage:

         RollingHdrHistogramBuilder builder = RollingHdrHistogramBuilder();

         // build and register timer
         Timer timer1 = builder.buildAndRegisterTimer(registry, "my-timer-1");

         // build and register timer in another way
         Timer timer2 = builder.buildTimer();
         registry.register(timer2, "my-timer-2");

         // build and register histogram
         Histogram histogram1 = builder.buildAndRegisterHistogram(registry, "my-histogram-1");

         // build and register histogram in another way
         Histogram histogram2 = builder.buildHistogram();
         registry.register(histogram2, "my-histogram-2");
     
 

In order to be sure that Reservoir with provided settings does not consume too much memory you can use getEstimatedFootprintInBytes() method which returns conservatively high estimation of the Reservoir's total footprint in bytes:

         RollingHdrHistogramBuilder builder = new RollingHdrHistogramBuilder().withSignificantDigits(3);
         System.out.println(builder.getEstimatedFootprintInBytes());
 
 

See Also:

Histogram

Constructor Summary

Constructors

Constructor and Description
RollingHdrHistogramBuilder(Ticker ticker)

Method Summary

Modifier and Type	Method and Description
RollingHdrHistogram	build() TODO
RollingHdrHistogramBuilder	deepCopy() Creates full copy of this builder.
int	getEstimatedFootprintInBytes() Provide a (conservatively high) estimate of the Reservoir's total footprint in bytes
RollingHdrHistogramBuilder	neverResetReservoir() Reservoir configured with this strategy will store all values since the reservoir was created.
RollingHdrHistogramBuilder	resetReservoirOnSnapshot() Reservoir configured with this strategy will be cleared each time when snapshot taken.
RollingHdrHistogramBuilder	resetReservoirPeriodically(Duration resettingPeriod) Reservoir configured with this strategy will be cleared fully after each resettingPeriod.
RollingHdrHistogramBuilder	resetReservoirPeriodicallyByChunks(Duration rollingTimeWindow, int numberChunks) Reservoir configured with this strategy will be divided to numberChunks parts, and one chunk will be cleared after each rollingTimeWindow / numberChunks elapsed.
String	toString()
RollingHdrHistogramBuilder	withBackgroundExecutor(Executor backgroundExecutor) Configures the executor which will be used if any of resetReservoirPeriodically(Duration) or resetReservoirPeriodicallyByChunks(Duration, int) (Duration)}.
RollingHdrHistogramBuilder	withExpectedIntervalBetweenValueSamples(long expectedIntervalBetweenValueSamples) When this setting is configured then it will be used 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.
RollingHdrHistogramBuilder	withHighestTrackableValue(long highestTrackableValue, OverflowResolver overflowResolver) Configures the highest value to be tracked by the histogram.
RollingHdrHistogramBuilder	withLowestDiscernibleValue(long lowestDiscernibleValue) Configures the lowest value that can be discerned.
RollingHdrHistogramBuilder	withoutSnapshotOptimization() Discards snapshot memory footprint optimization.
RollingHdrHistogramBuilder	withPredefinedPercentiles(double[] predefinedPercentiles) Configures list of percentiles which you plan to store in monitoring database.
RollingHdrHistogramBuilder	withSignificantDigits(int numberOfSignificantValueDigits) Configures the number of significant decimal digits to which the histogram will maintain value resolution and separation.
RollingHdrHistogramBuilder	withSnapshotCachingDuration(Duration duration) Configures the period for which taken snapshot will be cached.
RollingHdrHistogramBuilder	withTicker(Ticker ticker) TODO

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RollingHdrHistogramBuilder

public RollingHdrHistogramBuilder(Ticker ticker)

Method Detail

resetReservoirOnSnapshot

public RollingHdrHistogramBuilder resetReservoirOnSnapshot()

Reservoir configured with this strategy will be cleared each time when snapshot taken.

Returns:

this builder instance

See Also:

resetReservoirPeriodically(Duration), resetReservoirPeriodicallyByChunks(Duration, int), neverResetReservoir()

resetReservoirPeriodically

public RollingHdrHistogramBuilder resetReservoirPeriodically(Duration resettingPeriod)

Reservoir configured with this strategy will be cleared fully after each resettingPeriod.

The value recorded to reservoir will take affect at most resettingPeriod time.

If You use this strategy inside JEE environment, then it would be better to call ResilientExecutionUtil.getInstance().shutdownBackgroundExecutor() once in application shutdown listener, in order to avoid leaking reference to classloader through the thread which this library creates for histogram rotation in background.

Parameters:

resettingPeriod - specifies how often need to reset reservoir

Returns:

this builder instance

See Also:

neverResetReservoir(), resetReservoirOnSnapshot(), resetReservoirPeriodicallyByChunks(Duration, int)

resetReservoirPeriodicallyByChunks

public RollingHdrHistogramBuilder resetReservoirPeriodicallyByChunks(Duration rollingTimeWindow,
                                                                     int numberChunks)

Reservoir configured with this strategy will be divided to numberChunks parts, and one chunk will be cleared after each rollingTimeWindow / numberChunks elapsed. This strategy is more smoothly then resetReservoirPeriodically because reservoir never zeroed at whole, so user experience provided by resetReservoirPeriodicallyByChunks should look more pretty.

The value recorded to reservoir will take affect at least rollingTimeWindow and at most rollingTimeWindow *(1 + 1/numberChunks) time, for example when you configure rollingTimeWindow=60 seconds and numberChunks=6 then each value recorded to reservoir will be stored at 60-70 seconds

If You use this strategy inside JEE environment, then it would be better to call ResilientExecutionUtil.getInstance().shutdownBackgroundExecutor() once in application shutdown listener, in order to avoid leaking reference to classloader through the thread which this library creates for histogram rotation in background.

Parameters:

rollingTimeWindow - the total rolling time window, any value recorded to reservoir will not be evicted from it at least rollingTimeWindow

numberChunks - specifies number of chunks by which reservoir will be slitted

Returns:

this builder instance

See Also:

neverResetReservoir(), resetReservoirOnSnapshot(), resetReservoirPeriodically(Duration)

neverResetReservoir

public RollingHdrHistogramBuilder neverResetReservoir()

Reservoir configured with this strategy will store all values since the reservoir was created.

This is default strategy for RollingHdrHistogramBuilder

Returns:

this builder instance

See Also:

resetReservoirPeriodically(Duration), resetReservoirOnSnapshot(), resetReservoirPeriodicallyByChunks(Duration, int)

withSignificantDigits

public RollingHdrHistogramBuilder withSignificantDigits(int numberOfSignificantValueDigits)

Configures the number of significant decimal digits to which the histogram will maintain value resolution and separation.

Pay attention that numberOfSignificantValueDigits is major setting which affects the memory footprint, higher value will lead to higher memory consumption, use getEstimatedFootprintInBytes() to be sure that Reservoir with provided settings does not consume too much memory.

If numberOfSignificantValueDigits is not configured then default value 2 will be applied.

Parameters:

numberOfSignificantValueDigits - The number of significant decimal digits. Must be a non-negative integer between 0 and 5.

Returns:

this builder instance

See Also:

AbstractHistogram.AbstractHistogram(int)

withLowestDiscernibleValue

public RollingHdrHistogramBuilder withLowestDiscernibleValue(long lowestDiscernibleValue)

Configures the lowest value that can be discerned. 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.

If you configured lowestDiscernibleValue then highestTrackableValue must be configured via withHighestTrackableValue(long, OverflowResolver) otherwise IllegalStateException will be thrown during reservoir construction.

There is no default value for lowestDiscernibleValue, when it is not specified then it will not be applied.

Parameters:

lowestDiscernibleValue - The lowest value that can be discerned (distinguished from 0) by the histogram. Must be a positive integer that is >= 1. May be internally rounded down to nearest power of 2.

Returns:

this builder instance

See Also:

AbstractHistogram.AbstractHistogram(long, long, int)

withHighestTrackableValue

public RollingHdrHistogramBuilder withHighestTrackableValue(long highestTrackableValue,
                                                            OverflowResolver overflowResolver)

Configures the highest value to be tracked by the histogram.

Parameters:

highestTrackableValue - highest value to be tracked by the histogram. Must be a positive integer that is >= (2 * lowestDiscernibleValue)

overflowResolver - specifies behavior which should be applied when writing to reservoir value which greater than highestTrackableValue

Returns:

this builder instance

withExpectedIntervalBetweenValueSamples

public RollingHdrHistogramBuilder withExpectedIntervalBetweenValueSamples(long expectedIntervalBetweenValueSamples)

When this setting is configured then it will be used 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.

WARNING: You should not use this method for monitoring your application in the production, its designed to be used inside benchmarks and load testing. See related notes AbstractHistogram.recordValueWithExpectedInterval(long, long) for more explanations about coordinated omission and expected interval correction.

Parameters:

expectedIntervalBetweenValueSamples - If expectedIntervalBetweenValueSamples is larger than 0, then each time on value writing, reservoir will add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples

Returns:

this builder instance

See Also:

AbstractHistogram.recordValueWithExpectedInterval(long, long)

withSnapshotCachingDuration

public RollingHdrHistogramBuilder withSnapshotCachingDuration(Duration duration)

Configures the period for which taken snapshot will be cached.

Parameters:

duration - the period for which taken snapshot will be cached, should be a positive duration.

Returns:

this builder instance

withPredefinedPercentiles

public RollingHdrHistogramBuilder withPredefinedPercentiles(double[] predefinedPercentiles)

Configures list of percentiles which you plan to store in monitoring database.

This method is useful when you already know list of percentiles which need to be stored in monitoring database, then you can specify it to optimize snapshot size, as result unnecessary garbage will be avoided, memory in snapshot will allocated only for percentiles which you configure.

Moreover by default builder already configured with default list of percentiles DEFAULT_PERCENTILES. the default percentiles are double[] {0.5, 0.75, 0.9, 0.95, 0.98, 0.99, 0.999}

Parameters:

predefinedPercentiles - list of percentiles which you plan to store in monitoring database, should be not empty array of doubles between 0..1

Returns:

this builder instance

See Also:

withoutSnapshotOptimization()

withoutSnapshotOptimization

public RollingHdrHistogramBuilder withoutSnapshotOptimization()

Discards snapshot memory footprint optimization. Use this method when you do not know concrete percentiles which you need. Pay attention that when you discard snapshot optimization then garbage required for take one snapshot will approximately equals to histogram size.

This method zeroes predefinedPercentiles configured by default DEFAULT_PERCENTILES or configured via withPredefinedPercentiles(double[]).

Returns:

this builder instance

withBackgroundExecutor

public RollingHdrHistogramBuilder withBackgroundExecutor(Executor backgroundExecutor)

Configures the executor which will be used if any of resetReservoirPeriodically(Duration) or resetReservoirPeriodicallyByChunks(Duration, int) (Duration)}.

Normally you should not use this method because of default executor provided by ResilientExecutionUtil.getBackgroundExecutor() is quietly enough for mostly use cases.

You can use this method for example inside JEE environments with enabled SecurityManager, in case of ResilientExecutionUtil.setThreadFactory(ThreadFactory) is not enough to meat security rules.

Returns:

this builder instance

withTicker

public RollingHdrHistogramBuilder withTicker(Ticker ticker)

TODO

Parameters:

ticker -

Returns:

build

public RollingHdrHistogram build()

TODO

Returns:

getEstimatedFootprintInBytes

public int getEstimatedFootprintInBytes()

Provide a (conservatively high) estimate of the Reservoir's total footprint in bytes

Returns:

a (conservatively high) estimate of the Reservoir's total footprint in bytes

deepCopy

public RollingHdrHistogramBuilder deepCopy()

Creates full copy of this builder.

Returns:

copy of this builder

toString

public String toString()

Overrides:

toString in class Object