Module io.prometheus.metrics.core

Package io.prometheus.metrics.core.metrics

Class StatefulMetric<D extends DataPoint,T extends D>

java.lang.Object

io.prometheus.metrics.core.metrics.Metric

io.prometheus.metrics.core.metrics.MetricWithFixedMetadata

io.prometheus.metrics.core.metrics.StatefulMetric<D,T>

All Implemented Interfaces:

io.prometheus.metrics.model.registry.Collector

Direct Known Subclasses:

Counter, Gauge, Histogram, StateSet, Summary

public abstract class StatefulMetric<D extends DataPoint,T extends D>
extends MetricWithFixedMetadata

There are two kinds of metrics:

• A StatefulMetric actively maintains its current values, e.g. a stateful counter actively stores its current count.
• A CallbackMetric gets its values on demand when it is collected, e.g. a callback gauge representing the current heap size.

The OpenTelemetry terminology for stateful is synchronous and the OpenTelemetry terminology for callback is asynchronous. We are using our own terminology here because in Java synchronous and asynchronous usually refers to multi-threading, but this has nothing to do with multi-threading.

Field Summary

Fields inherited from class io.prometheus.metrics.core.metrics.MetricWithFixedMetadata

labelNames

Fields inherited from class io.prometheus.metrics.core.metrics.Metric

constLabels

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	StatefulMetric(io.prometheus.metrics.core.metrics.StatefulMetric.Builder<?,?> builder)

Method Summary

Modifier and Type	Method	Description
void	clear()	Reset the metric (remove all data points).
io.prometheus.metrics.model.snapshots.MetricSnapshot	collect()
protected abstract io.prometheus.metrics.model.snapshots.MetricSnapshot	collect(List<io.prometheus.metrics.model.snapshots.Labels> labels, List<T> metricData)	labels and metricData have the same size. labels.get(i) are the labels for metricData.get(i).
protected <P> P	getConfigProperty(io.prometheus.metrics.config.MetricsProperties[] properties, Function<io.prometheus.metrics.config.MetricsProperties,P> getter)
protected io.prometheus.metrics.config.MetricsProperties[]	getMetricProperties(io.prometheus.metrics.core.metrics.StatefulMetric.Builder<?,?> builder, io.prometheus.metrics.config.PrometheusProperties prometheusProperties)	Metric properties in effect by order of precedence with the highest precedence first.
protected T	getNoLabels()
void	initLabelValues(String... labelValues)	Initialize label values.
D	labelValues(String... labelValues)
protected abstract T	newDataPoint()
void	remove(String... labelValues)	Remove the data point with the given label values.
void	removeIf(Function<List<String>,Boolean> f)	Remove the data points when the given function.

Methods inherited from class io.prometheus.metrics.core.metrics.MetricWithFixedMetadata

getMetadata, getPrometheusName

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.prometheus.metrics.model.registry.Collector

collect, collect, collect

Constructor Details

StatefulMetric

protected StatefulMetric(io.prometheus.metrics.core.metrics.StatefulMetric.Builder<?,?> builder)

Method Details

collect

protected abstract io.prometheus.metrics.model.snapshots.MetricSnapshot collect(List<io.prometheus.metrics.model.snapshots.Labels> labels,
 List<T> metricData)

labels and metricData have the same size. labels.get(i) are the labels for metricData.get(i).

collect

public io.prometheus.metrics.model.snapshots.MetricSnapshot collect()

Specified by:

collect in interface io.prometheus.metrics.model.registry.Collector

Specified by:

collect in class Metric

initLabelValues

public void initLabelValues(String... labelValues)

Initialize label values.

Example: Imagine you have a counter for payments as follows

 payment_transactions_total{payment_type="credit card"} 7.0
 payment_transactions_total{payment_type="paypal"} 3.0
 

Now, the data points for the payment_type label values get initialized when they are first used, i.e. the first time you call

 counter.labelValues("paypal").inc();
 

the data point with label payment_type="paypal" will go from non-existent to having value 1.0.

In some cases this is confusing, and you want to have data points initialized on application start with an initial value of 0.0:

 payment_transactions_total{payment_type="credit card"} 0.0
 payment_transactions_total{payment_type="paypal"} 0.0
 

initLabelValues(...) can be used to initialize label value, so that the data points show up in the exposition format with an initial value of zero.

labelValues

public D labelValues(String... labelValues)

remove

public void remove(String... labelValues)

Remove the data point with the given label values. See https://prometheus.io/docs/instrumenting/writing_clientlibs/#labels.

removeIf

public void removeIf(Function<List<String>,Boolean> f)

Remove the data points when the given function.

clear

public void clear()

Reset the metric (remove all data points).

newDataPoint

protected abstract T newDataPoint()

getNoLabels

protected T getNoLabels()

getMetricProperties

protected io.prometheus.metrics.config.MetricsProperties[] getMetricProperties(io.prometheus.metrics.core.metrics.StatefulMetric.Builder<?,?> builder,
 io.prometheus.metrics.config.PrometheusProperties prometheusProperties)

Metric properties in effect by order of precedence with the highest precedence first. If a MetricProperties is configured for the metric name it has higher precedence than the builder configuration. A special case is the setting StatefulMetric.Builder.withoutExemplars() via the builder, which cannot be overridden by any configuration.

getConfigProperty

protected <P> P getConfigProperty(io.prometheus.metrics.config.MetricsProperties[] properties,
 Function<io.prometheus.metrics.config.MetricsProperties,P> getter)