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 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.

  • 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, 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, 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, TimeUnit valueFunctionUnit, 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, ToLongFunction<T> countFunction, ToDoubleFunction<T> totalTimeFunction, 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, 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 List<Tag> getConventionTags(Meter.Id id)

    • getConventionName

      protected String getConventionName(Meter.Id id)

    • getBaseTimeUnit

      protected abstract 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 List<Meter> getMeters()
      Returns:
      The set of registered meters.

    • forEachMeter

      public void forEachMeter(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(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(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(String name, 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(String name, 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(String name, 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(String name, 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(String name, 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(String name, 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(String name, Iterable<Tag> tags, @Nullable T stateObject, 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 Number> T gauge(String name, 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 Number> T gauge(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(String name, T stateObject, 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 Collection<?>> T gaugeCollectionSize(String name, 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 Map<?, ?>> T gaugeMapSize(String name, 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)
      Remove a Meter from this registry. This is expected to be a Meter with the same Meter.Id returned when registering a meter - which will have MeterFilters applied to it.
      Parameters:
      meter - The meter to remove
      Returns:
      The removed meter, or null if the provided meter is not currently registered.
      Since:
      1.1.0

    • removeByPreFilterId

      @Incubating(since="1.3.16") @Nullable public Meter removeByPreFilterId(Meter.Id preFilterId)
      Remove a Meter from this registry based on its Meter.Id before applying this registry's MeterFilters to the given Meter.Id.
      Parameters:
      preFilterId - the id of the meter to remove
      Returns:
      The removed meter, or null if the meter is not found
      Since:
      1.3.16

    • remove

      @Incubating(since="1.1.0") @Nullable public Meter remove(Meter.Id mappedId)
      Remove a Meter from this registry based the given Meter.Id as-is. The registry's MeterFilters will not be applied to it. You can use the Meter.Id of the Meter returned when registering a meter, since that will have MeterFilters already applied to it.
      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.

    • meterRegistrationFailed

      protected void meterRegistrationFailed(Meter.Id id, @Nullable String reason)
      Handle a meter registration failure.
      Parameters:
      id - The id that was attempted, but for which registration failed.
      reason - The reason why the meter registration has failed
      Since:
      1.6.0