com.netflix.spectator.api.patterns

Class PolledMeter.Builder

java.lang.Object

com.netflix.spectator.api.patterns.TagsBuilder<PolledMeter.Builder>

com.netflix.spectator.api.patterns.PolledMeter.Builder

Enclosing class:

PolledMeter

public static final class PolledMeter.Builder
extends TagsBuilder<PolledMeter.Builder>

Builder for configuring a polled meter value.

Field Summary

Fields inherited from class com.netflix.spectator.api.patterns.TagsBuilder

extraTags

Method Summary

Modifier and Type	Method and Description
<T extends Number> T	monitorMonotonicCounter(T number) Poll the value of the provided Number and update a counter with the delta since the last time the value was sampled.
<T> T	monitorMonotonicCounter(T obj, ToLongFunction<T> f) Map a monotonically increasing long or int value to a counter.
<T extends Collection<?>> T	monitorSize(T collection) Poll the value of the provided Collection.
<T extends Map<?,?>> T	monitorSize(T map) Poll the value of the provided Map.
void	monitorStaticMethodMonotonicCounter(LongSupplier supplier) Map a monotonically increasing long or int value to a counter.
void	monitorStaticMethodValue(DoubleSupplier supplier) Poll by executing supplier.getAsDouble() and reporting the returned value.
<T extends Number> T	monitorValue(T number) Poll the value of the provided Number.
<T> T	monitorValue(T obj, ToDoubleFunction<T> f) Poll by executing f(obj) and reporting the returned value.
PolledMeter.Builder	scheduleOn(ScheduledExecutorService executor) Set the executor to be used for polling the value.
PolledMeter.Builder	withDelay(Duration delay) Set the delay at which the value should be refreshed.

Methods inherited from class com.netflix.spectator.api.patterns.TagsBuilder

withTag, withTag, withTag, withTag, withTags, withTags, withTags, withTags

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

scheduleOn

public PolledMeter.Builder scheduleOn(ScheduledExecutorService executor)

Set the executor to be used for polling the value. If not set, then the default executor will be used which is limited to a single thread to minimize the worst case resource usage for collecting the meter data. Use a custom executor if more resources are needed or if the polling operation is expensive.

Returns:

This builder instance to allow chaining of operations.

withDelay

public PolledMeter.Builder withDelay(Duration delay)

Set the delay at which the value should be refreshed. If not set, then the default value will be the gauge polling frequency set in the registry configuration.

Returns:

This builder instance to allow chaining of operations.

See Also:

RegistryConfig.gaugePollingFrequency()

monitorValue

public <T extends Number> T monitorValue(T number)

Poll the value of the provided Number. The implementation provided must be thread safe. The most common usages of this are to monitor instances of AtomicInteger or AtomicLong.

Parameters:

number - Thread-safe implementation of Number used to access the value.

Returns:

The number that was passed in to allow the builder to be used inline as part of an assignment.

monitorValue

public <T> T monitorValue(T obj,
                          ToDoubleFunction<T> f)

Poll by executing f(obj) and reporting the returned value. The provided function must be thread safe and cheap to execute. Expensive operations, including any IO or network calls, should not be performed inline unless using a custom executor by calling scheduleOn(ScheduledExecutorService). Assume that the function will be called frequently and may be called concurrently.

A weak reference will be kept to obj so that monitoring the object will not prevent garbage collection. The meter will go away when obj is collected. If obj is null, then it will be treated as an already collected object and a warning will be logged.

To explicitly disable polling call PolledMeter.remove(Registry, Id) with the same id used with this builder.

Parameters:

obj - Object used to compute a value.

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

Returns:

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

monitorStaticMethodValue

public void monitorStaticMethodValue(DoubleSupplier supplier)

Poll by executing supplier.getAsDouble() and reporting the returned value. The provided function must be thread safe and cheap to execute. Expensive operations, including any IO or network calls, should not be performed inline unless using a custom executor by calling scheduleOn(ScheduledExecutorService). Assume that the function will be called frequently and may be called concurrently.

