Package com.ocient.metrics

# Class MetricsRegistry

java.lang.Object
com.ocient.metrics.MetricsRegistry

    public class MetricsRegistry
    extends Object

Global Registry for all performance counters.

In the example below I've added both INCREMENTAL_VALUE and INSTANTANEOUS_VALUE performance counters for a queue implementation with add() and poll() methods. The perf counters are used to track:

- Cumulative number of elements processed by the queue (Countertype.INCREMENTAL)
- Cumulative number of bytes processed by the queue (Countertype.INCREMENTAL)
- Cumulative number of elements currently in the queue (Countertype.INSTANTANEOUS)
- Cumulative number of bytes currently consumed by the queue (Countertype.INSTANTANEOUS)

The counters are retrieved from the registry in the ExampleQueue constructor and are removed in the shutdown() method. Unfortunately, we can't rely on object finalization to clean orphaned metrics.

     private static class ExampleQueue {
         PerfCounter m_numElementsProcessed;
         PerfCounter m_numBytesProcessed;
         PerfCounter m_numElements;
         PerfCounter m_numBytesUsed;

         ExampleQueue(final int processingGroup, final int processingCore) {
             // Generate paths for all of the counters
             final List<NamedTag> tags = Arrays.asList(
                 NamedTag.id(Tag.PROCESSING_GROUP, processingGroup),
                 NamedTag.id(Tag.PROCESSING_CORE, processingCore));

             final Path nepPath = Path.create("extractor.exampleQueue.numElementsProcessed", tags);
             final Path nbpPath = Path.create("extractor.exampleQueue.numBytesProcessed", tags);
             final Path cnbPath = Path.create("extractor.exampleQueue.numElements", tags);
             final Path cnePath = Path.create("extractor.exampleQueue.numBytesUsed", tags);

             // Maintain references to these counters to avoid subsequent map lookups
             this.m_numElementsProcessed = MetricsRegistry.instance().getCounter(nepPath, ThreadingModel.NO_CONTENTION, DataType.LONG, CounterType.INCREMENTAL_VALUE, Units.UNITLESS);
             this.m_numBytesProcessed = MetricsRegistry.instance().getCounter(nbpPath, ThreadingModel.NO_CONTENTION, DataType.LONG, CounterType.INCREMENTAL_VALUE, Units.BYTES);
             this.m_numElements = MetricsRegistry.instance().getCounter(cnbPath, ThreadingModel.NO_CONTENTION, DataType.LONG, CounterType.INSTANTANEOUS_VALUE, Units.UNITLESS);
             this.m_numBytesUsed = MetricsRegistry.instance().getCounter(cnePath, ThreadingModel.NO_CONTENTION, DataType.LONG, CounterType.INSTANTANEOUS_VALUE, Units.BYTES);
         }

         void shutdown() {
             MetricsRegistry.instance().removeCounter(this.m_numElementsProcessed.path());
             MetricsRegistry.instance().removeCounter(this.m_numBytesProcessed.path());
             MetricsRegistry.instance().removeCounter(this.m_numElements.path());
             MetricsRegistry.instance().removeCounter(this.m_numBytesUsed.path());
         }

         void add(final Object o) {
             //... store o in memory
             this.m_numElements.incValue(1);
             this.m_numBytesUsed.incValue(getBytes(o));
         }

         Object poll() {
             //... poll object
             this.m_numElements.decValue(1);
             this.m_numBytesUsed.decValue(getBytes(o));
             this.m_numElementsProcessed.incValue(1);
             this.m_numBytesProcessed.incValue(getBytes(o));
             //... return polled object
         }
     }

## Method Summary

