Package io.prometheus.metrics.core.metrics

Class Histogram.Builder

java.lang.Object
io.prometheus.metrics.core.metrics.Metric.Builder<B,M>
io.prometheus.metrics.core.metrics.MetricWithFixedMetadata.Builder<B,M>
io.prometheus.metrics.core.metrics.Histogram.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>

    • toProperties

      protected io.prometheus.metrics.config.MetricsProperties toProperties()
      Override if there are more properties than just exemplars enabled.

    • getDefaultProperties

      public io.prometheus.metrics.config.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.

    • withClassicBuckets

      public Histogram.Builder withClassicBuckets(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.

    • withClassicLinearBuckets

      public Histogram.Builder withClassicLinearBuckets(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

    • withClassicExponentialBuckets

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

      Example: withClassicExponentialBuckets(1.0, 2.0, 10) creates bucket bounaries [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

    • withNativeInitialSchema

      public Histogram.Builder withNativeInitialSchema(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 withNativeMaxNumberOfBuckets(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%

    • withNativeMaxZeroThreshold

      public Histogram.Builder withNativeMaxZeroThreshold(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.

    • withNativeMinZeroThreshold

      public Histogram.Builder withNativeMinZeroThreshold(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.

    • withNativeMaxNumberOfBuckets

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

      If the number of native buckets exceeds the maximum, the withNativeInitialSchema(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.

    • withNativeResetDuration

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

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

      Default is no reset.

    • self

      protected Histogram.Builder self()
      Specified by:
      self in class MetricWithFixedMetadata.Builder<Histogram.Builder,Histogram>

    • withExemplars

      public Histogram.Builder withExemplars()

    • withoutExemplars

      public Histogram.Builder withoutExemplars()