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. So if a metric is created and an input is set and 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 exception. Of course there will be a log warning.

Performance

The MetricRegistry is designed for low overhead metrics. So once a metric is registered, there is no overhead for the provider of the Metric 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 inputs. So it is up to the provider of the metric input how much overhead is required.

Method Summary

<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 If a Metric with the given name already has an input, that input will be overwritten.
<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 annotated with Probe annotation, and registering these fields/methods as metrics.
void	scheduleAtFixedRate(Runnable publisher, long period, TimeUnit timeUnit) Schedules a publisher to be executed at a fixed rate.

Method Detail

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 metrics. If metrics with the same name already exist, there source/inputs will be updated. So multiple registrations if the same object are ignored. 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,
                  LongProbe<S> input)

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

Parameters:

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:

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 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.

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. 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.

Parameters:

name - the name

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 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.