org.apache.cassandra.metrics

## Class DecayingEstimatedHistogramReservoir

- java.lang.Object
- - org.apache.cassandra.metrics.DecayingEstimatedHistogramReservoir

All Implemented Interfaces:
  com.codahale.metrics.Reservoir

    public class DecayingEstimatedHistogramReservoir
    extends java.lang.Object
    implements com.codahale.metrics.Reservoir

A decaying histogram reservoir where values collected during each minute will be twice as significant as the values collected in the previous minute. Measured values are collected in variable sized buckets, using small buckets in the lower range and larger buckets in the upper range. Use this histogram when you want to know if the distribution of the underlying data stream has changed recently and you want high resolution on values in the lower range. The histogram use forward decay [1] to make recent values more significant. The forward decay factor will be doubled every minute (half-life time set to 60 seconds) [2]. The forward decay landmark is reset every 30 minutes (or at first read/update after 30 minutes). During landmark reset, updates and reads in the reservoir will be blocked in a fashion similar to the one used in the metrics library [3]. The 30 minute rescale interval is used based on the assumption that in an extreme case we would have to collect a metric 1M times for a single bucket each second. By the end of the 30:th minute all collected values will roughly add up to 1.000.000 * 60 * pow(2, 30) which can be represented with 56 bits giving us some head room in a signed 64 bit long. Internally two reservoirs are maintained, one with decay and one without decay. All public getters in a will expose the decay functionality with the exception of the `Snapshot.getValues()` which will return values from the reservoir without decay. This makes it possible for the caller to maintain precise deltas in an interval of its choise. The bucket size starts at 1 and grows by 1.2 each time (rounding and removing duplicates). It goes from 1 to around 18T by default (creating 164+1 buckets), which will give a timing resolution from microseconds to roughly 210 days, with less precision as the numbers get larger. The series of values to which the counts in `decayingBuckets` correspond: 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 17, 20, 24, 29, 35, 42, 50, 60, 72 etc. Thus, a `decayingBuckets` of [0, 0, 1, 10] would mean we had seen 1 value of 3 and 10 values of 4. Each bucket represents values from (previous bucket offset, current offset]. [1]: http://dimacs.rutgers.edu/~graham/pubs/papers/fwddecay.pdf [2]: https://en.wikipedia.org/wiki/Half-life [3]: https://github.com/dropwizard/metrics/blob/v3.1.2/metrics-core/src/main/java/com/codahale/metrics/ExponentiallyDecayingReservoir.java

### Field Summary

Fields
`static int` `DEFAULT_BUCKET_COUNT` The default number of decayingBuckets.
`static long[]` `DEFAULT_WITH_ZERO_BUCKET_OFFSETS`
`static long[]` `DEFAULT_WITHOUT_ZERO_BUCKET_OFFSETS`
`static boolean` `DEFAULT_ZERO_CONSIDERATION`
`static long` `HALF_TIME_IN_S`
`static long` `LANDMARK_RESET_INTERVAL_IN_MS`
`static double` `MEAN_LIFETIME_IN_S`

### Constructor Summary

Constructors
Constructor and Description
`DecayingEstimatedHistogramReservoir()` Construct a decaying histogram with default number of buckets and without considering zeroes.
`DecayingEstimatedHistogramReservoir(boolean considerZeroes)` Construct a decaying histogram with default number of buckets.
`DecayingEstimatedHistogramReservoir(boolean considerZeroes, int bucketCount)` Construct a decaying histogram.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `clear()`
`com.codahale.metrics.Snapshot` `getSnapshot()` Returns a snapshot of the decaying values in this reservoir.
`int` `size()` Return the number of buckets where recorded values are stored.
`void` `update(long value)` Increments the count of the bucket closest to n, rounding UP.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### DEFAULT_BUCKET_COUNT

    public static final int DEFAULT_BUCKET_COUNT

The default number of decayingBuckets. Use this bucket count to reduce memory allocation for bucket offsets.

See Also:
  Constant Field Values

#### DEFAULT_ZERO_CONSIDERATION

    public static final boolean DEFAULT_ZERO_CONSIDERATION

See Also:
  Constant Field Values

#### DEFAULT_WITHOUT_ZERO_BUCKET_OFFSETS

    public static final long[] DEFAULT_WITHOUT_ZERO_BUCKET_OFFSETS

#### DEFAULT_WITH_ZERO_BUCKET_OFFSETS

    public static final long[] DEFAULT_WITH_ZERO_BUCKET_OFFSETS

#### HALF_TIME_IN_S

    public static final long HALF_TIME_IN_S

See Also:
  Constant Field Values

#### MEAN_LIFETIME_IN_S

    public static final double MEAN_LIFETIME_IN_S

#### LANDMARK_RESET_INTERVAL_IN_MS

    public static final long LANDMARK_RESET_INTERVAL_IN_MS

See Also:
  Constant Field Values

### Constructor Detail

#### DecayingEstimatedHistogramReservoir

    public DecayingEstimatedHistogramReservoir()

Construct a decaying histogram with default number of buckets and without considering zeroes.

#### DecayingEstimatedHistogramReservoir

    public DecayingEstimatedHistogramReservoir(boolean considerZeroes)

Construct a decaying histogram with default number of buckets.

Parameters:
  `considerZeroes` - when true, 0-value measurements in a separate bucket, otherwise they will be collected in same bucket as 1-value measurements

#### DecayingEstimatedHistogramReservoir

    public DecayingEstimatedHistogramReservoir(boolean considerZeroes,
                                               int bucketCount)

Construct a decaying histogram.

Parameters:
  `considerZeroes` - when true, 0-value measurements in a separate bucket, otherwise they will be collected in same bucket as 1-value measurements
  `bucketCount` - number of buckets used to collect measured values

### Method Detail

#### update

    public void update(long value)

Increments the count of the bucket closest to n, rounding UP.

Specified by:
  `update` in interface `com.codahale.metrics.Reservoir`
Parameters:
  `value` - the data point to add to the histogram

#### size

    public int size()

Return the number of buckets where recorded values are stored. This method does not return the number of recorded values as suggested by the `Reservoir` interface.

Specified by:
  `size` in interface `com.codahale.metrics.Reservoir`
Returns:
  the number of buckets

#### getSnapshot

    public com.codahale.metrics.Snapshot getSnapshot()

Returns a snapshot of the decaying values in this reservoir. Non-decaying reservoir will not be included in the snapshot.

Specified by:
  `getSnapshot` in interface `com.codahale.metrics.Reservoir`
Returns:
  the snapshot

#### clear

    public void clear()