Class Summary

All Implemented Interfaces:
Collector.Describable

public class Summary extends SimpleCollector<Summary.Child> implements Collector.Describable
Summary metric, to track the size of events.

Example of uses for Summaries include:

  • Response latency
  • Request size

Example Summaries:

 
   class YourClass {
     static final Summary receivedBytes = Summary.build()
         .name("requests_size_bytes").help("Request size in bytes.").register();
     static final Summary requestLatency = Summary.build()
         .name("requests_latency_seconds").help("Request latency in seconds.").register();

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

     // Or if using Java 8 and lambdas.
     void processRequestLambda(Request req) {
       receivedBytes.observe(req.size());
       requestLatency.time(() -> {
         // Your code here.
       });
     }
 }
 
 
This would allow you to track request rate, average latency and average request size.

How to add custom quantiles:

 
     static final Summary myMetric = Summary.build()
             .quantile(0.5, 0.05)   // Add 50th percentile (= median) with 5% tolerated error
             .quantile(0.9, 0.01)   // Add 90th percentile with 1% tolerated error
             .quantile(0.99, 0.001) // Add 99th percentile with 0.1% tolerated error
             .name("requests_size_bytes")
             .help("Request size in bytes.")
             .register();
 
 
The quantiles are calculated over a sliding window of time. There are two options to configure this time window:
  • maxAgeSeconds(long): Set the duration of the time window is, i.e. how long observations are kept before they are discarded. Default is 10 minutes.
  • ageBuckets(int): Set the number of buckets used to implement the sliding time window. If your time window is 10 minutes, and you have ageBuckets=5, buckets will be switched every 2 minutes. The value is a trade-off between resources (memory and cpu for maintaining the bucket) and how smooth the time window is moved. Default value is 5.
See https://prometheus.io/docs/practices/histograms/ for more info on quantiles.
  • Field Details

    • quantiles

      final List<CKMSQuantiles.Quantile> quantiles
    • maxAgeSeconds

      final long maxAgeSeconds
    • ageBuckets

      final int ageBuckets
  • Constructor Details

  • Method Details

    • build

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

      public static Summary.Builder build()
      Return a Builder to allow configuration of a new Summary.
    • newChild

      protected Summary.Child newChild()
      Description copied from class: SimpleCollector
      Return a new child, workaround for Java generics limitations.
      Specified by:
      newChild in class SimpleCollector<Summary.Child>
    • observe

      public void observe(double amt)
      Observe the given amount on the summary with no labels.
    • startTimer

      public Summary.Timer startTimer()
      Start a timer to track a duration on the summary with no labels.

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

    • time

      public double time(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.
    • time

      public <E> E time(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.
    • get

      public Summary.Child.Value get()
      Get the value of the Summary.

      Warning: The definition of Summary.Child.Value is subject to change.

    • collect

      Description copied from class: Collector
      Return all of the metrics of this Collector.
      Specified by:
      collect in class Collector
    • describe

      public 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