Package io.prometheus.client
Class Histogram
- All Implemented Interfaces:
Collector.Describable
Histogram metric, to track distributions of events.
Example of uses for Histograms include:
- Response latency
- Request size
Note: Each bucket is one timeseries. Many buckets and/or many dimensions with labels can produce large amount of time series, that may cause performance problems.
The default buckets are intended to cover a typical web/rpc request from milliseconds to seconds.
Example Histograms:
class YourClass {
static final Histogram requestLatency = Histogram.build()
.name("requests_latency_seconds").help("Request latency in seconds.").register();
void processRequest(Request req) {
Histogram.Timer requestTimer = requestLatency.startTimer();
try {
// Your code here.
} finally {
requestTimer.observeDuration();
}
}
// Or if using Java 8 lambdas.
void processRequestLambda(Request req) {
requestLatency.time(() -> {
// Your code here.
});
}
}
You can choose your own buckets:
static final Histogram requestLatency = Histogram.build()
.buckets(.01, .02, .03, .04)
.name("requests_latency_seconds").help("Request latency in seconds.").register();
linearBuckets
and
exponentialBuckets
offer easy ways to set common bucket patterns.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
static class
The value of a single Histogram.static class
Represents an event being timed.Nested classes/interfaces inherited from class io.prometheus.client.Collector
Collector.Describable, Collector.MetricFamilySamples, Collector.Type
-
Field Summary
FieldsFields 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 -
Method Summary
Modifier and TypeMethodDescriptionstatic Histogram.Builder
build()
Return a Builder to allow configuration of a new Histogram.static Histogram.Builder
Return a Builder to allow configuration of a new Histogram.collect()
Return all of the metrics of this Collector.describe()
Provide a list of metric families this Collector is expected to return.(package private) double[]
protected Histogram.Child
newChild()
Return a new child, workaround for Java generics limitations.void
observe
(double amt) Observe the given amount on the histogram with no labels.Start a timer to track a duration on the histogram with no labels.double
Executes runnable code (e.g.<E> E
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 Details
-
buckets
private final double[] buckets
-
-
Constructor Details
-
Histogram
Histogram(Histogram.Builder b)
-
-
Method Details
-
build
Return a Builder to allow configuration of a new Histogram. Ensures required fields are provided.- Parameters:
name
- The name of the metrichelp
- The help string of the metric
-
build
Return a Builder to allow configuration of a new Histogram. -
newChild
Description copied from class:SimpleCollector
Return a new child, workaround for Java generics limitations.- Specified by:
newChild
in classSimpleCollector<Histogram.Child>
-
observe
public void observe(double amt) Observe the given amount on the histogram with no labels. -
startTimer
Start a timer to track a duration on the histogram with no labels.Call
Histogram.Timer.observeDuration()
at the end of what you want to measure the duration of. -
time
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
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.
-
collect
Description copied from class:Collector
Return all of the metrics of this Collector. -
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
-
getBuckets
double[] getBuckets()
-