io.micrometer.core.instrument

Class MeterRegistry

java.lang.Object

io.micrometer.core.instrument.MeterRegistry

Direct Known Subclasses:

CompositeMeterRegistry, DropwizardMeterRegistry, PushMeterRegistry, SimpleMeterRegistry

public abstract class MeterRegistry
extends java.lang.Object

Creates and manages your application's set of meters. Exporters use the meter registry to iterate over the set of meters instrumenting your application, and then further iterate over each meter's metrics, generally resulting in a time series in the metrics backend for each combination of metrics and dimensions.

MeterRegistry may be used in a reactive context. As such, implementations must not negatively impact the calling thread, e.g. it should respond immediately by avoiding IO call, deep stack recursion or any coordination.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	MeterRegistry.Config Access to configuration options for this registry.
class	MeterRegistry.More Additional, less commonly used meter types.

Field Summary

Fields

Modifier and Type	Field and Description
protected Clock	clock

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MeterRegistry(Clock clock)

Method Summary

Modifier and Type	Method and Description
void	close() Closes this registry, releasing any resources in the process.
MeterRegistry.Config	config()
Counter	counter(java.lang.String name, java.lang.Iterable<Tag> tags) Tracks a monotonically increasing value.
Counter	counter(java.lang.String name, java.lang.String... tags) Tracks a monotonically increasing value.
protected abstract DistributionStatisticConfig	defaultHistogramConfig() Every custom registry implementation should define a default histogram expiry at a minimum:
Search	find(java.lang.String name) Initiate a search beginning with a metric name.
void	forEachMeter(java.util.function.Consumer<? super Meter> consumer) Iterate over each meter in the registry.
<T extends java.lang.Number> T	gauge(java.lang.String name, java.lang.Iterable<Tag> tags, T number) Register a gauge that reports the value of the Number.
<T> T	gauge(java.lang.String name, java.lang.Iterable<Tag> tags, T obj, java.util.function.ToDoubleFunction<T> valueFunction) Register a gauge that reports the value of the object after the function valueFunction is applied.
<T extends java.lang.Number> T	gauge(java.lang.String name, T number) Register a gauge that reports the value of the Number.
<T> T	gauge(java.lang.String name, T obj, java.util.function.ToDoubleFunction<T> valueFunction) Register a gauge that reports the value of the object.
<T extends java.util.Collection<?>> T	gaugeCollectionSize(java.lang.String name, java.lang.Iterable<Tag> tags, T collection) Register a gauge that reports the size of the Collection.
<T extends java.util.Map<?,?>> T	gaugeMapSize(java.lang.String name, java.lang.Iterable<Tag> tags, T map) Register a gauge that reports the size of the Map.
RequiredSearch	get(java.lang.String name) Initiate a search beginning with a metric name.
protected abstract java.util.concurrent.TimeUnit	getBaseTimeUnit()
protected java.lang.String	getConventionName(Meter.Id id)
protected java.util.List<Tag>	getConventionTags(Meter.Id id)
java.util.List<Meter>	getMeters()
boolean	isClosed() If the registry is closed, it will no longer accept new meters and any publishing activity will cease.
MeterRegistry.More	more() Access to less frequently used meter types and patterns.
protected abstract Counter	newCounter(Meter.Id id) Build a new counter to be added to the registry.
protected abstract DistributionSummary	newDistributionSummary(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig, double scale) Build a new distribution summary to be added to the registry.
protected abstract <T> FunctionCounter	newFunctionCounter(Meter.Id id, T obj, java.util.function.ToDoubleFunction<T> countFunction) Build a new function counter to be added to the registry.
protected abstract <T> FunctionTimer	newFunctionTimer(Meter.Id id, T obj, java.util.function.ToLongFunction<T> countFunction, java.util.function.ToDoubleFunction<T> totalTimeFunction, java.util.concurrent.TimeUnit totalTimeFunctionUnit) Build a new function timer to be added to the registry.
protected abstract <T> Gauge	newGauge(Meter.Id id, T obj, java.util.function.ToDoubleFunction<T> valueFunction) Build a new gauge to be added to the registry.
protected abstract LongTaskTimer	newLongTaskTimer(Meter.Id id) Build a new long task timer to be added to the registry.
protected abstract Meter	newMeter(Meter.Id id, Meter.Type type, java.lang.Iterable<Measurement> measurements) Build a new custom meter to be added to the registry.
protected <T> TimeGauge	newTimeGauge(Meter.Id id, T obj, java.util.concurrent.TimeUnit valueFunctionUnit, java.util.function.ToDoubleFunction<T> valueFunction) Build a new time gauge to be added to the registry.
protected abstract Timer	newTimer(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig, PauseDetector pauseDetector) Build a new timer to be added to the registry.
Meter	remove(Meter.Id id)
Meter	remove(Meter meter)
DistributionSummary	summary(java.lang.String name, java.lang.Iterable<Tag> tags) Measures the distribution of samples.
DistributionSummary	summary(java.lang.String name, java.lang.String... tags) Measures the distribution of samples.
Timer	timer(java.lang.String name, java.lang.Iterable<Tag> tags) Measures the time taken for short tasks and the count of these tasks.
Timer	timer(java.lang.String name, java.lang.String... tags) Measures the time taken for short tasks and the count of these tasks.

