java.lang.Object
io.prometheus.client.Collector
io.prometheus.client.SimpleCollector<Gauge.Child>
org.torproject.metrics.descriptorparser.utils.Gauge
All Implemented Interfaces:
io.prometheus.client.Collector.Describable

public class Gauge extends io.prometheus.client.SimpleCollector<Gauge.Child> implements io.prometheus.client.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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
     
    static class 
    The value of a single Gauge.
    static class 
    Represents an event being timed.

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

    io.prometheus.client.Collector.Describable, io.prometheus.client.Collector.MetricFamilySamples, io.prometheus.client.Collector.Type
  • Field Summary

    Fields inherited from class io.prometheus.client.SimpleCollector

    children, fullname, help, labelNames, noLabelsChild, unit

    Fields inherited from class io.prometheus.client.Collector

    MILLISECONDS_PER_SECOND, NANOSECONDS_PER_SECOND
  • Method Summary

    Modifier and Type
    Method
    Description
    Return a Builder to allow configuration of a new Gauge.
    build(String name, String help)
    Return a Builder to allow configuration of a new Gauge.
    List<io.prometheus.client.Collector.MetricFamilySamples>
     
    void
    dec()
    Decrement the gauge with no labels by 1.
    void
    dec(double amt)
    Decrement the gauge with no labels by the given amount.
    List<io.prometheus.client.Collector.MetricFamilySamples>
     
    double
    get()
    Get the value of the gauge.
    void
    inc()
    Increment the gauge with no labels by 1.
    void
    inc(double amt)
    Increment the gauge with no labels by the given amount.
    protected Gauge.Child
     
    void
    set(double val)
    Set the gauge with no labels to the given value.
    void
    Set the gauge with no labels to the current unixtime.
    double
    setToTime(Runnable timeable)
    Executes runnable code (e.g.
    <E> E
    setToTime(Callable<E> timeable)
    Executes callable code (e.g.
    Start a timer to track a duration, for the gauge with no labels.

    Methods inherited from class io.prometheus.client.SimpleCollector

    clear, familySamplesList, initializeNoLabelsChild, labels, remove, setChild

    Methods inherited from class io.prometheus.client.Collector

    checkMetricLabelName, checkMetricName, collect, doubleToGoString, register, register, sanitizeMetricName

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • 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.
    • newChild

      protected Gauge.Child newChild()
      Specified by:
      newChild in class io.prometheus.client.SimpleCollector<Gauge.Child>
    • 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

      invalid @link
      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.
    • collect

      public List<io.prometheus.client.Collector.MetricFamilySamples> collect()
      Specified by:
      collect in class io.prometheus.client.Collector
    • describe

      public List<io.prometheus.client.Collector.MetricFamilySamples> describe()
      Specified by:
      describe in interface io.prometheus.client.Collector.Describable