io.prometheus.client

Class Histogram

java.lang.Object

io.prometheus.client.Collector

io.prometheus.client.SimpleCollector<Histogram.Child,Histogram>

io.prometheus.client.Histogram

public class Histogram
extends SimpleCollector<Histogram.Child,Histogram>

Histogram metric, to track distributions of events.

Example of uses for Histograms include:

• Response latency
• Request size

Note: Each bucket is one timeseries. Many buckets and/or many dimensions with labels can produce large amount of time series, that may cause performance problems.

The default buckets are intended to cover a typical web/rpc request from milliseconds to seconds.

Example Histograms:

 class YourClass {
     static final Histogram requestLatency = Histogram.build()
         .name("requests_latency_seconds").help("Request latency in seconds.").register();

     void processRequest(Request req) {  
        Histogram.Timer requestTimer = requestLatency.startTimer();
        try {
          // Your code here.
        } finally {
          requestTimer.observeDuration();
        }
     }
   }
 
 

You can choose your own buckets:

 static final Histogram requestLatency = Histogram.build()
         .buckets(.01, .02, .03, .04)
         .name("requests_latency_seconds").help("Request latency in seconds.").register();
 
 

linearBuckets and exponentialBuckets offer easy ways to set common bucket patterns.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Histogram.Builder
static class	Histogram.Child The value of a single Histogram.
static class	Histogram.Timer Represents an event being timed.

Nested classes/interfaces inherited from class io.prometheus.client.Collector

Collector.MetricFamilySamples, Collector.Type

Field Summary

Fields inherited from class io.prometheus.client.SimpleCollector

children, fullname, help, labelNames, noLabelsChild

Fields inherited from class io.prometheus.client.Collector

METRIC_LABEL_NAME_RE, METRIC_NAME_RE, MILLISECONDS_PER_SECOND, NANOSECONDS_PER_SECOND, RESERVED_METRIC_LABEL_NAME_RE

Method Summary

Methods

Modifier and Type	Method and Description
static Histogram.Builder	build() Return a Builder to allow configuration of a new Histogram.
List<Collector.MetricFamilySamples>	collect() Return all of the metrics of this Collector.
protected Histogram.Child	newChild() Return a new child, workaround for Java generics limitations.
void	observe(double amt) Observe the given amount on the histogram with no labels.
Histogram.Timer	startTimer() Start a timer to track a duration on the histogram with no labels.

Methods inherited from class io.prometheus.client.SimpleCollector

clear, initializeNoLabelsChild, labels, remove, setChild

Methods inherited from class io.prometheus.client.Collector

checkMetricLabelName, checkMetricName, doubleToGoString, register, register

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

build

public static Histogram.Builder build()

Return a Builder to allow configuration of a new Histogram.

newChild

protected Histogram.Child newChild()

Description copied from class: SimpleCollector

Return a new child, workaround for Java generics limitations.

Specified by:

newChild in class SimpleCollector<Histogram.Child,Histogram>

observe

public void observe(double amt)

Observe the given amount on the histogram with no labels.

startTimer

public Histogram.Timer startTimer()

Start a timer to track a duration on the histogram with no labels.

Call Histogram.Timer.observeDuration() at the end of what you want to measure the duration of.

collect

public List<Collector.MetricFamilySamples> collect()

Description copied from class: Collector

Return all of the metrics of this Collector.

Specified by:

collect in class Collector