com.netflix.spectator.api

Interface Registry

All Superinterfaces:

Iterable<Meter>

All Known Implementing Classes:

AbstractRegistry, CompositeRegistry, DefaultRegistry, ExtendedRegistry, NoopRegistry

public interface Registry
extends Iterable<Meter>

Registry to manage a set of meters.

Method Summary

Modifier and Type	Method and Description
Clock	clock() The clock used by the registry for timing events.
default <T extends Collection<?>> T	collectionSize(Id id, T collection) Register a gauge that reports the size of the Collection.
default <T extends Collection<?>> T	collectionSize(String name, T collection) Register a gauge that reports the size of the Collection.
default RegistryConfig	config() Configuration settings used for this registry.
Counter	counter(Id id) Measures the rate of some activity.
default Counter	counter(String name) Measures the rate of some activity.
default Counter	counter(String name, Iterable<Tag> tags) Measures the rate of some activity.
default Counter	counter(String name, String... tags) Measures the rate of some activity.
default Stream<Counter>	counters() Returns a stream of all registered counters.
Id	createId(String name) Creates an identifier for a meter.
Id	createId(String name, Iterable<Tag> tags) Creates an identifier for a meter.
default Id	createId(String name, Map<String,String> tags) Creates an identifier for a meter.
default Id	createId(String name, String... tags) Creates an identifier for a meter.
default Stream<DistributionSummary>	distributionSummaries() Returns a stream of all registered distribution summaries.
DistributionSummary	distributionSummary(Id id) Measures the rate and variation in amount for some activity.
default DistributionSummary	distributionSummary(String name) Measures the sample distribution of events.
default DistributionSummary	distributionSummary(String name, Iterable<Tag> tags) Measures the sample distribution of events.
default DistributionSummary	distributionSummary(String name, String... tags) Measures the sample distribution of events.
default Gauge	gauge(Id id) Represents a value sampled from another source.
default <T extends Number> T	gauge(Id id, T number) Register a gauge that reports the value of the Number.
default <T> T	gauge(Id id, T obj, ToDoubleFunction<T> f) Register a gauge that reports the value of the object after the function f is applied.
default <T extends Number> T	gauge(String name, Iterable<Tag> tags, T number) Register a gauge that reports the value of the Number.
default <T extends Number> T	gauge(String name, T number) Register a gauge that reports the value of the Number.
default <T> T	gauge(String name, T obj, ToDoubleFunction<T> f) Register a gauge that reports the value of the object.
Meter	get(Id id) Returns the meter associated with a given id.
Iterator<Meter>	iterator() Iterator for traversing the set of meters in the registry.
default LongTaskTimer	longTaskTimer(Id id) Measures the time taken for long tasks.
default LongTaskTimer	longTaskTimer(String name) Measures the time taken for long tasks.
default LongTaskTimer	longTaskTimer(String name, Iterable<Tag> tags) Measures the time taken for long tasks.
default LongTaskTimer	longTaskTimer(String name, String... tags) Measures the time taken for long tasks.
default <T extends Map<?,?>> T	mapSize(Id id, T collection) Register a gauge that reports the size of the Map.
default <T extends Map<?,?>> T	mapSize(String name, T collection) Register a gauge that reports the size of the Map.
default void	methodValue(Id id, Object obj, String method) Register a gauge that reports the return value of invoking the method on the object.
default void	methodValue(String name, Object obj, String method) Register a gauge that reports the return value of invoking the method on the object.
default void	propagate(String msg, Throwable t) Log a warning and if enabled propagate the exception t.
default void	propagate(Throwable t) Log a warning using the message from the exception and if enabled propagate the exception t.
void	register(Meter meter) Add a custom meter to the registry.
ConcurrentMap<Id,Object>	state() Returns a map that can be used to associate state with the registry.
default Stream<Meter>	stream() Returns a stream of all registered meters.
Timer	timer(Id id) Measures the rate and time taken for short running tasks.
default Timer	timer(String name) Measures the time taken for short tasks.
default Timer	timer(String name, Iterable<Tag> tags) Measures the time taken for short tasks.
default Timer	timer(String name, String... tags) Measures the time taken for short tasks.
default Stream<Timer>	timers() Returns a stream of all registered timers.
default <T extends Registry> T	underlying(Class<T> c) Returns the first underlying registry that is an instance of c.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

clock

Clock clock()

The clock used by the registry for timing events.

config

default RegistryConfig config()

Configuration settings used for this registry.

createId

Id createId(String name)

Creates an identifier for a meter. All ids passed into other calls should be created by the registry.

Parameters:

name - Description of the measurement that is being collected.

createId

Id createId(String name,
            Iterable<Tag> tags)

Creates an identifier for a meter. All ids passed into other calls should be created by the registry.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

register

void register(Meter meter)

Add a custom meter to the registry.

state

ConcurrentMap<Id,Object> state()

Returns a map that can be used to associate state with the registry. Users instrumenting their application will most likely never need to use this method. The primary use case is for building custom meter types that need some additional state beyond the core types supported by the registry. This map can be used to store the state so that the lifecycle of the data is connected to the registry. For an example, see some of the built in patterns such as LongTaskTimer.

