Class Histogram

  • All Implemented Interfaces:
    Collector.Describable

    public class Histogram
    extends SimpleCollector<Histogram.Child>
    implements Collector.Describable
    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();
            }
         }
    
         // Or if using Java 8 lambdas.
         void processRequestLambda(Request req) {
            requestLatency.time(() -> {
              // Your code here.
            });
         }
       }
     
     

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

      • buckets

        private final double[] buckets
      • exemplarsEnabled

        private final java.lang.Boolean exemplarsEnabled
    • Method Detail

      • build

        public static Histogram.Builder build​(java.lang.String name,
                                              java.lang.String help)
        Return a Builder to allow configuration of a new Histogram. Ensures required fields are provided.
        Parameters:
        name - The name of the metric
        help - The help string of the metric
      • build

        public static Histogram.Builder build()
        Return a Builder to allow configuration of a new Histogram.
      • time

        public double time​(java.lang.Runnable timeable)
        Executes runnable code (e.g. a Java 8 Lambda) and observes a duration of how long it took to run.
        Parameters:
        timeable - Code that is being timed
        Returns:
        Measured duration in seconds for timeable to complete.
      • timeWithExemplar

        public double timeWithExemplar​(java.lang.Runnable timeable,
                                       java.util.Map<java.lang.String,​java.lang.String> exemplarLabels)
        Like time(Runnable), but additionally create an exemplar.

        See Histogram.Child.observeWithExemplar(double, Map) for documentation on the exemplarLabels parameter.

      • time

        public <E> E time​(java.util.concurrent.Callable<E> timeable)
        Executes callable code (e.g. a Java 8 Lambda) and observes a duration of how long it took to run.
        Parameters:
        timeable - Code that is being timed
        Returns:
        Result returned by callable.
      • timeWithExemplar

        public <E> E timeWithExemplar​(java.util.concurrent.Callable<E> timeable,
                                      java.util.Map<java.lang.String,​java.lang.String> exemplarLabels)
        Like time(Callable), but additionally create an exemplar.

        See Histogram.Child.observeWithExemplar(double, Map) for documentation on the exemplarLabels parameter.

      • describe

        public java.util.List<Collector.MetricFamilySamples> describe()
        Description copied from interface: Collector.Describable
        Provide a list of metric families this Collector is expected to return. These should exclude the samples. This is used by the registry to detect collisions and duplicate registrations. Usually custom collectors do not have to implement Describable. If Describable is not implemented and the CollectorRegistry was created with auto describe enabled (which is the case for the default registry) then Collector.collect() will be called at registration time instead of describe. If this could cause problems, either implement a proper describe, or if that's not practical have describe return an empty list.
        Specified by:
        describe in interface Collector.Describable
      • getBuckets

        double[] getBuckets()