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.

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected Clock clock  

  • Constructor Summary

    Constructors
    Modifier Constructor Description
    protected MeterRegistry​(Clock clock)  

  • Method Summary

    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>
    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 stateObject, 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 stateObject, 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 LongTaskTimer newLongTaskTimer​(Meter.Id id)
    Deprecated.
    Implement newLongTaskTimer(Meter.Id, DistributionStatisticConfig) instead.
    protected LongTaskTimer newLongTaskTimer​(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig)
    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 mappedId)  
    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 Details

    • clock

      protected final Clock clock

  • Constructor Details

    • MeterRegistry

      protected MeterRegistry​(Clock clock)

  • Method Details

    • 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

      @Deprecated protected LongTaskTimer newLongTaskTimer​(Meter.Id id)
      Deprecated.
      Implement newLongTaskTimer(Meter.Id, DistributionStatisticConfig) instead.
      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.

    • newLongTaskTimer

      protected LongTaskTimer newLongTaskTimer​(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig)
      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.
      distributionStatisticConfig - Configuration for published distribution statistics.
      Returns:
      A new long task timer.
      Since:
      1.5.0

    • 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 stateObject, 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.
      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.
      stateObject - State object used to compute a value.
      valueFunction - Function that produces an instantaneous gauge value from the state object.
      Returns:
      The state object 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 stateObject, 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.
      stateObject - State object used to compute a value.
      valueFunction - Function that produces an instantaneous gauge value from the state object.
      Returns:
      The state object 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 Collection 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 Map 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 mappedId)
      Parameters:
      mappedId - 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.