com.hazelcast.internal.metrics

Interface MetricsRegistry

All Known Implementing Classes:

MetricsRegistryImpl

public interface MetricsRegistry

The MetricsRegistry is a registry of various Hazelcast/JVM internal information to help out with debugging, performance or stability issues. Each HazelcastInstance has one local MetricsRegistry instance.

A MetricsRegistry can contain many Probe instances. A probe is registered under a name, and can be read by creating a Gauge, see newLongGauge(String).

The name has this form:

     [tag1=foo,tag2=bar,...]
 

Special characters in values must be escaped, use ProbeBuilder to register metrics with properly escaped values.

The metrics registry doesn't interpret the name in any way, it is treated as is. For example, [tag1=foo,tag2=bar] and [tag2=bar,tag1=foo] will be treated as two different metrics even though they have same tags and values. Clients making use of the metrics can use the tags. For backwards compatibility, the name does not have to be enclosed in [].

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.
ProbeBuilder	newProbeBuilder() Creates a new ProbeBuilder.
<S> void	register(S source, String name, ProbeLevel level, DoubleProbeFunction<S> probe) Registers a probe.
<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 registers these fields/methods as probe 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 registers these fields/methods as probe instances.

If a probe is called 'queueSize' and the namePrefix is 'operations', then the name of the probe instance is 'operations.queueSize'.

If a probe with the same name already exists, then the probe is replaced.

If an object has no @Probe 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 a Probe 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 time unit 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.

newProbeBuilder

ProbeBuilder newProbeBuilder()

Creates a new ProbeBuilder.