com.hazelcast.internal.metrics

Interface MetricsRegistry

All Known Implementing Classes:

MetricsRegistryImpl

public interface MetricsRegistry

The MetricsRegistry is responsible for recording all kinds of Hazelcast/JVM specific information to help out with issues like performance or stability problems. Each HazelcastInstance has its own MetricsRegistry instance. A MetricsRegistry can contain many Probe instances. A probe is registered under a certain name, and can be read by creating a Gauge, see newLongGauge(String). This name can be any string, e.g.:

1. proxy.count
2. operation.completed.count
3. operation.partition[14].count

For the time being there the MetricsRegistry doesn't require any syntax for the name content; so any String is fine.

Duplicate Registrations

The MetricsRegistry is lenient regarding duplicate registrations of probes. So if there is an existing probe for a given name and a new probe with the same name is registered, the old probe is overwritten. The reason to be lenient is that the MetricRegistry should not throw exception. Of course there will be a log warning.

Performance

The MetricRegistry is designed for low overhead probes. So once a probe is registered, there is no overhead for the provider of the probe data. The provider could have for example a volatile long field and increment this using a lazy-set. As long as the MetricRegistry can frequently read out this field, the MetricRegistry is perfectly happy with such low overhead probes. So it is up to the provider of the probe how much overhead is required.

Method Summary

Modifier and Type	Method and Description
void	collectMetrics(Object... objects) For each object that implements MetricsProvider the MetricsProvider.provideMetrics(MetricsRegistry) is called.
<S> void	deregister(S source) Deregisters all probes for a given source object.
void	discardMetrics(Object... objects) For each object that implements DiscardableMetricsProvider the DiscardableMetricsProvider.discardMetrics(MetricsRegistry) is called.
Set<String>	getNames() Gets a set of all current probe names.
ProbeLevel	minimumLevel() Returns the minimum ProbeLevel this MetricsRegistry is recording.
DoubleGauge	newDoubleGauge(String name) Creates a DoubleGauge for a given metric name.
LongGauge	newLongGauge(String name) Creates a LongGauge for a given metric name.
<S> void	register(S source, String name, ProbeLevel level, DoubleProbeFunction<S> probe) Registers a probe If a probe for the given name exists, it will be overwritten.
<S> void	register(S source, String name, ProbeLevel level, LongProbeFunction<S> probe) Registers a probe.
void	render(ProbeRenderer renderer) Renders the content of the MetricsRegistry.
<S> void	scanAndRegister(S source, String namePrefix) Scans the source object for any fields/methods that have been annotated with Probe annotation, and registering these fields/methods as probes instances.
void	scheduleAtFixedRate(Runnable publisher, long period, TimeUnit timeUnit) Schedules a publisher to be executed at a fixed rate.

Method Detail

minimumLevel

ProbeLevel minimumLevel()

Returns the minimum ProbeLevel this MetricsRegistry is recording.

newLongGauge

LongGauge newLongGauge(String name)

Creates a LongGauge for a given metric name. If no gauge exists for the name, it will be created but no probe is set. The reason to do so is that you don't want to depend on the order of registration. Perhaps you want to read out e.g. operations.count gauge, but the OperationService has not started yet and the metric is not yet available. Another cause is that perhaps a probe is not registered, but the metric is created. For example when experimenting with a new implementation, e.g. a new OperationService implementation, that doesn't provide the operation.count probe. Multiple calls with the same name, return different Gauge instances; so the Gauge instance is not cached. This is done to prevent memory leaks.

Parameters:

name - the name of the metric.

Returns:

the created LongGauge.

Throws:

NullPointerException - if name is null.

newDoubleGauge

DoubleGauge newDoubleGauge(String name)

Creates a DoubleGauge for a given metric name.

Parameters:

name - name of the metric

Returns:

the create DoubleGauge

Throws:

NullPointerException - if name is null.

See Also:

newLongGauge(String)

getNames

Set<String> getNames()

Gets a set of all current probe names. The returned set is immutable and is a snapshot of the names. So the reader gets a stable view on the names.

Returns:

set of all current names.

scanAndRegister

<S> void scanAndRegister(S source,
                         String namePrefix)

Scans the source object for any fields/methods that have been annotated with Probe annotation, and registering these fields/methods as probes instances. If a probe is called, 'queueSize' and the namePrefix is 'operations, then the name of the probe-instance is 'operations.queueSize'. If probes with the same name already exist, then the probes are replaced. If an object has no @Gauge annotations, the call is ignored.

Parameters:

source - the object to scan.

namePrefix - the name prefix.

Throws:

NullPointerException - if namePrefix or source is null.

IllegalArgumentException - if the source contains Gauge annotation on a field/method of unsupported type.

register

<S> void register(S source,
                  String name,
                  ProbeLevel level,
                  LongProbeFunction<S> probe)

Registers a probe. If a probe for the given name exists, it will be overwritten.

Parameters:

name - the name of the probe.

level - the ProbeLevel

probe - the probe

Throws:

NullPointerException - if source, name, level or probe is null.

register

<S> void register(S source,
                  String name,
                  ProbeLevel level,
                  DoubleProbeFunction<S> probe)

Registers a probe If a probe for the given name exists, it will be overwritten.

Parameters:

name - the name of the probe

level - the ProbeLevel

probe - the probe

Throws:

NullPointerException - if source, name, level or probe is null.

deregister

<S> void deregister(S source)

Deregisters all probes for a given source object. If the object already is deregistered, the call is ignored. If the object was never registered, the call is ignored.

Parameters:

source - the object to deregister. If called with null, then ignored.

scheduleAtFixedRate

void scheduleAtFixedRate(Runnable publisher,
                         long period,
                         TimeUnit timeUnit)

Schedules a publisher to be executed at a fixed rate. Probably this method will be removed in the future, but we need a mechanism for complex gauges that require some calculation to provide their values.

Parameters:

publisher - the published task that needs to be executed

period - the time between executions

timeUnit - the timeunit for period

Throws:

NullPointerException - if publisher or timeUnit is null.

render

void render(ProbeRenderer renderer)

Renders the content of the MetricsRegistry.

Parameters:

renderer - the ProbeRenderer

Throws:

NullPointerException - if renderer is null.

collectMetrics

void collectMetrics(Object... objects)

For each object that implements MetricsProvider the MetricsProvider.provideMetrics(MetricsRegistry) is called.

Parameters:

objects - the array of objects to initialize.

discardMetrics

void discardMetrics(Object... objects)

For each object that implements DiscardableMetricsProvider the DiscardableMetricsProvider.discardMetrics(MetricsRegistry) is called.

Parameters:

objects - the array of objects to check.