Methods inherited from class java.lang.Object

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

Field Detail

clock

protected final Clock clock

Constructor Detail

MeterRegistry

protected MeterRegistry(Clock clock)

Method Detail

newGauge

protected abstract <T> Gauge newGauge(Meter.Id id,
                                      @Nullable
                                      T obj,
                                      java.util.function.ToDoubleFunction<T> valueFunction)

Build a new gauge to be added to the registry. This is guaranteed to only be called if the gauge doesn't already exist.

Type Parameters:

T - The type of the state object from which the gauge value is extracted.

Parameters:

id - The id that uniquely identifies the gauge.

obj - State object used to compute a value.

valueFunction - Function that is applied on the value for the number.

Returns:

A new gauge.

newCounter

protected abstract Counter newCounter(Meter.Id id)

Build a new counter to be added to the registry. This is guaranteed to only be called if the counter doesn't already exist.

Parameters:

id - The id that uniquely identifies the counter.

Returns:

A new counter.

newLongTaskTimer

protected abstract LongTaskTimer newLongTaskTimer(Meter.Id id)

Build a new long task timer to be added to the registry. This is guaranteed to only be called if the long task timer doesn't already exist.

Parameters:

id - The id that uniquely identifies the long task timer.

Returns:

A new long task timer.

newTimer

protected abstract Timer newTimer(Meter.Id id,
                                  DistributionStatisticConfig distributionStatisticConfig,
                                  PauseDetector pauseDetector)

Build a new timer to be added to the registry. This is guaranteed to only be called if the timer doesn't already exist.

Parameters:

id - The id that uniquely identifies the timer.

distributionStatisticConfig - Configuration for published distribution statistics.

pauseDetector - The pause detector to use for coordinated omission compensation.

Returns:

A new timer.

newDistributionSummary

protected abstract DistributionSummary newDistributionSummary(Meter.Id id,
                                                              DistributionStatisticConfig distributionStatisticConfig,
                                                              double scale)

Build a new distribution summary to be added to the registry. This is guaranteed to only be called if the distribution summary doesn't already exist.

Parameters:

id - The id that uniquely identifies the distribution summary.

distributionStatisticConfig - Configuration for published distribution statistics.

scale - Multiply every recorded sample by this factor.

Returns:

A new distribution summary.

newMeter

protected abstract Meter newMeter(Meter.Id id,
                                  Meter.Type type,
                                  java.lang.Iterable<Measurement> measurements)

Build a new custom meter to be added to the registry. This is guaranteed to only be called if the custom meter doesn't already exist.

Parameters:

id - The id that uniquely identifies the custom meter.

type - What kind of meter this is.

measurements - A set of measurements describing how to sample this meter.

Returns:

A new custom meter.

newTimeGauge

protected <T> TimeGauge newTimeGauge(Meter.Id id,
                                     @Nullable
                                     T obj,
                                     java.util.concurrent.TimeUnit valueFunctionUnit,
                                     java.util.function.ToDoubleFunction<T> valueFunction)

Build a new time gauge to be added to the registry. This is guaranteed to only be called if the time gauge doesn't already exist.

Type Parameters:

T - The type of the object upon which the value function derives a measurement.

Parameters:

id - The id that uniquely identifies the time gauge.

obj - The state object from which the value function derives a measurement.

valueFunctionUnit - The base unit of time returned by the value function.

valueFunction - A function returning a time value that can go up or down.

Returns:

A new time gauge.

newFunctionTimer

