Package io.prometheus.client

Class Gauge

  • All Implemented Interfaces:
    Collector.Describable
    public class Gauge
extends SimpleCollector<Gauge.Child>
implements Collector.Describable
    Gauge metric, to report instantaneous values.

    Examples of Gauges include:

    • Inprogress requests
    • Number of items in a queue
    • Free memory
    • Total memory
    • Temperature
    Gauges can go both up and down.

    An example Gauge: 

     
   class YourClass {
     static final Gauge inprogressRequests = Gauge.build()
         .name("inprogress_requests").help("Inprogress requests.").register();

     void processRequest() {
        inprogressRequests.inc();
        // Your code here.
        inprogressRequests.dec();
     }
   }

    You can also use labels to track different types of metric: 

     
   class YourClass {
     static final Gauge inprogressRequests = Gauge.build()
         .name("inprogress_requests").help("Inprogress requests.")
         .labelNames("method").register();

     void processGetRequest() {
        inprogressRequests.labels("get").inc();
        // Your code here.
        inprogressRequests.labels("get").dec();
     }
     void processPostRequest() {
        inprogressRequests.labels("post").inc();
        // Your code here.
        inprogressRequests.labels("post").dec();
     }
   }

    These can be aggregated and processed together much more easily in the Prometheus server than individual metrics for each labelset.

    • Method Detail

      • build

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

      • build

        public static Gauge.Builder build()
        Return a Builder to allow configuration of a new Gauge.

      • inc

        public void inc()
        Increment the gauge with no labels by 1.

      • inc

        public void inc​(double amt)
        Increment the gauge with no labels by the given amount.

      • dec

        public void dec()
        Decrement the gauge with no labels by 1.

      • dec

        public void dec​(double amt)
        Decrement the gauge with no labels by the given amount.

      • set

        public void set​(double val)
        Set the gauge with no labels to the given value.

      • setToCurrentTime

        public void setToCurrentTime()
        Set the gauge with no labels to the current unixtime.

      • startTimer

        public Gauge.Timer startTimer()
        Start a timer to track a duration, for the gauge with no labels.

        This is primarily useful for tracking the durations of major steps of batch jobs, which are then pushed to a PushGateway. For tracking other durations/latencies you should usually use a Summary.

        Call Gauge.Timer.setDuration() at the end of what you want to measure the duration of.

      • setToTime

        public double setToTime​(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.

      • setToTime

        public <E> E setToTime​(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 double get()
        Get the value of the gauge.

      • 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