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 all kinds of issues. Each HazelcastInstance has its own MetricsRegistry. A MetricsRegistry can contain many Metric instances. Each metric has an input and each metric can be identified using a name; a String. This name can be any string, the general structure is something like:

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 metrics. If a metric is created and an input is set, and then a new registration for the same Metric is done, the old input/source is overwritten. The reason to be lenient is that the MetricRegistry should not throw exceptions. Of course, there will be a log warning.

Performance

The MetricRegistry is designed for low overhead metrics. Once a metric is registered, there is no overhead for the provider of the Metric data. For example, the provider could have 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 inputs. It is up to the provider of the metric input to determine how much overhead is required.

Method Summary

Methods

Modifier and Type	Method and Description
<S> void	deregister(S source) Deregisters and scans object with probe annotations.
Gauge	getGauge(String name) Gets the Gauge for a given name.
Set<String>	getNames() Gets a set of all current metric names.
int	modCount() Returns the modCount.
<S> void	register(S source, String name, DoubleProbe<S> input) Registers a probe.
<S> void	register(S source, String name, LongProbe<S> input) Registers a probe.
<S> void	scanAndRegister(S source, String namePrefix) Scans the source object for any fields/methods that have been given a name prefix with Probe annotation, and registering these fields/methods as metrics.
void	scheduleAtFixedRate(Runnable publisher, long period, TimeUnit timeUnit) Schedules a publisher to be periodically executed.

Method Detail

scanAndRegister

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

Scans the source object for any fields/methods that have been given a name prefix with Probe annotation, and registering these fields/methods as metrics. If metrics with the same name already exist, their source/inputs will be updated. Multiple registrations of the same object are ignored. If an object has no @Gauge annotations, the call is ignored.

Parameters:

source - the source object to scan.

namePrefix - search the source object for fields/methods that have this 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,
                LongProbe<S> input)

Registers a probe. If a Metric with the given name already has an input, that input will be overwritten.

Parameters:

source - the source object.

name - the name of the metric.

input - the input for the metric.

Throws:

NullPointerException - if source, name or input is null.

register

<S> void register(S source,
                String name,
                DoubleProbe<S> input)

Registers a probe. If a Metric with the given name already has an input, that input will be overwritten.

Parameters:

source - the source object.

name - the name of the metric.

input - the input for the metric.

Throws:

NullPointerException - if name or input is null.

deregister

<S> void deregister(S source)

Deregisters and scans object with probe annotations. All metrics that were for this given source object are removed. 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.

Throws:

NullPointerException - if source is null.

scheduleAtFixedRate

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

Schedules a publisher to be periodically executed. 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 periodically executed.

period - the time between executions.

timeUnit - the timeunit for period.

Throws:

NullPointerException - if publisher or timeUnit is null.

getGauge

Gauge getGauge(String name)

Gets the Gauge for a given name. If no gauge exists for the name, it will be created but no input is set. The reason to do so is that you don't want to depend on the order of registration. For example, you want to read out operations.count gauge, but the OperationService has not started yet and the metric is not yet available.

Parameters:

name - the name of the gauge to get.

Returns:

the Gauge. Multiple calls with the same name, return the same Metric instance.

Throws:

NullPointerException - if name is null.

getNames

Set<String> getNames()

Gets a set of all current metric names.

Returns:

set of all current metric names.

modCount

int modCount()

Returns the modCount. Every time a Metric is added or removed, the modCount is increased. Returned modCount will always be equal or larger than 0.

Returns:

the modCount: the number of times Metrics are added or removed.