protected abstract <T> FunctionTimer newFunctionTimer(Meter.Id id,
                                                      T obj,
                                                      java.util.function.ToLongFunction<T> countFunction,
                                                      java.util.function.ToDoubleFunction<T> totalTimeFunction,
                                                      java.util.concurrent.TimeUnit totalTimeFunctionUnit)

Build a new function timer to be added to the registry. This is guaranteed to only be called if the function timer doesn't already exist.

Type Parameters:

T - The type of the object upon which the value functions derives their measurements.

Parameters:

id - The id that uniquely identifies the function timer.

obj - The state object from which the count and total functions derive measurements.

countFunction - A monotonically increasing count function.

totalTimeFunction - A monotonically increasing total time function.

totalTimeFunctionUnit - The base unit of time of the totals returned by the total time function.

Returns:

A new function timer.

newFunctionCounter

protected abstract <T> FunctionCounter newFunctionCounter(Meter.Id id,
                                                          T obj,
                                                          java.util.function.ToDoubleFunction<T> countFunction)

Build a new function counter to be added to the registry. This is guaranteed to only be called if the function counter doesn't already exist.

Type Parameters:

T - The type of the object upon which the value function derives a measurement.

Parameters:

id - The id that uniquely identifies the function counter.

obj - The state object from which the count function derives a measurement.

countFunction - A monotonically increasing count function.

Returns:

A new function counter.

getConventionTags

protected java.util.List<Tag> getConventionTags(Meter.Id id)

getConventionName

protected java.lang.String getConventionName(Meter.Id id)

getBaseTimeUnit

protected abstract java.util.concurrent.TimeUnit getBaseTimeUnit()

Returns:

the registry's base TimeUnit. Must not be null.

defaultHistogramConfig

protected abstract DistributionStatisticConfig defaultHistogramConfig()

Every custom registry implementation should define a default histogram expiry at a minimum:

 DistributionStatisticConfig.builder()
    .expiry(defaultStep)
    .build()
    .merge(DistributionStatisticConfig.DEFAULT);
 

Returns:

The default distribution statistics config.

getMeters

public java.util.List<Meter> getMeters()

Returns:

The set of registered meters.

forEachMeter

public void forEachMeter(java.util.function.Consumer<? super Meter> consumer)

Iterate over each meter in the registry.

Parameters:

consumer - Consumer of each meter during iteration.

config

public MeterRegistry.Config config()

Returns:

A configuration object used to change the behavior of this registry.

find

public Search find(java.lang.String name)

Initiate a search beginning with a metric name. If constraints added in the search are not satisfied, the search will return null.

Parameters:

name - The meter name to locate.

Returns:

A new search.

get

public RequiredSearch get(java.lang.String name)

Initiate a search beginning with a metric name. All constraints added in the search must be satisfied or an MeterNotFoundException is thrown.

Parameters:

name - The meter name to locate.

Returns:

A new search.

counter

public Counter counter(java.lang.String name,
                       java.lang.Iterable<Tag> tags)

Tracks a monotonically increasing value.

Parameters:

name - The base metric name

tags - Sequence of dimensions for breaking down the name.

Returns:

A new or existing counter.

counter

public Counter counter(java.lang.String name,
                       java.lang.String... tags)

Tracks a monotonically increasing value.

Parameters:

name - The base metric name

tags - MUST be an even number of arguments representing key/value pairs of tags.

Returns:

A new or existing counter.

summary

public DistributionSummary summary(java.lang.String name,
                                   java.lang.Iterable<Tag> tags)

Measures the distribution of samples.

Parameters:

name - The base metric name

tags - Sequence of dimensions for breaking down the name.

Returns:

A new or existing distribution summary.

summary

public DistributionSummary summary(java.lang.String name,
                                   java.lang.String... tags)

Measures the distribution of samples.

Parameters:

name - The base metric name

tags - MUST be an even number of arguments representing key/value pairs of tags.

Returns:

A new or existing distribution summary.

timer

public Timer timer(java.lang.String name,
                   java.lang.Iterable<Tag> tags)

Measures the time taken for short tasks and the count of these tasks.

Parameters:

name - The base metric name

tags - Sequence of dimensions for breaking down the name.

Returns:

A new or existing timer.

timer

public Timer timer(java.lang.String name,
                   java.lang.String... tags)

Measures the time taken for short tasks and the count of these tasks.

Parameters:

name - The base metric name

