Module org.elasticsearch.exponentialhistogram
Package org.elasticsearch.exponentialhistogram

Interface ExponentialHistogram

All Superinterfaces:
org.apache.lucene.util.Accountable
All Known Subinterfaces:
ReleasableExponentialHistogram
All Known Implementing Classes:
AbstractExponentialHistogram, CompressedExponentialHistogram
public interface ExponentialHistogram extends org.apache.lucene.util.Accountable
Interface for implementations of exponential histograms adhering to the OpenTelemetry definition. This interface supports sparse implementations, allowing iteration over buckets without requiring direct index access.
The most important properties are:
  • The histogram has a scale parameter, which defines the accuracy. A higher scale implies a higher accuracy. The base for the buckets is defined as base = 2^(2^-scale).
  • The histogram bucket at index i has the range (base^i, base^(i+1)]
  • Negative values are represented by a separate negative range of buckets with the boundaries (-base^(i+1), -base^i]
  • Histograms are perfectly subsetting: increasing the scale by one merges each pair of neighboring buckets
  • A special ZeroBucket is used to handle zero and close-to-zero values

Additionally, all algorithms assume that samples within a bucket are located at a single point: the point of least relative error (see ExponentialScaleUtils.getPointOfLeastRelativeError(long, int)).

  • Field Details

  • Method Details

    • scale

      int scale()
      The scale of the histogram. Higher scales result in higher accuracy but potentially more buckets. Must be less than or equal to MAX_SCALE and greater than or equal to MIN_SCALE.
      Returns:
      the scale of the histogram

    • zeroBucket

      ZeroBucket zeroBucket()
      Returns:
      the ZeroBucket representing the number of zero (or close-to-zero) values and its threshold

    • positiveBuckets

      ExponentialHistogram.Buckets positiveBuckets()
      Returns:
      a ExponentialHistogram.Buckets instance for the populated buckets covering the positive value range of this histogram. The BucketIterator.scale() of iterators obtained via ExponentialHistogram.Buckets.iterator() must be the same as scale().

    • negativeBuckets

      ExponentialHistogram.Buckets negativeBuckets()
      Returns:
      a ExponentialHistogram.Buckets instance for the populated buckets covering the negative value range of this histogram. The BucketIterator.scale() of iterators obtained via ExponentialHistogram.Buckets.iterator() must be the same as scale().

    • sum

      double sum()
      Returns the sum of all values represented by this histogram. Note that even if histograms are cumulative, the sum is not guaranteed to be monotonically increasing, because histograms support negative values.
      Returns:
      the sum, guaranteed to be zero for empty histograms

    • valueCount

      long valueCount()
      Returns the number of values represented by this histogram. In other words, this is the sum of the counts of all buckets including the zero bucket.
      Returns:
      the value count, guaranteed to be zero for empty histograms

    • min

      double min()
      Returns minimum of all values represented by this histogram.
      Returns:
      the minimum, NaN for empty histograms

    • max

      double max()
      Returns maximum of all values represented by this histogram.
      Returns:
      the maximum, NaN for empty histograms

    • equals

      static boolean equals(ExponentialHistogram a, ExponentialHistogram b)
      Value-based equality for exponential histograms.
      Parameters:
      a - the first histogram (can be null)
      b - the second histogram (can be null)
      Returns:
      true, if both histograms are equal

    • hashCode

      static int hashCode(ExponentialHistogram histogram)
      Default hash code implementation to be used with equals(ExponentialHistogram, ExponentialHistogram).
      Parameters:
      histogram - the histogram to hash
      Returns:
      the hash code

    • empty

      static ExponentialHistogram empty()

    • builder

      static ExponentialHistogramBuilder builder(int scale, ExponentialHistogramCircuitBreaker breaker)
      Create a builder for an exponential histogram with the given scale.
      Parameters:
      scale - the scale of the histogram to build
      breaker - the circuit breaker to use
      Returns:
      a new builder

    • builder

      static ExponentialHistogramBuilder builder(ExponentialHistogram toCopy, ExponentialHistogramCircuitBreaker breaker)
      Create a builder for an exponential histogram, which is initialized to copy the given histogram.
      Parameters:
      toCopy - the histogram to copy
      breaker - the circuit breaker to use
      Returns:
      a new builder

    • create

      static ReleasableExponentialHistogram create(int maxBucketCount, ExponentialHistogramCircuitBreaker breaker, double... values)
      Creates a histogram representing the distribution of the given values with at most the given number of buckets. If the given maxBucketCount is greater than or equal to the number of values, the resulting histogram will have a relative error of less than 2^(2^-MAX_SCALE) - 1.
      Parameters:
      maxBucketCount - the maximum number of buckets
      breaker - the circuit breaker to use to limit memory allocations
      values - the values to be added to the histogram
      Returns:
      a new ReleasableExponentialHistogram

    • merge

      static ReleasableExponentialHistogram merge(int maxBucketCount, ExponentialHistogramCircuitBreaker breaker, Iterator<? extends ExponentialHistogram> histograms)
      Merges the provided exponential histograms to a new, single histogram with at most the given amount of buckets.
      Parameters:
      maxBucketCount - the maximum number of buckets the result histogram is allowed to have
      breaker - the circuit breaker to use to limit memory allocations
      histograms - the histograms to merge
      Returns:
      the merged histogram

    • merge

      static ReleasableExponentialHistogram merge(int maxBucketCount, ExponentialHistogramCircuitBreaker breaker, ExponentialHistogram... histograms)
      Merges the provided exponential histograms to a new, single histogram with at most the given amount of buckets.
      Parameters:
      maxBucketCount - the maximum number of buckets the result histogram is allowed to have
      breaker - the circuit breaker to use to limit memory allocations
      histograms - the histograms to merge
      Returns:
      the merged histogram