Package 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.
If you register meters having the same ID multiple times, the first registration only will work and the subsequent registrations will be ignored.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
MeterRegistry.Config
Access to configuration options for this registry.class
MeterRegistry.More
Additional, less commonly used meter types.
-
Constructor Summary
Constructors Modifier Constructor Description protected
MeterRegistry(Clock clock)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
clear()
Clear all meters.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>
Tgauge(java.lang.String name, java.lang.Iterable<Tag> tags, T number)
Register a gauge that reports the value of theNumber
.<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 functionvalueFunction
is applied.<T extends java.lang.Number>
Tgauge(java.lang.String name, T number)
Register a gauge that reports the value of theNumber
.<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<?>>
TgaugeCollectionSize(java.lang.String name, java.lang.Iterable<Tag> tags, T collection)
Register a gauge that reports the size of theCollection
.<T extends java.util.Map<?,?>>
TgaugeMapSize(java.lang.String name, java.lang.Iterable<Tag> tags, T map)
Register a gauge that reports the size of theMap
.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 meter)
Meter
remove(Meter.Id id)
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.
-
-
-
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.
-
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 returnnull
.- 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 anMeterNotFoundException
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 nametags
- 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 nametags
- 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 nametags
- 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 nametags
- 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 nametags
- 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 nametags
- 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 functionvalueFunction
is applied. The registration will keep a weak reference to the object so it will not prevent garbage collection. ApplyingvalueFunction
on the object should be thread safe.- 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 theNumber
.- 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 ofNumber
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 theNumber
.- 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 ofNumber
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 theCollection
. 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 callingCollection.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 ofCollection
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 theMap
. 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 callingMap.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 ofMap
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
@Incubating(since="1.1.0") @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
@Incubating(since="1.1.0") @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
-
clear
@Incubating(since="1.2.0") public void clear()
Clear all meters.- Since:
- 1.2.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.
-
-