tags - MUST be an even number of arguments representing key/value pairs of tags.

Returns:

A new or existing timer.

more

public MeterRegistry.More more()

Access to less frequently used meter types and patterns.

Returns:

Access to additional meter types and patterns.

gauge

@Nullable
public <T> T gauge(java.lang.String name,
                             java.lang.Iterable<Tag> tags,
                             @Nullable
                             T obj,
                             java.util.function.ToDoubleFunction<T> valueFunction)

Register a gauge that reports the value of the object after the function valueFunction is applied. The registration will keep a weak reference to the object so it will not prevent garbage collection. Applying valueFunction on the object should be thread safe.

If multiple gauges are registered with the same id, then the values will be aggregated and the sum will be reported. For example, registering multiple gauges for active threads in a thread pool with the same id would produce a value that is the overall number of active threads. For other behaviors, manage it on the user side and avoid multiple registrations.

Type Parameters:

T - The type of the state object from which the gauge value is extracted.

Parameters:

name - Name of the gauge being registered.

tags - Sequence of dimensions for breaking down the name.

obj - State object used to compute a value.

valueFunction - Function that produces an instantaneous gauge value from the state object.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

gauge

@Nullable
public <T extends java.lang.Number> T gauge(java.lang.String name,
                                                      java.lang.Iterable<Tag> tags,
                                                      T number)

Register a gauge that reports the value of the Number.

Type Parameters:

T - The type of the number from which the gauge value is extracted.

Parameters:

name - Name of the gauge being registered.

tags - Sequence of dimensions for breaking down the name.

number - Thread-safe implementation of Number used to access the value.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

gauge

@Nullable
public <T extends java.lang.Number> T gauge(java.lang.String name,
                                                      T number)

Register a gauge that reports the value of the Number.

Type Parameters:

T - The type of the state object from which the gauge value is extracted.

Parameters:

name - Name of the gauge being registered.

number - Thread-safe implementation of Number used to access the value.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

gauge

@Nullable
public <T> T gauge(java.lang.String name,
                             T obj,
                             java.util.function.ToDoubleFunction<T> valueFunction)

Register a gauge that reports the value of the object.

Type Parameters:

T - The type of the state object from which the gauge value is extracted.

Parameters:

name - Name of the gauge being registered.

obj - State object used to compute a value.

valueFunction - Function that produces an instantaneous gauge value from the state object.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

gaugeCollectionSize

@Nullable
public <T extends java.util.Collection<?>> T gaugeCollectionSize(java.lang.String name,
                                                                           java.lang.Iterable<Tag> tags,
                                                                           T collection)

Register a gauge that reports the size of the Collection. The registration will keep a weak reference to the collection so it will not prevent garbage collection. The collection implementation used should be thread safe. Note that calling Collection.size() can be expensive for some collection implementations and should be considered before registering.

Type Parameters:

T - The type of the state object from which the gauge value is extracted.

Parameters:

name - Name of the gauge being registered.

tags - Sequence of dimensions for breaking down the name.

collection - Thread-safe implementation of Collection used to access the value.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

gaugeMapSize

@Nullable
public <T extends java.util.Map<?,?>> T gaugeMapSize(java.lang.String name,
                                                               java.lang.Iterable<Tag> tags,
                                                               T map)

Register a gauge that reports the size of the Map. The registration will keep a weak reference to the collection so it will not prevent garbage collection. The collection implementation used should be thread safe. Note that calling Map.size() can be expensive for some collection implementations and should be considered before registering.

Type Parameters:

T - The type of the state object from which the gauge value is extracted.

Parameters:

name - Name of the gauge being registered.

tags - Sequence of dimensions for breaking down the name.

map - Thread-safe implementation of Map used to access the value.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

remove

@Nullable
public Meter remove(Meter meter)

Parameters:

meter - The meter to remove

Returns:

The removed meter, or null if the provided meter is not currently registered.

Since:

1.1.0

remove

@Nullable
public Meter remove(Meter.Id id)

Parameters:

id - The id of the meter to remove

Returns:

The removed meter, or null if no meter matched the provided id.

Since:

1.1.0

close

public void close()

Closes this registry, releasing any resources in the process. Once closed, this registry will no longer accept new meters and any publishing activity will cease.

isClosed

public boolean isClosed()

If the registry is closed, it will no longer accept new meters and any publishing activity will cease.

Returns:

true if this registry is closed.