DecayingEstimatedHistogramReservoir (apache-cassandra API)
Date: 2018-02-14

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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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()

Copyright © 2018 The Apache Software Foundation