Package io.prometheus.metrics.core.metrics

Class Histogram.Builder

Object
MetricWithFixedMetadata.Builder<B,M>
Builder
Enclosing class:
Histogram
public static class Histogram.Builder extends MetricWithFixedMetadata.Builder<B,M>

  • Field Details

  • Method Details

    • build

      public Histogram build()
      Specified by:
      build in class MetricWithFixedMetadata.Builder<Histogram.Builder,Histogram>

    • getDefaultProperties

      public MetricsProperties getDefaultProperties()
      Default properties for histogram metrics.

    • nativeOnly

      public Histogram.Builder nativeOnly()
      Use the native histogram representation only, i.e. don't maintain classic histogram buckets. See Histogram for more info.

    • classicOnly

      public Histogram.Builder classicOnly()
      Use the classic histogram representation only, i.e. don't maintain native histogram buckets. See Histogram for more info.

    • classicUpperBounds

      public Histogram.Builder classicUpperBounds(double... upperBounds)
      Set the upper bounds for the classic histogram buckets. Default is DEFAULT_CLASSIC_UPPER_BOUNDS. If the +Inf bucket is missing it will be added. If upperBounds contains duplicates the duplicates will be removed.

    • classicLinearUpperBounds

      public Histogram.Builder classicLinearUpperBounds(double start, double width, int count)
      Create classic histogram buckets with linear bucket boundaries.

      Example: withClassicLinearBuckets(1.0, 0.5, 10) creates bucket boundaries [[1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5].

      Parameters:
      start - is the first bucket boundary
      width - is the width of each bucket
      count - is the total number of buckets, including start

    • classicExponentialUpperBounds

      public Histogram.Builder classicExponentialUpperBounds(double start, double factor, int count)
      Create classic histogram buckets with exponential boundaries.

      Example: withClassicExponentialBuckets(1.0, 2.0, 10) creates bucket boundaries [1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0, 128.0, 256.0, 512.0]

      Parameters:
      start - is the first bucket boundary
      factor - growth factor
      count - total number of buckets, including start

    • nativeInitialSchema

      public Histogram.Builder nativeInitialSchema(int nativeSchema)
      The schema is a number in [-4, 8] defining the resolution of the native histogram. Default is DEFAULT_NATIVE_INITIAL_SCHEMA.

      The higher the schema, the finer the resolution. Schema is Prometheus terminology. In OpenTelemetry it's called "scale".

      Note that the schema for a histogram may be automatically decreased at runtime if the number of native histogram buckets exceeds nativeMaxNumberOfBuckets(int).

      The following table shows:

      • factor: The growth factor for bucket boundaries, i.e. next bucket boundary = growth factor * previous bucket boundary.
      • max quantile error: The maximum error for quantiles calculated using the Prometheus histogram_quantile() function, relative to the observed value, assuming harmonic mean.
      max quantile errors for different growth factors
      schemafactormax quantile error
      -465.53699%
      -325699%
      -21688%
      -1460%
      0233%
      11.4142...17%
      21.1892...9%
      31.1090...4%
      41.0442...2%
      51.0218...1%
      61.0108...0.5%
      71.0054...0.3%
      81.0027...0.1%

    • nativeMaxZeroThreshold

      public Histogram.Builder nativeMaxZeroThreshold(double nativeMaxZeroThreshold)
      Native histogram buckets get smaller and smaller the closer they get to zero. To avoid wasting a lot of buckets for observations fluctuating around zero, we consider all values in [-zeroThreshold, +zeroThreshold] to be equal to zero.

      The zeroThreshold is initialized with minZeroThreshold, and will grow up to maxZeroThreshold if the number of native histogram buckets exceeds nativeMaxBuckets.

      Default is DEFAULT_NATIVE_MAX_NUMBER_OF_BUCKETS.

    • nativeMinZeroThreshold

      public Histogram.Builder nativeMinZeroThreshold(double nativeMinZeroThreshold)
      Native histogram buckets get smaller and smaller the closer they get to zero. To avoid wasting a lot of buckets for observations fluctuating around zero, we consider all values in [-zeroThreshold, +zeroThreshold] to be equal to zero.

      The zeroThreshold is initialized with minZeroThreshold, and will grow up to maxZeroThreshold if the number of native histogram buckets exceeds nativeMaxBuckets.

      Default is DEFAULT_NATIVE_MIN_ZERO_THRESHOLD.

    • nativeMaxNumberOfBuckets

      public Histogram.Builder nativeMaxNumberOfBuckets(int nativeMaxBuckets)
      Limit the number of native buckets.

      If the number of native buckets exceeds the maximum, the nativeInitialSchema(int) is decreased, i.e. the resolution of the histogram is decreased to reduce the number of buckets.

      Default is DEFAULT_NATIVE_MAX_NUMBER_OF_BUCKETS.

    • nativeResetDuration

      public Histogram.Builder nativeResetDuration(long duration, TimeUnit unit)
      If the histogram needed to be scaled down because nativeMaxNumberOfBuckets(int) was exceeded, reset the histogram after a certain time interval to go back to the original nativeInitialSchema(int).

      Reset means all values are set to zero. A good value might be 24h or 7d.

      Default is no reset.

    • withExemplars

      public Histogram.Builder withExemplars()
      Allow Exemplars for this metric.

    • withoutExemplars

      public Histogram.Builder withoutExemplars()
      Turn off Exemplars for this metric.