Package io.prometheus.client
Class Gauge
- java.lang.Object
-
- io.prometheus.client.Collector
-
- io.prometheus.client.SimpleCollector<Gauge.Child>
-
- io.prometheus.client.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
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
Gauge.Builder
static class
Gauge.Child
The value of a single Gauge.static class
Gauge.Timer
Represents an event being timed.-
Nested classes/interfaces inherited from class io.prometheus.client.Collector
Collector.Describable, Collector.MetricFamilySamples, 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Gauge.Builder
build()
Return a Builder to allow configuration of a new Gauge.static Gauge.Builder
build(String name, String help)
Return a Builder to allow configuration of a new Gauge.List<Collector.MetricFamilySamples>
collect()
Return all metrics of this Collector.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<Collector.MetricFamilySamples>
describe()
Provide a list of metric families this Collector is expected to return.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
newChild()
Return a new child, workaround for Java generics limitations.void
set(double val)
Set the gauge with no labels to the given value.void
setToCurrentTime()
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.Gauge.Timer
startTimer()
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
-
-
-
-
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 metrichelp
- 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()
Description copied from class:SimpleCollector
Return a new child, workaround for Java generics limitations.- Specified by:
newChild
in classSimpleCollector<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
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<Collector.MetricFamilySamples> collect()
Description copied from class:Collector
Return all metrics of this 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) thenCollector.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 interfaceCollector.Describable
-
-