Package io.prometheus.client

Class Histogram.Child

java.lang.Object

io.prometheus.client.Histogram.Child

Enclosing class:

Histogram

public static class Histogram.Child
extends Object

The value of a single Histogram.

Warning: References to a Child become invalid after using SimpleCollector.remove(java.lang.String...) or SimpleCollector.clear().

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Histogram.Child.Value

Field Summary

Fields

Modifier and Type	Field	Description
private final long	created
private final DoubleAdder[]	cumulativeCounts
private final ArrayList<AtomicReference<Exemplar>>	exemplars
private final HistogramExemplarSampler	exemplarSampler
private final Boolean	exemplarsEnabled
private final DoubleAdder	sum
private final double[]	upperBounds

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Child(double[] buckets, Boolean exemplarsEnabled, HistogramExemplarSampler exemplarSampler)

Method Summary

Modifier and Type	Method	Description
Histogram.Child.Value	get()	Get the value of the Histogram.
void	observe(double amt)	Observe the given amount.
void	observeWithExemplar(double amt, String... exemplarLabels)	Like observe(double), but additionally creates an exemplar.
void	observeWithExemplar(double amt, Map<String,String> exemplarLabels)	Like observeWithExemplar(double, String...), but the exemplar labels are passed as a Map.
private Exemplar	sampleNextExemplar(double amt, double bucketFrom, double bucketTo, Exemplar prev)
Histogram.Timer	startTimer()	Start a timer to track a duration.
double	time(Runnable timeable)	Executes runnable code (e.g.
<E> E	time(Callable<E> timeable)	Executes callable code (e.g.
double	timeWithExemplar(Runnable timeable, String... exemplarLabels)	Like time(Runnable), but additionally create an exemplar.
double	timeWithExemplar(Runnable timeable, Map<String,String> exemplarLabels)	Like time(Runnable), but additionally create an exemplar.
<E> E	timeWithExemplar(Callable<E> timeable, String... exemplarLabels)	Like time(Callable), but additionally create an exemplar.
<E> E	timeWithExemplar(Callable<E> timeable, Map<String,String> exemplarLabels)	Like time(Callable), but additionally create an exemplar.
private void	updateExemplar(double amt, int i, Exemplar userProvidedExemplar)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

exemplars

private final ArrayList<AtomicReference<Exemplar>> exemplars

exemplarsEnabled

private final Boolean exemplarsEnabled

exemplarSampler

private final HistogramExemplarSampler exemplarSampler

upperBounds

private final double[] upperBounds

cumulativeCounts

private final DoubleAdder[] cumulativeCounts

sum

private final DoubleAdder sum

created

private final long created

Constructor Details

Child

private Child(double[] buckets,
 Boolean exemplarsEnabled,
 HistogramExemplarSampler exemplarSampler)

Method Details

time

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

timeWithExemplar

public double timeWithExemplar(Runnable timeable,
 String... exemplarLabels)

Like time(Runnable), but additionally create an exemplar.

See observeWithExemplar(double, String...) for documentation on the exemplarLabels parameter.

timeWithExemplar

public double timeWithExemplar(Runnable timeable,
 Map<String,String> exemplarLabels)

Like time(Runnable), but additionally create an exemplar.

See observeWithExemplar(double, Map) for documentation on the exemplarLabels parameter.

time

public <E> E time(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.

timeWithExemplar

public <E> E timeWithExemplar(Callable<E> timeable,
 String... exemplarLabels)

Like time(Callable), but additionally create an exemplar.

See observeWithExemplar(double, String...) for documentation on the exemplarLabels parameter.

timeWithExemplar

public <E> E timeWithExemplar(Callable<E> timeable,
 Map<String,String> exemplarLabels)

Like time(Callable), but additionally create an exemplar.

See observeWithExemplar(double, Map) for documentation on the exemplarLabels parameter.

observe

public void observe(double amt)

Observe the given amount.

Parameters:

amt - in most cases amt should be >= 0. Negative values are supported, but you should read https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations for implications and alternatives.

observeWithExemplar

public void observeWithExemplar(double amt,
 String... exemplarLabels)

Like observe(double), but additionally creates an exemplar.

This exemplar takes precedence over any exemplar returned by the HistogramExemplarSampler configured in ExemplarConfig.

The exemplar will have amt as the value, System.currentTimeMillis() as the timestamp, and the specified labels.

Parameters:

amt - same as in observe(double) (double)}

exemplarLabels - list of name/value pairs, as documented in Exemplar(double, String...). A commonly used name is "trace_id". Calling observeWithExemplar(amt) means that an exemplar without labels is created. Calling observeWithExemplar(amt, (String[]) null) is equivalent to calling observe(amt).

observeWithExemplar

public void observeWithExemplar(double amt,
 Map<String,String> exemplarLabels)

Like observeWithExemplar(double, String...), but the exemplar labels are passed as a Map.

updateExemplar

private void updateExemplar(double amt,
 int i,
 Exemplar userProvidedExemplar)

sampleNextExemplar

private Exemplar sampleNextExemplar(double amt,
 double bucketFrom,
 double bucketTo,
 Exemplar prev)

startTimer

public Histogram.Timer startTimer()

Start a timer to track a duration.

Call Histogram.Timer.observeDuration() at the end of what you want to measure the duration of.

get

public Histogram.Child.Value get()

Get the value of the Histogram.

Warning: The definition of Histogram.Child.Value is subject to change.