This helper should only be used with static method references. It will keep a strong reference to any enclosed objects and they will never get garbage collected unless removed explicitly by the user.

To explicitly disable polling call PolledMeter.remove(Registry, Id) with the same id used with this builder.

Parameters:

supplier - Supplier that will be called to access the value.

monitorMonotonicCounter

public <T extends Number> T monitorMonotonicCounter(T number)

Poll the value of the provided Number and update a counter with the delta since the last time the value was sampled. The implementation provided must be thread safe. The most common usages of this are to monitor instances of AtomicInteger, AtomicLong, or LongAdder. For more information see monitorMonotonicCounter(Object, ToLongFunction).

Parameters:

number - Thread-safe implementation of Number used to access the value.

Returns:

The number that was passed in to allow the builder to be used inline as part of an assignment.

monitorMonotonicCounter

public <T> T monitorMonotonicCounter(T obj,
                                     ToLongFunction<T> f)

Map a monotonically increasing long or int value to a counter. Monotonic counters are frequently used as a simple way for exposing the amount of change. In order to be useful, they need to be polled frequently so the change can be measured regularly over time.

Example monotonic counters provided by the JDK:

• ThreadPoolExecutor.getCompletedTaskCount()
• GarbageCollectorMXBean

Example usage:

   Registry registry = ...
   MonotonicCounter.using(registry)
     .withName("pool.completedTasks")
     .monitorMonotonicCounter(executor, ThreadPoolExecutor::getCompletedTaskCount);
 

The value is polled by executing f(obj) and a counter will be updated with the delta since the last time the value was sampled. The provided function must be thread safe and cheap to execute. Expensive operations, including any IO or network calls, should not be performed inline unless using a custom executor by calling scheduleOn(ScheduledExecutorService). Assume that the function will be called frequently and may be called concurrently.

A weak reference will be kept to obj so that monitoring the object will not prevent garbage collection. The meter will go away when obj is collected. If obj is null, then it will be treated as an already collected object and a warning will be logged.

To explicitly disable polling call PolledMeter.remove(Registry, Id) with the same id used with this builder.

Parameters:

obj - Object used to compute a value.

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

Returns:

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

monitorStaticMethodMonotonicCounter

public void monitorStaticMethodMonotonicCounter(LongSupplier supplier)

Map a monotonically increasing long or int value to a counter. Monotonic counters are frequently used as a simple way for exposing the amount of change. In order to be useful, they need to be polled frequently so the change can be measured regularly over time.

Poll by executing supplier.getAsLong() and reporting the returned value. The provided function must be thread safe and cheap to execute. Expensive operations, including any IO or network calls, should not be performed inline unless using a custom executor by calling scheduleOn(ScheduledExecutorService). Assume that the function will be called frequently and may be called concurrently.

This helper should only be used with static method references. It will keep a strong reference to any enclosed objects and they will never get garbage collected unless removed explicitly by the user.

To explicitly disable polling call PolledMeter.remove(Registry, Id) with the same id used with this builder.

Parameters:

supplier - Supplier that will be called to access the value.

monitorSize

public <T extends Collection<?>> T monitorSize(T collection)

Poll the value of the provided Collection. The implementation provided must be thread safe. Keep in mind that computing the size can be an expensive operation for some collection types.

Parameters:

collection - Thread-safe implementation of Collection.

Returns:

The collection that was passed in to allow the builder to be used inline as part of an assignment.

monitorSize

public <T extends Map<?,?>> T monitorSize(T map)

Poll the value of the provided Map. The implementation provided must be thread safe. Keep in mind that computing the size can be an expensive operation for some map types.

Parameters:

map - Thread-safe implementation of Map.

Returns:

The collection that was passed in to allow the builder to be used inline as part of an assignment.