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:

MetricFilter

Field Summary

Fields

Modifier and Type	Field and Description
static String	APPLICATION_SCOPE String constant to represent the scope value used for the application scope
static String	BASE_SCOPE String constant to represent the scope value used for the base scope
static String	VENDOR_SCOPE String constant to represent the scope value used for the vendor scope

Method Summary

Modifier and Type	Method and Description
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.
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.
Counter	counter(MetricID metricID) Return the Counter registered under the MetricID; or create and register a new Counter if none is registered.
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.
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.
<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.
<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.
<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.
<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.
<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.
<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.
Counter	getCounter(MetricID metricID) Return the Counter registered for the provided MetricID.
SortedMap<MetricID,Counter>	getCounters() Returns a map of all the counters in the registry and their MetricIDs.
SortedMap<MetricID,Counter>	getCounters(MetricFilter filter) Returns a map of all the counters in the registry and their MetricIDs which match the given filter.
Gauge<?>	getGauge(MetricID metricID) Return the Gauge registered for the provided MetricID.
SortedMap<MetricID,Gauge>	getGauges() Returns a map of all the gauges in the registry and their MetricIDs.
SortedMap<MetricID,Gauge>	getGauges(MetricFilter filter) Returns a map of all the gauges in the registry and their MetricIDs which match the given filter.
Histogram	getHistogram(MetricID metricID) Return the Histogram registered for the provided MetricID.
SortedMap<MetricID,Histogram>	getHistograms() Returns a map of all the histograms in the registry and their MetricIDs.
SortedMap<MetricID,Histogram>	getHistograms(MetricFilter filter) Returns a map of all the histograms in the registry and their MetricIDs which match the given filter.
Map<String,Metadata>	getMetadata() Returns a map of all the metadata in the registry and their names.
Metadata	getMetadata(String name) Return the Metadata for the provided name.
Metric	getMetric(MetricID metricID) Return the Metric registered for a provided MetricID.
<T extends Metric> T	getMetric(MetricID metricID, Class<T> asType) Return the Metric registered for the provided MetricID as the provided type.
SortedSet<MetricID>	getMetricIDs() Returns a set of the MetricIDs of all the metrics in the registry.
Map<MetricID,Metric>	getMetrics() Returns a map of all the metrics in the registry and their MetricIDs at query time.
<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.
SortedMap<MetricID,Metric>	getMetrics(MetricFilter filter) Returns a map of all the metrics in the registry and their MetricIDs which match the given filter.
SortedSet<String>	getNames() Returns a set of the names of all the metrics in the registry.
String	getScope() Returns the scope of this metric registry.
Timer	getTimer(MetricID metricID) Return the Timer registered for the provided MetricID.
SortedMap<MetricID,Timer>	getTimers() Returns a map of all the timers in the registry and their MetricIDs.
SortedMap<MetricID,Timer>	getTimers(MetricFilter filter) Returns a map of all the timers in the registry and their MetricIDs which match the given filter.
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.
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.
Histogram	histogram(MetricID metricID) Return the Histogram registered under the MetricID; or create and register a new Histogram if none is registered.
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.
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.
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.
static String	name(String name, String... names) Concatenates elements to form a dotted name, eliding any null values or empty strings.
boolean	remove(MetricID metricID) Removes the metric with the given MetricID
boolean	remove(String name) Removes all metrics with the given name.
void	removeMatching(MetricFilter filter) Removes all metrics which match the given filter.
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.
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.
Timer	timer(MetricID metricID) Return the Timer registered under the MetricID; or create and register a new Timer if none is registered.
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.
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.

Field Detail

APPLICATION_SCOPE

static final String APPLICATION_SCOPE

String constant to represent the scope value used for the application scope

See Also:

Constant Field Values

VENDOR_SCOPE

static final String VENDOR_SCOPE

String constant to represent the scope value used for the vendor scope

See Also:

Constant Field Values

BASE_SCOPE

static final String BASE_SCOPE

String constant to represent the scope value used for the base scope

See Also:

Constant Field Values

Method Detail

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)