Package org.eclipse.microprofile.metrics

Interface MetricRegistry

public interface MetricRegistry
The registry that stores metrics and their metadata. The MetricRegistry provides methods to register, create and retrieve metrics and their respective metadata.
See Also:

  • Field Details

    • APPLICATION_SCOPE

      static final String APPLICATION_SCOPE
      String constant to represent the scope value used for the application scope
      See Also:

    • VENDOR_SCOPE

      static final String VENDOR_SCOPE
      String constant to represent the scope value used for the vendor scope
      See Also:

    • BASE_SCOPE

      static final String BASE_SCOPE
      String constant to represent the scope value used for the base scope
      See Also:

  • Method Details

    • name

      static String name(String name, String... names)
      Concatenates elements to form a dotted name, eliding any null values or empty strings.
      Parameters:
      name - the first element of the name
      names - the remaining elements of the name
      Returns:
      name and names concatenated by periods

    • name

      static String name(Class<?> klass, String... names)
      Concatenates a class name and elements to form a dotted name, eliding any null values or empty strings.
      Parameters:
      klass - the first element of the name
      names - the remaining elements of the name
      Returns:
      klass and names concatenated by periods

    • counter

      Counter counter(String name)
      Return the Counter registered under the MetricID with this name and with no tags; or create and register a new Counter if none is registered. If a Counter was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      name - the name of the metric
      Returns:
      a new or pre-existing Counter

    • counter

      Counter counter(String name, Tag... tags)
      Return the Counter registered under the MetricID with this name and with the provided Tags; or create and register a new Counter if none is registered. If a Counter was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      name - the name of the metric
      tags - the tags of the metric
      Returns:
      a new or pre-existing Counter
      Since:
      2.0

    • counter

      Counter counter(MetricID metricID)
      Return the Counter registered under the MetricID; or create and register a new Counter if none is registered. If a Counter was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      metricID - the ID of the metric
      Returns:
      a new or pre-existing Counter
      Since:
      3.0

    • counter

      Counter counter(Metadata metadata)
      Return the Counter registered under the MetricID with the Metadata's name and with no tags; or create and register a new Counter if none is registered. If a Counter was created, the provided Metadata object will be registered.

      Note: During retrieval or creation, if a Metadata object is already registered under this metric name and is not equal to the provided Metadata object then an exception will be thrown.

      Parameters:
      metadata - the name of the metric
      Returns:
      a new or pre-existing Counter

    • counter

      Counter counter(Metadata metadata, Tag... tags)
      Return the Counter registered under the MetricID with the Metadata's name and with the provided Tags; or create and register a new Counter if none is registered. If a Counter was created, the provided Metadata object will be registered.

      Note: During retrieval or creation, if a Metadata object is already registered under this metric name and is not equal to the provided Metadata object then an exception will be thrown.

      Parameters:
      metadata - the name of the metric
      tags - the tags of the metric
      Returns:
      a new or pre-existing Counter
      Since:
      2.0

    • gauge

      <T, R extends Number> Gauge<R> gauge(String name, T object, Function<T,R> func, Tag... tags)
      Return the Gauge of type Number registered under the MetricID with this name and with the provided Tags; or create and register this gauge if none is registered. If a Gauge was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used. The created Gauge will apply a Function to the provided object to resolve a Number value.
      Type Parameters:
      T - The Type of the Object of which the function func is applied to
      R - A Number
      Parameters:
      name - The name of the Gauge metric
      object - The object that the Function func will be applied to
      func - The Function that will be applied to object
      tags - The tags of the metric
      Returns:
      a new or pre-existing Gauge
      Since:
      3.0

    • gauge

      <T, R extends Number> Gauge<R> gauge(MetricID metricID, T object, Function<T,R> func)
      Return the Gauge of type Number registered under the MetricID; or create and register this gauge if none is registered. If a Gauge was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used. The created Gauge will apply a Function to the provided object to resolve a Number value.
      Type Parameters:
      T - The Type of the Object of which the function func is applied to
      R - A Number
      Parameters:
      metricID - The MetricID of the Gauge metric
      object - The object that the Function func will be applied to
      func - The Function that will be applied to object
      Returns:
      a new or pre-existing Gauge
      Since:
      3.0

    • gauge

      <T, R extends Number> Gauge<R> gauge(Metadata metadata, T object, Function<T,R> func, Tag... tags)
      Return the Gauge of type Number registered under the MetricID with the @{link Metadata}'s name and with the provided Tags; or create and register this gauge if none is registered. If a Gauge was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used. The created Gauge will apply a Function to the provided object to resolve a Number value.
      Type Parameters:
      T - The Type of the Object of which the function func is applied to
      R - A Number
      Parameters:
      metadata - The Metadata of the Gauge
      object - The object that the Function func will be applied to
      func - The Function that will be applied to object
      tags - The tags of the metric
      Returns:
      a new or pre-existing Gauge
      Since:
      3.0

    • gauge

      <T extends Number> Gauge<T> gauge(String name, Supplier<T> supplier, Tag... tags)
      Return the Gauge registered under the MetricID with this name and with the provided Tags; or create and register this gauge if none is registered. If a Gauge was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used. The created Gauge will return the value that the Supplier will provide.
      Type Parameters:
      T - A Number
      Parameters:
      name - The name of the Gauge
      supplier - The Supplier function that will return the value for the Gauge metric
      tags - The tags of the metric
      Returns:
      a new or pre-existing Gauge
      Since:
      3.0

    • gauge

      <T extends Number> Gauge<T> gauge(MetricID metricID, Supplier<T> supplier)
      Return the Gauge registered under the MetricID; or create and register this gauge if none is registered. If a Gauge was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used. The created Gauge will return the value that the Supplier will provide.
      Type Parameters:
      T - A Number
      Parameters:
      metricID - The MetricID
      supplier - The Supplier function that will return the value for the Gauge metric
      Returns:
      a new or pre-existing Gauge
      Since:
      3.0

    • gauge

      <T extends Number> Gauge<T> gauge(Metadata metadata, Supplier<T> supplier, Tag... tags)
      Return the Gauge registered under the MetricID with the @{link Metadata}'s name and with the provided Tags; or create and register this gauge if none is registered. If a Gauge was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used. The created Gauge will return the value that the Supplier will provide.
      Type Parameters:
      T - A Number
      Parameters:
      metadata - The metadata of the gauge
      supplier - The Supplier function that will return the value for the Gauge metric
      tags - The tags of the metric
      Returns:
      a new or pre-existing Gauge
      Since:
      3.0

    • histogram

      Histogram histogram(String name)
      Return the Histogram registered under the MetricID with this name and with no tags; or create and register a new Histogram if none is registered. If a Histogram was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      name - the name of the metric
      Returns:
      a new or pre-existing Histogram

    • histogram

      Histogram histogram(String name, Tag... tags)
      Return the Histogram registered under the MetricID with this name and with the provided Tags; or create and register a new Histogram if none is registered. If a Histogram was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      name - the name of the metric
      tags - the tags of the metric
      Returns:
      a new or pre-existing Histogram
      Since:
      2.0

    • histogram

      Histogram histogram(MetricID metricID)
      Return the Histogram registered under the MetricID; or create and register a new Histogram if none is registered. If a Histogram was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      metricID - the ID of the metric
      Returns:
      a new or pre-existing Histogram
      Since:
      3.0

    • histogram

      Histogram histogram(Metadata metadata)
      Return the Histogram registered under the MetricID with the Metadata's name and with no tags; or create and register a new Histogram if none is registered. If a Histogram was created, the provided Metadata object will be registered.

      Note: During retrieval or creation, if a Metadata object is already registered under this metric name and is not equal to the provided Metadata object then an exception will be thrown.

      Parameters:
      metadata - the name of the metric
      Returns:
      a new or pre-existing Histogram

    • histogram

      Histogram histogram(Metadata metadata, Tag... tags)
      Return the Histogram registered under the MetricID with the Metadata's name and with the provided Tags; or create and register a new Histogram if none is registered. If a Histogram was created, the provided Metadata object will be registered.

      Note: During retrieval or creation, if a Metadata object is already registered under this metric name and is not equal to the provided Metadata object then an exception will be thrown.

      Parameters:
      metadata - the name of the metric
      tags - the tags of the metric
      Returns:
      a new or pre-existing Histogram
      Since:
      2.0

    • timer

      Timer timer(String name)
      Return the Timer registered under the MetricID with this name and with no tags; or create and register a new Timer if none is registered. If a Timer was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      name - the name of the metric
      Returns:
      a new or pre-existing Timer

    • timer

      Timer timer(String name, Tag... tags)
      Return the Timer registered under the MetricID with this name and with the provided Tags; or create and register a new Timer if none is registered. If a Timer was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      name - the name of the metric
      tags - the tags of the metric
      Returns:
      a new or pre-existing Timer
      Since:
      2.0

    • timer

      Timer timer(MetricID metricID)
      Return the Timer registered under the MetricID; or create and register a new Timer if none is registered. If a Timer was created, a Metadata object will be registered with the name and type. If a Metadata object is already registered with this metric name then that Metadata will be used.
      Parameters:
      metricID - the ID of the metric
      Returns:
      a new or pre-existing Timer
      Since:
      3.0

    • timer

      Timer timer(Metadata metadata)
      Return the Timer registered under the the MetricID with the Metadata's name and with no tags; or create and register a new Timer if none is registered. If a Timer was created, the provided Metadata object will be registered.

      Note: During retrieval or creation, if a Metadata object is already registered under this metric name and is not equal to the provided Metadata object then an exception will be thrown.

      Parameters:
      metadata - the name of the metric
      Returns:
      a new or pre-existing Timer

    • timer

      Timer timer(Metadata metadata, Tag... tags)
      Return the Timer registered under the the MetricID with the Metadata's name and with the provided Tags; or create and register a new Timer if none is registered. If a Timer was created, the provided Metadata object will be registered.

      Note: During retrieval or creation, if a Metadata object is already registered under this metric name and is not equal to the provided Metadata object then an exception will be thrown.

      Parameters:
      metadata - the name of the metric
      tags - the tags of the metric
      Returns:
      a new or pre-existing Timer
      Since:
      2.0

    • getMetric

      Metric getMetric(MetricID metricID)
      Return the Metric registered for a provided MetricID.
      Parameters:
      metricID - lookup key, not null
      Returns:
      the Metric registered for the provided MetricID or null if none has been registered so far
      Since:
      3.0

    • getMetric

      <T extends Metric> T getMetric(MetricID metricID, Class<T> asType)
      Return the Metric registered for the provided MetricID as the provided type.
      Parameters:
      metricID - lookup key, not null
      asType - the return type which is expected to be compatible with the actual type of the registered metric
      Returns:
      the Metric registered for the provided MetricID or null if none has been registered so far
      Throws:
      IllegalArgumentException - If the registered metric was not assignable to the provided type
      Since:
      3.0

    • getCounter

      Counter getCounter(MetricID metricID)
      Return the Counter registered for the provided MetricID.
      Parameters:
      metricID - lookup key, not null
      Returns:
      the Counter registered for the key or null if none has been registered so far
      Throws:
      IllegalArgumentException - If the registered metric was not assignable to Counter
      Since:
      3.0

    • getGauge

      Gauge<?> getGauge(MetricID metricID)
      Return the Gauge registered for the provided MetricID.
      Parameters:
      metricID - lookup key, not null
      Returns:
      the Gauge registered for the key or null if none has been registered so far
      Throws:
      IllegalArgumentException - If the registered metric was not assignable to Gauge
      Since:
      3.0

    • getHistogram

      Histogram getHistogram(MetricID metricID)
      Return the Histogram registered for the provided MetricID.
      Parameters:
      metricID - lookup key, not null
      Returns:
      the Histogram registered for the key or null if none has been registered so far
      Throws:
      IllegalArgumentException - If the registered metric was not assignable to Histogram
      Since:
      3.0

    • getTimer

      Timer getTimer(MetricID metricID)
      Return the Timer registered for the provided MetricID.
      Parameters:
      metricID - lookup key, not null
      Returns:
      the Timer registered for the key or null if none has been registered so far
      Throws:
      IllegalArgumentException - If the registered metric was not assignable to Timer
      Since:
      3.0

    • getMetadata

      Metadata getMetadata(String name)
      Return the Metadata for the provided name.
      Parameters:
      name - the name of the metric
      Returns:
      the Metadata for the provided name or null if none has been registered for that name
      Since:
      3.0

    • remove

      boolean remove(String name)
      Removes all metrics with the given name.
      Parameters:
      name - the name of the metric
      Returns:
      whether or not the metric was removed

    • remove

      boolean remove(MetricID metricID)
      Removes the metric with the given MetricID
      Parameters:
      metricID - the MetricID of the metric
      Returns:
      whether or not the metric was removed
      Since:
      2.0

    • removeMatching

      void removeMatching(MetricFilter filter)
      Removes all metrics which match the given filter.
      Parameters:
      filter - a filter

    • getNames

      SortedSet<String> getNames()
      Returns a set of the names of all the metrics in the registry.
      Returns:
      the names of all the metrics

    • getMetricIDs

      SortedSet<MetricID> getMetricIDs()
      Returns a set of the MetricIDs of all the metrics in the registry.
      Returns:
      the MetricIDs of all the metrics

    • getGauges

      SortedMap<MetricID,Gauge> getGauges()
      Returns a map of all the gauges in the registry and their MetricIDs.
      Returns:
      all the gauges in the registry

    • getGauges

      SortedMap<MetricID,Gauge> getGauges(MetricFilter filter)
      Returns a map of all the gauges in the registry and their MetricIDs which match the given filter.
      Parameters:
      filter - the metric filter to match
      Returns:
      all the gauges in the registry

    • getCounters

      SortedMap<MetricID,Counter> getCounters()
      Returns a map of all the counters in the registry and their MetricIDs.
      Returns:
      all the counters in the registry

    • getCounters

      SortedMap<MetricID,Counter> getCounters(MetricFilter filter)
      Returns a map of all the counters in the registry and their MetricIDs which match the given filter.
      Parameters:
      filter - the metric filter to match
      Returns:
      all the counters in the registry

    • getHistograms

      SortedMap<MetricID,Histogram> getHistograms()
      Returns a map of all the histograms in the registry and their MetricIDs.
      Returns:
      all the histograms in the registry

    • getHistograms

      SortedMap<MetricID,Histogram> getHistograms(MetricFilter filter)
      Returns a map of all the histograms in the registry and their MetricIDs which match the given filter.
      Parameters:
      filter - the metric filter to match
      Returns:
      all the histograms in the registry

    • getTimers

      SortedMap<MetricID,Timer> getTimers()
      Returns a map of all the timers in the registry and their MetricIDs.
      Returns:
      all the timers in the registry

    • getTimers

      SortedMap<MetricID,Timer> getTimers(MetricFilter filter)
      Returns a map of all the timers in the registry and their MetricIDs which match the given filter.
      Parameters:
      filter - the metric filter to match
      Returns:
      all the timers in the registry

    • getMetrics

      SortedMap<MetricID,Metric> getMetrics(MetricFilter filter)
      Returns a map of all the metrics in the registry and their MetricIDs which match the given filter.
      Parameters:
      filter - the metric filter to match
      Returns:
      all the metrics in the registry
      Since:
      3.0

    • getMetrics

      <T extends Metric> SortedMap<MetricID,T> getMetrics(Class<T> ofType, MetricFilter filter)
      Returns a map of all the metrics in the registry and their MetricIDs which match the given filter and which are assignable to the provided type.
      Parameters:
      ofType - the type to which all returned metrics should be assignable
      filter - the metric filter to match
      Returns:
      all the metrics in the registry
      Since:
      3.0

    • getMetrics

      Map<MetricID,Metric> getMetrics()
      Returns a map of all the metrics in the registry and their MetricIDs at query time. The only guarantee about this method is that any key has a value (compared to using getMetric(MetricID) and getMetricIDs() together). It is only intended for bulk querying, if you need a single or a few entries, always prefer getMetric(MetricID) or getMetrics(MetricFilter).
      Returns:
      all the metrics in the registry

    • getMetadata

      Map<String,Metadata> getMetadata()
      Returns a map of all the metadata in the registry and their names. The only guarantee about this method is that any key has a value (compared to using getMetadata(String). It is only intended for bulk querying, if you need a single or a few metadata, always prefer getMetadata(String)}.
      Returns:
      all the metadata in the registry

    • getScope

      String getScope()
      Returns the scope of this metric registry.
      Returns:
      Scope of this registry (VENDOR_SCOPE, BASE_SCOPE, APPLICATION_SCOPE, or a custom scope)