counter

Counter counter(Id id)

Measures the rate of some activity. A counter is for continuously incrementing sources like the number of requests that are coming into a server.

Parameters:

id - Identifier created by a call to createId(java.lang.String)

distributionSummary

DistributionSummary distributionSummary(Id id)

Measures the rate and variation in amount for some activity. For example, it could be used to get insight into the variation in response sizes for requests to a server.

Parameters:

id - Identifier created by a call to createId(java.lang.String)

timer

Timer timer(Id id)

Measures the rate and time taken for short running tasks.

Parameters:

id - Identifier created by a call to createId(java.lang.String)

gauge

default Gauge gauge(Id id)

Represents a value sampled from another source. For example, the size of queue. The caller is responsible for sampling the value regularly and calling Gauge.set(double). Registry implementations are free to expire the gauge if it has not been updated in the last minute. If you do not want to worry about the sampling, then use one of the helpers linked below instead.

Parameters:

id - Identifier created by a call to createId(java.lang.String)

See Also:

gauge(Id, Number), gauge(Id, Object, ToDoubleFunction), collectionSize(Id, Collection), mapSize(Id, Map)

get

Meter get(Id id)

Returns the meter associated with a given id.

Parameters:

id - Identifier for the meter.

Returns:

Instance of the meter or null if there is no match.

iterator

Iterator<Meter> iterator()

Iterator for traversing the set of meters in the registry.

Specified by:

iterator in interface Iterable<Meter>

underlying

default <T extends Registry> T underlying(Class<T> c)

Returns the first underlying registry that is an instance of c.

createId

default Id createId(String name,
                    String... tags)

Creates an identifier for a meter.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Identifier for a meter.

createId

default Id createId(String name,
                    Map<String,String> tags)

Creates an identifier for a meter.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Identifier for a meter.

counter

default Counter counter(String name)

Measures the rate of some activity.

Parameters:

name - Description of the measurement that is being collected.

Returns:

Counter instance with the corresponding id.

counter

default Counter counter(String name,
                        Iterable<Tag> tags)

Measures the rate of some activity.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Counter instance with the corresponding id.

counter

default Counter counter(String name,
                        String... tags)

Measures the rate of some activity.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Counter instance with the corresponding id.

distributionSummary

default DistributionSummary distributionSummary(String name)

Measures the sample distribution of events.

Parameters:

name - Description of the measurement that is being collected.

Returns:

Summary instance with the corresponding id.

distributionSummary

default DistributionSummary distributionSummary(String name,
                                                Iterable<Tag> tags)

Measures the sample distribution of events.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Summary instance with the corresponding id.

distributionSummary

default DistributionSummary distributionSummary(String name,
                                                String... tags)

Measures the sample distribution of events.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Summary instance with the corresponding id.

timer

default Timer timer(String name)

Measures the time taken for short tasks.

Parameters:

name - Description of the measurement that is being collected.

Returns:

Timer instance with the corresponding id.

timer

default Timer timer(String name,
                    Iterable<Tag> tags)

Measures the time taken for short tasks.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Timer instance with the corresponding id.

timer

default Timer timer(String name,
                    String... tags)

Measures the time taken for short tasks.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Timer instance with the corresponding id.

longTaskTimer

default LongTaskTimer longTaskTimer(Id id)

Measures the time taken for long tasks.

Parameters:

id - Identifier for the metric being registered.

Returns:

Timer instance with the corresponding id.

longTaskTimer

default LongTaskTimer longTaskTimer(String name)

Measures the time taken for long tasks.

Parameters:

name - Description of the measurement that is being collected.

Returns:

Timer instance with the corresponding id.

longTaskTimer

default LongTaskTimer longTaskTimer(String name,
                                    Iterable<Tag> tags)

Measures the time taken for long tasks.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Timer instance with the corresponding id.

longTaskTimer

default LongTaskTimer longTaskTimer(String name,
                                    String... tags)

Measures the time taken for long tasks.

Parameters:

name - Description of the measurement that is being collected.

tags - Other dimensions that can be used to classify the measurement.

Returns:

Timer instance with the corresponding id.

gauge

default <T extends Number> T gauge(Id id,
                                   T number)

Register a gauge that reports the value of the Number. The registration will keep a weak reference to the number so it will not prevent garbage collection. The number implementation used should be thread safe. See gauge(Id, Object, ToDoubleFunction) for more information on gauges.

Parameters:

id - Identifier for the metric 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

default <T extends Number> T gauge(String name,
                                   T number)

Register a gauge that reports the value of the Number. See gauge(Id, Number).

Parameters:

name - Name of the metric 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

default <T extends Number> T gauge(String name,
                                   Iterable<Tag> tags,
                                   T number)

Register a gauge that reports the value of the Number. See gauge(Id, Number).

Parameters:

name - Name of the metric 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

default <T> T gauge(Id id,
                    T obj,
                    ToDoubleFunction<T> f)