Modifier and Type | Method | Description
--- | --- | ---
`void` | `clear()` | Removes all `PerfCounter`s from the registry
`com.ibm.asyncutil.locks.FairAsyncReadWriteLock` | `deferEvictions()` | Returns an `AsyncLock` used to defer removal of metrics from the registry.
`Optional<Metric<?>>` | `find​(Metric.MetricPath path)` | Finds the single `Metric` with the exact given path.
`<R,​ A> R` | `find​(Predicate<Metric<?>> predicate, Collector<Metric<?>,​A,​R> collector)` | Finds the group of `Metric`s that match the given predicate.
`PerfCounter` | `getCounter​(Metric.MetricPath path, PerfCounter.ThreadingModel threadingModel, Metric.DataType dataType, Metric.CounterType counterType, Metric.Units units)` | Fetches a `PerfCounter` or creates one if no such counter exists.
`static MetricsRegistry` | `instance()` |
`void` | `registerGauge​(Gauge gauge)` | Adds the `Gauge` to the global registry
`boolean` | `removeGauge​(Gauge gauge)` | Removes the `Gauge` from the global registry
`void` | `removeIf​(Predicate<Metric<?>> predicate)` | Removes a counter with the given `Metric.MetricPath`.
`void` | `removeMetricsByBase​(String basePath)` | Removes the set of metrics with the given base path.
`Stream<Metric<?>>` | `stream()` |

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Method Details

### instance

public static MetricsRegistry instance()

Returns:
  the global `PerfCounter` registry

### getCounter

public PerfCounter getCounter​(Metric.MetricPath path, PerfCounter.ThreadingModel threadingModel, Metric.DataType dataType, Metric.CounterType counterType, Metric.Units units)
Fetches a `PerfCounter` or creates one if no such counter exists.

For example, to retrieve the counter for "extractor.examplePath" tagged with PROCESSING_GROUP=0:

     final Path path = Path.create("extractor.examplePath", Arrays.asList(NamedTag.id(Tag.PROCESSING_GROUP, 0));
     PerfCounter counter = PerfRegistry.instance().getCounter(path, ThreadingModel.NO_CONTENTION, DataType.LONG, CounterType.INCREMENTAL_VALUE, Units.UNITLESS);

Parameters:
  `path` - the path for the counter, should be unique to this counter
  `threadingModel` - the threading model under which the counter will be mutated
  `dataType` - the data type
  `counterType` - the counter type
  `units` - the units of the value
Returns:
  the `PerfCounter`

### deferEvictions

public com.ibm.asyncutil.locks.FairAsyncReadWriteLock deferEvictions()
Returns an `AsyncLock` used to defer removal of metrics from the registry. Useful when the event ends outside of the reporting interval.

### registerGauge

public void registerGauge​(Gauge gauge)
Adds the `Gauge` to the global registry

Parameters:
  `gauge` - the gauge

### removeGauge

public boolean removeGauge​(Gauge gauge)
Removes the `Gauge` from the global registry

Parameters:
  `gauge` - the gauge
Returns:
  `true` if the gauge was removed

### stream

public Stream<Metric<?>> stream()

Returns:
  a `Stream` of registered metrics

### find

public <R,​ A> R find​(Predicate<Metric<?>> predicate, Collector<Metric<?>,​A,​R> collector)
Finds the group of `Metric`s that match the given predicate.

Parameters:
  `predicate` - a non-interfering, stateless predicate to apply to each element to determine if it should be included
  `collector` - a path to the desired metric
Returns:
  the `Metric` if it exists, otherwise `Optional.empty()`

### find

public Optional<Metric<?>> find​(Metric.MetricPath path)
Finds the single `Metric` with the exact given path.

Parameters:
  `path` - a path to the desired metric
Returns:
  the `Metric` if it exists, otherwise `Optional.empty()`

### removeIf

public void removeIf​(Predicate<Metric<?>> predicate)
Removes a counter with the given `Metric.MetricPath`.

Parameters:
  `predicate` - a non-interfering, stateless predicate to apply to each element to determine if it should be removed

### removeMetricsByBase

public void removeMetricsByBase​(String basePath)
Removes the set of metrics with the given base path.

Parameters:
  `basePath` - the base path of the metrics

### clear

public void clear()
Removes all `PerfCounter`s from the registry