Module io.prometheus.metrics.core
Package io.prometheus.metrics.core.metrics

Class Histogram.Builder

java.lang.Object
io.prometheus.metrics.core.metrics.Metric.Builder<Histogram.Builder,Histogram>
io.prometheus.metrics.core.metrics.MetricWithFixedMetadata.Builder<Histogram.Builder,Histogram>
io.prometheus.metrics.core.metrics.Histogram.Builder
Enclosing class:
Histogram
public static class Histogram.Builder extends MetricWithFixedMetadata.Builder<Histogram.Builder,Histogram>

  • Field Details

    • DEFAULT_CLASSIC_UPPER_BOUNDS

      public static final double[] DEFAULT_CLASSIC_UPPER_BOUNDS

    • exemplarsEnabled

      @Nullable protected Boolean exemplarsEnabled

    • exemplarLabelsSupplier

      @Nullable protected Supplier<io.prometheus.metrics.model.snapshots.Labels> exemplarLabelsSupplier

  • 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.

    • 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: classicLinearUpperBounds(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: classicExponentialUpperBounds(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.

    • self

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

    • exemplarLabelsSupplier

      public Histogram.Builder exemplarLabelsSupplier(Supplier<io.prometheus.metrics.model.snapshots.Labels> supplier)
      Provide additional labels to be merged into every automatically-sampled exemplar of this metric. The supplier is called each time an exemplar is sampled, so it can return dynamic values (e.g. a request-scoped identifier from a thread-local). The supplier is only invoked when a valid, sampled span context is present; it has no effect when tracing is not active.

      For a global supplier that applies to all metrics (including metrics registered by third-party libraries you do not control), see ExemplarLabelsSupplier. When both are configured, this per-metric supplier takes precedence over the global one on a label-name collision, and the reserved trace_id/span_id labels always win over both. Labels that collide are silently dropped.

    • withExemplars

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

    • withoutExemplars

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