Register a gauge that reports the value of the object after the function f is applied. The registration will keep a weak reference to the object so it will not prevent garbage collection. Applying f on the object should be thread safe. If multiple gauges are registered with the same id, then the values will be aggregated and the sum will be reported. For example, registering multiple gauges for active threads in a thread pool with the same id would produce a value that is the overall number of active threads. For other behaviors, manage it on the user side and avoid multiple registrations.

Parameters:

id - Identifier for the metric being registered.

obj - Object used to compute a value.

f - Function that is applied on the value for the number.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

gauge

default <T> T gauge(String name,
                    T obj,
                    ToDoubleFunction<T> f)

Register a gauge that reports the value of the object. See gauge(Id, Object, ToDoubleFunction).

Parameters:

name - Name of the metric being registered.

obj - Object used to compute a value.

f - Function that is applied on the value for the number.

Returns:

The number that was passed in so the registration can be done as part of an assignment statement.

collectionSize

default <T extends Collection<?>> T collectionSize(Id id,
                                                   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.

Parameters:

id - Identifier for the metric being registered.

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.

collectionSize

default <T extends Collection<?>> T collectionSize(String name,
                                                   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.

Parameters:

name - Name of the metric being registered.

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.

mapSize

default <T extends Map<?,?>> T mapSize(Id id,
                                       T collection)

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.

Parameters:

id - Identifier for the metric being registered.

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

mapSize

default <T extends Map<?,?>> T mapSize(String name,
                                       T collection)

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.

Parameters:

name - Name of the metric being registered.

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

methodValue

default void methodValue(Id id,
                         Object obj,
                         String method)

Register a gauge that reports the return value of invoking the method on the object. The registration will keep a weak reference to the object so it will not prevent garbage collection. The registered method should be thread safe and cheap to invoke. Any potentially long running or expensive activity such as IO should not be performed inline.

Parameters:

id - Identifier for the metric being registered.

obj - Object used to compute a value.

method - Name of the method to invoke on the object.

methodValue

default void methodValue(String name,
                         Object obj,
                         String method)

Register a gauge that reports the return value of invoking the method on the object. The registration will keep a weak reference to the object so it will not prevent garbage collection. The registered method should be thread safe and cheap to invoke. Any potentially long running or expensive activity such as IO should not be performed inline.

Parameters:

name - Name of the metric being registered.

obj - Object used to compute a value.

method - Name of the method to invoke on the object.

stream

default Stream<Meter> stream()

Returns a stream of all registered meters.

counters

default Stream<Counter> counters()

Returns a stream of all registered counters. This operation is mainly used for testing as a convenient way to get an aggregated value. For example, to generate a summary of all counters with name "foo":

 LongSummaryStatistics summary = r.counters()
   .filter(Functions.nameEquals("foo"))
   .collect(Collectors.summarizingLong(Counter::count));
 

distributionSummaries

default Stream<DistributionSummary> distributionSummaries()

Returns a stream of all registered distribution summaries. This operation is mainly used for testing as a convenient way to get an aggregated value. For example, to generate a summary of the counts and total amounts for all distribution summaries with name "foo":

 LongSummaryStatistics countSummary = r.distributionSummaries()
   .filter(Functions.nameEquals("foo"))
   .collect(Collectors.summarizingLong(DistributionSummary::count));

 LongSummaryStatistics totalSummary = r.distributionSummaries()
   .filter(Functions.nameEquals("foo"))
   .collect(Collectors.summarizingLong(DistributionSummary::totalAmount));

 double avgAmount = (double) totalSummary.getSum() / countSummary.getSum();
 

timers

default Stream<Timer> timers()

Returns a stream of all registered timers. This operation is mainly used for testing as a convenient way to get an aggregated value. For example, to generate a summary of the counts and total amounts for all timers with name "foo":

 LongSummaryStatistics countSummary = r.timers()
   .filter(Functions.nameEquals("foo"))
   .collect(Collectors.summarizingLong(Timer::count));

 LongSummaryStatistics totalSummary = r.timers()
   .filter(Functions.nameEquals("foo"))
   .collect(Collectors.summarizingLong(Timer::totalTime));

 double avgTime = (double) totalSummary.getSum() / countSummary.getSum();
 

propagate

default void propagate(String msg,
                       Throwable t)

Log a warning and if enabled propagate the exception t. As a general rule instrumentation code should degrade gracefully and avoid impacting the core application. If the user makes a mistake and causes something to break, then it should not impact the application unless that mistake triggers a problem outside of the instrumentation code. However, in test code it is often better to throw so that mistakes are caught and corrected. This method is used to handle exceptions internal to the instrumentation code. Propagation is controlled by the RegistryConfig.propagateWarnings() setting. If the setting is true, then the exception will be propagated. Otherwise the exception will only get logged as a warning.

Parameters:

msg - Message written out to the log.

t - Exception to log and optionally propagate.

propagate

default void propagate(Throwable t)

Log a warning using the message from the exception and if enabled propagate the exception t. For more information see propagate(String, Throwable).

Parameters:

t - Exception to log and optionally propagate.