com.netflix.spectator.api.patterns

Class PolledMeter

java.lang.Object

com.netflix.spectator.api.patterns.PolledMeter

public final class PolledMeter
extends Object

Helper for configuring a meter that will receive a value by regularly polling the source in the background.

Example usage:

   Registry registry = ...
   AtomicLong connections = PolledMeter.using(registry)
     .withName("server.currentConnections")
     .monitorValue(new AtomicLong());

   // When a connection is added
   connections.incrementAndGet();

   // When a connection is removed
   connections.decrementAndGet();
 

Polling frequency will depend on the underlying registry implementation, but users should assume it will be frequently checked and that the provided function is cheap. Users should keep in mind that polling will not capture all activity, just sample it at some frequency. For example, if monitoring a queue, then a meter will only tell you the last sampled size when the value is reported. If more details are needed, then use an alternative type and ensure that all changes are reported when they occur.

For example, consider tracking the number of currently established connections to a server. Using a polled meter will show the last sampled number when reported. An alternative would be to report the number of connections to a DistributionSummary every time a connection is added or removed. The distribution summary would provide more accurate tracking such as max and average number of connections across an interval of time. The polled meter would not provide that level of detail.

If multiple values are monitored with the same id, then the values will be aggregated and the sum will be reported. For example, registering multiple meters 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PolledMeter.Builder Builder for configuring a polled meter value.

Method Summary

Modifier and Type	Method and Description
static void	monitorMeter(Registry registry, Meter meter) Deprecated. This method only exists to allow for backwards compatibility and should be considered an internal detail. This method is scheduled for removal in a future release.
static void	remove(Registry registry, Id id) Explicitly disable polling for the meter registered with id.
static void	update(Registry registry) Force the polling of all meters associated with the registry.
static IdBuilder<PolledMeter.Builder>	using(Registry registry) Return a builder for configuring a polled meter reporting to the provided registry.

Methods inherited from class java.lang.Object

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

Method Detail

using

public static IdBuilder<PolledMeter.Builder> using(Registry registry)

Return a builder for configuring a polled meter reporting to the provided registry.

Parameters:

registry - Registry that will maintain the state and receive the sampled values for the configured meter.

Returns:

Builder for configuring a polled meter.

update

public static void update(Registry registry)

Force the polling of all meters associated with the registry.

remove

public static void remove(Registry registry,
                          Id id)

Explicitly disable polling for the meter registered with id. This is optional and is mostly used if it is desirable for the meter to go away immediately. The polling will stop automatically when the referred object is garbage collected. See PolledMeter.Builder.monitorValue(Object, ToDoubleFunction) for more information.

monitorMeter

@Deprecated
public static void monitorMeter(Registry registry,
                                            Meter meter)

Deprecated. This method only exists to allow for backwards compatibility and should be considered an internal detail. This method is scheduled for removal in a future release.

Provided for backwards compatibility to support the Registry.register(Meter) method. Use the builder created with using(Registry) instead.