public final class PolledMeter extends Object
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.
Modifier and Type | Class and Description |
---|---|
static class |
PolledMeter.Builder
Builder for configuring a polled meter value.
|
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 ScheduledFuture<?> |
poll(Registry registry,
Runnable f)
Poll by executing
f.accept(registry) using the default thread pool for polling
gauges at the default frequency configured for the registry. |
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.
|
public static IdBuilder<PolledMeter.Builder> using(Registry registry)
registry
- Registry that will maintain the state and receive the sampled values for the
configured meter.public static void update(Registry registry)
public static void remove(Registry registry, Id id)
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.public static ScheduledFuture<?> poll(Registry registry, Runnable f)
f.accept(registry)
using the default thread pool for polling
gauges at the default frequency configured for the registry. If more customization is
needed, then it can be done by using a ScheduledExecutorService
directly and
updating meters in the registry. The common use-case is being able to update multiple
meters based on sampling a single time.
The provided function must be thread safe and cheap to execute. Expensive operations, including any IO or network calls, should not be performed inline. Assume that the function will be called frequently and may be called concurrently.
registry
- Registry that will maintain the state and receive the sampled values for the
configured meter.f
- Function to call to update the registry.@Deprecated public static void monitorMeter(Registry registry, Meter meter)
Registry.register(Meter)
method. Use the builder created with using(Registry)
instead.