Package io.prometheus.client
Class Summary
- java.lang.Object
-
- io.prometheus.client.Collector
-
- io.prometheus.client.SimpleCollector<Summary.Child>
-
- io.prometheus.client.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. }); } }
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();
- 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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Summary.Builder
static class
Summary.Child
The value of a single Summary.static class
Summary.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 Modifier and Type Field Description (package private) int
ageBuckets
(package private) long
maxAgeSeconds
(package private) java.util.List<CKMSQuantiles.Quantile>
quantiles
-
Fields inherited from class io.prometheus.client.SimpleCollector
children, fullname, help, labelNames, noLabelsChild
-
Fields inherited from class io.prometheus.client.Collector
MILLISECONDS_PER_SECOND, NANOSECONDS_PER_SECOND
-
-
Constructor Summary
Constructors Constructor Description Summary(Summary.Builder b)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Summary.Builder
build()
Return a Builder to allow configuration of a new Summary.static Summary.Builder
build(java.lang.String name, java.lang.String help)
Return a Builder to allow configuration of a new Summary.java.util.List<Collector.MetricFamilySamples>
collect()
Return all of the metrics of this Collector.java.util.List<Collector.MetricFamilySamples>
describe()
Provide a list of metric families this Collector is expected to return.Summary.Child.Value
get()
Get the value of the Summary.protected Summary.Child
newChild()
Return a new child, workaround for Java generics limitations.void
observe(double amt)
Observe the given amount on the summary with no labels.Summary.Timer
startTimer()
Start a timer to track a duration on the summary with no labels.double
time(java.lang.Runnable timeable)
Executes runnable code (e.g.<E> E
time(java.util.concurrent.Callable<E> timeable)
Executes callable code (e.g.-
Methods inherited from class io.prometheus.client.SimpleCollector
clear, familySamplesList, initializeNoLabelsChild, labels, remove, setChild
-
Methods inherited from class io.prometheus.client.Collector
checkMetricLabelName, checkMetricName, doubleToGoString, register, register, sanitizeMetricName
-
-
-
-
Field Detail
-
quantiles
final java.util.List<CKMSQuantiles.Quantile> quantiles
-
maxAgeSeconds
final long maxAgeSeconds
-
ageBuckets
final int ageBuckets
-
-
Constructor Detail
-
Summary
Summary(Summary.Builder b)
-
-
Method Detail
-
build
public static Summary.Builder build(java.lang.String name, java.lang.String help)
Return a Builder to allow configuration of a new Summary. Ensures required fields are provided.- Parameters:
name
- The name of the metrichelp
- 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 classSimpleCollector<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(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.
-
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.
-
get
public Summary.Child.Value get()
Get the value of the Summary.Warning: The definition of
Summary.Child.Value
is subject to change.
-
collect
public java.util.List<Collector.MetricFamilySamples> collect()
Description copied from class:Collector
Return all of the metrics of this Collector.
-
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) 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
-
-