Class 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

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

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