Package io.prometheus.metrics.core.metrics

Class Histogram

Object
Metric
MetricWithFixedMetadata
Histogram
All Implemented Interfaces:
DataPoint, DistributionDataPoint, TimerApi, Collector
public class Histogram extends MetricWithFixedMetadata implements DistributionDataPoint
Histogram metric. Example usage: 

 Histogram histogram = Histogram.builder()
         .name("http_request_duration_seconds")
         .help("HTTP request service time in seconds")
         .unit(SECONDS)
         .labelNames("method", "path", "status_code")
         .register();

 long start = System.nanoTime();
 // do something
 histogram.labelValues("GET", "/", "200").observe(Unit.nanosToSeconds(System.nanoTime() - start));
Prometheus supports two internal representations of histograms:
  1. Classic Histograms have a fixed number of buckets with fixed bucket boundaries.
  2. Native Histograms have an infinite number of buckets with a dynamic resolution. Prometheus native histograms are the same as OpenTelemetry's exponential histograms.
By default, a histogram maintains both representations, i.e. the example above will maintain a classic histogram representation with Prometheus' default bucket boundaries as well as native histogram representation. Which representation is used depends on the exposition format, i.e. which content type the Prometheus server accepts when scraping. Exposition format "Text" exposes the classic histogram, exposition format "Protobuf" exposes both representations. This is great for migrating from classic histograms to native histograms.

If you want the classic representation only, use Histogram.Builder.classicOnly. If you want the native representation only, use Histogram.Builder.nativeOnly.

  • Method Details

    • observe

      public void observe(double amount)
      Observe value.
      Specified by:
      observe in interface DistributionDataPoint

    • observeWithExemplar

      public void observeWithExemplar(double amount, Labels labels)
      Observe value, and create a custom exemplar with the given labels.
      Specified by:
      observeWithExemplar in interface DistributionDataPoint

    • collect

      public HistogramSnapshot collect()
      Called when the Prometheus server scrapes metrics.
      Specified by:
      collect in interface Collector

    • builder

      public static Histogram.Builder builder()

    • builder

      public static Histogram.Builder builder(PrometheusProperties config)

    • initLabelValues

      public void initLabelValues(String... labelValues)
      Initialize label values.

      Example: Imagine you have a counter for payments as follows 

       payment_transactions_total{payment_type="credit card"} 7.0
 payment_transactions_total{payment_type="paypal"} 3.0
      Now, the data points for the payment_type label values get initialized when they are first used, i.e. the first time you call 
      
 counter.labelValues("paypal").inc();
      the data point with label payment_type="paypal" will go from non-existent to having value 1.0.

      In some cases this is confusing, and you want to have data points initialized on application start with an initial value of 0.0: 

       payment_transactions_total{payment_type="credit card"} 0.0
 payment_transactions_total{payment_type="paypal"} 0.0
      initLabelValues(...) can be used to initialize label value, so that the data points show up in the exposition format with an initial value of zero.

    • labelValues

      public DistributionDataPoint labelValues(String... labelValues)

    • remove

      public void remove(String... labelValues)
      Remove the data point with the given label values. See https://prometheus.io/docs/instrumenting/writing_clientlibs/#labels.

    • clear

      public void clear()
      Reset the metric (remove all data points).