net.centro.rtb.monitoringcenter

Interface MetricCollector

public interface MetricCollector

This interface is responsible for providing clients of the MonitoringCenter with methods for collecting metrics under a particular namespace. MetricCollector is analogous to a logger retrieved from SLF4J's LoggerFactory. As such, a typical idiom for instantiating a MetricCollector is:

 private static final MetricCollector metricCollector = MonitoringCenter.getMetricCollector(SampleService.class);
 

In addition to the ability to instantiate or retrieve Dropwizard's Metric implementations (e.g., Counter), this interface exposes high-level methods for registering and instrumenting collections, maps, caches, executors, and data sources. The instrumentation methods return a proxy instance that has to be employed in lieu of the original instance.

All metrics registered within a MetricCollector are prefixed with its namespace (defined when retrieving a MetricCollector instance from MonitoringCenter; see MonitoringCenter.getMetricCollector(String, String...)). A MetricCollector also enforces a metric naming policy specified in the MonitoringCenter's configuration (see MetricNamePostfixPolicy). Thus, a histogram named "foo" may be registered as "fooHistogram", given an appropriate MetricNamePostfixPolicy (e.g., MetricNamePostfixPolicy.ADD_COMPOSITE_TYPES).

In other words, all metrics registered with a MetricCollector will follow the naming schema below:

[MetricCollector's namespace].[name].[additionalNames][postfix as dictated by the MetricNamePostfixPolicy] ,

where "." is the separator character expressed by MetricNamingUtil.SEPARATOR.

For instance, getMeter("requests", "errors", "400") registered with a MetricCollector named "SampleServlet" and given MetricNamePostfixPolicy.ADD_COMPOSITE_TYPES, will yield a meter named "SampleServlet.requests.errors.400Meter".

Note that the node-specific prefix (such as "bidder.east.lb10-p2e.114") is appended on demand during the reporting stage.

MetricCollector abstracts away all the naming intricacies mentioned above, allowing the client to simply reference a metric by its short name ("coins" vs "SampleService.coinsMeter").

Method Summary

Modifier and Type	Method and Description
com.codahale.metrics.Counter	getCounter(String topLevelName, String... additionalNames) Retrieves a counter, creating it if one does not exist.
com.codahale.metrics.Histogram	getHistogram(String topLevelName, String... additionalNames) Retrieves a histogram, creating it if one does not exist.
com.codahale.metrics.Meter	getMeter(String topLevelName, String... additionalNames) Retrieves a meter, creating it if one does not exist.
com.codahale.metrics.Timer	getTimer(String topLevelName, String... additionalNames) Retrieves a timer, creating it if one does not exist.
<T> BlockingQueue<T>	instrumentBlockingQueue(BlockingQueue<T> blockingQueue, String topLevelName, String... additionalNames) Instruments a BlockingQueue.
DataSource	instrumentDataSource(DataSource dataSource, String topLevelName, String... additionalNames) Instruments a DataSource, exposing the distribution of connection acquisition times.
ExecutorService	instrumentExecutorService(ExecutorService executorService, String topLevelName, String... additionalNames) Instruments an ExecutorService.
ScheduledExecutorService	instrumentScheduledExecutorService(ScheduledExecutorService scheduledExecutorService, String topLevelName, String... additionalNames) Instruments a ScheduledExecutorService.
void	registerC3P0DataSource(com.mchange.v2.c3p0.PooledDataSource pooledDataSource, String topLevelName, String... additionalNames) Registers a C3P0 pool with the MetricCollector, exposing as gauges its various data points for connections, threads, and statement cache.
void	registerCollection(Collection<?> collection, String topLevelName, String... additionalNames) Registers a Collection with the MetricCollector, exposing its size as a gauge.
<T> void	registerGauge(com.codahale.metrics.Gauge<T> gauge, String topLevelName, String... additionalNames) Registers a gauge.
void	registerGuavaCache(com.google.common.cache.Cache<?,?> cache, String topLevelName, String... additionalNames) Registers a Guava Cache with the MetricCollector, exposing its size and stats as gauges.
void	registerMap(Map<?,?> map, String topLevelName, String... additionalNames) Registers a Map with the MetricCollector, exposing its size as a gauge.
void	registerMetric(com.codahale.metrics.Metric metric, String topLevelName, String... additionalNames) Registers a metric.
void	registerMetricSet(com.codahale.metrics.MetricSet metricSet, String... names) Registers all metrics contained in a MetricSet.
void	removeAll() Removes all metrics registered within this MetricCollector.
void	removeMetric(com.codahale.metrics.Metric metric, String topLevelName, String... additionalNames) Removes a metric from the MetricCollector, voiding its registration with the MonitoringCenter.
void	removeMetricSet(com.codahale.metrics.MetricSet metricSet, String... names) Removes a metric set, effectively removing all metrics contained in it.
void	replaceMetric(com.codahale.metrics.Metric metric, String topLevelName, String... additionalNames) Replaces an existing metric with a new metric under the same name.

Method Detail

getCounter

com.codahale.metrics.Counter getCounter(String topLevelName,
                                        String... additionalNames)

Retrieves a counter, creating it if one does not exist. This method is thread-safe. The actual name of the counter registered with the MonitoringCenter will be prefixed with MetricCollector's namespace and, possibly, postfixed with the type of the metric (i.e., Counter). The postfix enforcement is controlled by the MetricNamePostfixPolicy configured in the MonitoringCenter.
All illegal characters contained in the provided name parts will be escaped as documented for MetricNamingUtil.join(String, String...).

Parameters:

topLevelName - top-level part of the counter's name.

additionalNames - additional parts of the counter's name.

Returns:

a new or existing counter.

Throws:

IllegalArgumentException - if top-level part of the name is blank.

getTimer

com.codahale.metrics.Timer getTimer(String topLevelName,
                                    String... additionalNames)

Retrieves a timer, creating it if one does not exist. This method is thread-safe. The actual name of the timer registered with the MonitoringCenter will be prefixed with MetricCollector's namespace and, possibly, postfixed with the type of the metric (i.e., Timer). The postfix enforcement is controlled by the MetricNamePostfixPolicy configured in the MonitoringCenter.
All illegal characters contained in the provided name parts will be escaped as documented for MetricNamingUtil.join(String, String...).

Parameters:

topLevelName - top-level part of the timer's name.

additionalNames - additional parts of the timer's name.

Returns:

a new or existing timer.

Throws:

IllegalArgumentException - if top-level part of the name is blank.

getMeter

com.codahale.metrics.Meter getMeter(String topLevelName,
                                    String... additionalNames)

Retrieves a meter, creating it if one does not exist. This method is thread-safe. The actual name of the meter registered with the MonitoringCenter will be prefixed with MetricCollector's namespace and, possibly, postfixed with the type of the metric (i.e., Meter). The postfix enforcement is controlled by the MetricNamePostfixPolicy configured in the MonitoringCenter.
All illegal characters contained in the provided name parts will be escaped as documented for MetricNamingUtil.join(String, String...).

Parameters:

topLevelName - top-level part of the meter's name.

additionalNames - additional parts of the meter's name.

Returns:

a new or existing meter.

Throws:

IllegalArgumentException - if top-level part of the name is blank.

getHistogram

com.codahale.metrics.Histogram getHistogram(String topLevelName,
                                            String... additionalNames)

Retrieves a histogram, creating it if one does not exist. This method is thread-safe. The actual name of the histogram registered with the MonitoringCenter will be prefixed with MetricCollector's namespace and, possibly, postfixed with the type of the metric (i.e., Histogram). The postfix enforcement is controlled by the MetricNamePostfixPolicy configured in the MonitoringCenter.
All illegal characters contained in the provided name parts will be escaped as documented for MetricNamingUtil.join(String, String...).

Parameters:

topLevelName - top-level part of the histogram's name.

additionalNames - additional parts of the histogram's name.

Returns:

a new or existing histogram.

Throws:

IllegalArgumentException - if top-level part of the name is blank.

registerGauge

<T> void registerGauge(com.codahale.metrics.Gauge<T> gauge,
                       String topLevelName,
                       String... additionalNames)

Registers a gauge. This method is thread-safe. An attempt to register a gauge, which has already been registered will result in an IllegalArgumentException. The actual name of the gauge registered with the MonitoringCenter will be prefixed with MetricCollector's namespace and, possibly, postfixed with the type of the metric (i.e., Gauge). The postfix enforcement is controlled by the MetricNamePostfixPolicy configured in the MonitoringCenter.
All illegal characters contained in the provided name parts will be escaped as documented for MetricNamingUtil.join(String, String...).

Type Parameters:

T - type of the value returned by the gauge.

Parameters:

gauge - a gauge to register.

topLevelName - top-level part of the gauge's name.

additionalNames - additional parts of the gauge's name.

Throws:

NullPointerException - if gauge is null.

IllegalArgumentException - if top-level part of the name is blank.

IllegalArgumentException - if a gauge with the same name has already been registered.

registerMetric

void registerMetric(com.codahale.metrics.Metric metric,
                    String topLevelName,
                    String... additionalNames)

Registers a metric. This method is thread-safe. An attempt to register a metric, which has already been registered will result in an IllegalArgumentException. The actual name of the metric registered with the MonitoringCenter will be prefixed with MetricCollector's namespace and, possibly, postfixed with the type of the metric (e.g., Counter). The postfix enforcement is controlled by the MetricNamePostfixPolicy configured in the MonitoringCenter.
All illegal characters contained in the provided name parts will be escaped as documented for MetricNamingUtil.join(String, String...).

Parameters:

metric - a metric to register.

topLevelName - top-level part of the metric's name.

additionalNames - additional parts of the metric's name.

Throws:

NullPointerException - if metric is null.

IllegalArgumentException - if top-level part of the name is blank.

IllegalArgumentException - if a metric with the same name has already been registered.

registerMetricSet

void registerMetricSet(com.codahale.metrics.MetricSet metricSet,
                       String... names)

Registers all metrics contained in a MetricSet. If no name is provided, individual metrics will be registered under the MetricCollector's namespace (as if registered by registerMetric(Metric, String, String...)). If a name is specified for the MetricSet, it will be employed as a namespace for all individual metrics registered as a result of this method. Thus, the actual name of the individual metrics registered with the MonitoringCenter will be prefixed with MetricCollector's namespace, MetricSet's namespace, and then, possibly, postfixed with the type of the metric (e.g., Counter). The postfix enforcement is controlled by the MetricNamePostfixPolicy configured in the MonitoringCenter.
All illegal characters contained in the provided name parts will be escaped as documented for MetricNamingUtil.join(String, String...).

Parameters:

metricSet - a metric set to register.

names - optional name parts that form the namespace for metrics in the metric set.

Throws:

NullPointerException - if metricSet is null.

removeAll

void removeAll()

Removes all metrics registered within this MetricCollector. This method is especially useful for unit tests.

removeMetric

void removeMetric(com.codahale.metrics.Metric metric,
                  String topLevelName,
                  String... additionalNames)

Removes a metric from the MetricCollector, voiding its registration with the MonitoringCenter. This method is thread-safe. The name of the metric to remove will be computed in accordance with the logic documented for registerMetric(Metric, String, String...).

Parameters:

metric - a metric to remove.

topLevelName - top-level part of the metric's name.

additionalNames - additional parts of the metric's name.

Throws:

NullPointerException - if metric is null.

IllegalArgumentException - if top-level part of the name is blank.

removeMetricSet

void removeMetricSet(com.codahale.metrics.MetricSet metricSet,
                     String... names)

Removes a metric set, effectively removing all metrics contained in it. This method acts as the counterpart of registerMetricSet(MetricSet, String...).

Parameters:

metricSet - a metric set to remove.

names - optional name parts that form the namespace for metrics in the metric set.

Throws:

NullPointerException - if metricSet is null.

replaceMetric

void replaceMetric(com.codahale.metrics.Metric metric,
                   String topLevelName,
                   String... additionalNames)

Replaces an existing metric with a new metric under the same name. Effectively, this is a convenience method for combining removing and registering a metric.

Parameters:

metric - a metric to replace the existing metric with.

topLevelName - top-level part of the metric's name.

additionalNames - additional parts of the metric's name.

Throws:

NullPointerException - if metric is null.

IllegalArgumentException - if top-level part of the name is blank.

See Also:

registerMetric(Metric, String, String...), removeMetric(Metric, String, String...)

registerCollection

void registerCollection(Collection<?> collection,
                        String topLevelName,
                        String... additionalNames)

Registers a Collection with the MetricCollector, exposing its size as a gauge.

Parameters:

collection - a collection to register.

topLevelName - top-level part of the collection's name.

additionalNames - additional parts of the collection's name.

Throws:

NullPointerException - if collection is null.

IllegalArgumentException - if top-level part of the name is blank.

registerMap

void registerMap(Map<?,?> map,
                 String topLevelName,
                 String... additionalNames)

Registers a Map with the MetricCollector, exposing its size as a gauge.

Parameters:

map - a map to register.

topLevelName - top-level part of the map's name.

additionalNames - additional parts of the map's name.

Throws:

NullPointerException - if map is null.

IllegalArgumentException - if top-level part of the name is blank.

registerGuavaCache

void registerGuavaCache(com.google.common.cache.Cache<?,?> cache,
                        String topLevelName,
                        String... additionalNames)

Registers a Guava Cache with the MetricCollector, exposing its size and stats as gauges.

Parameters:

cache - a cache to register.

topLevelName - top-level part of the cache's name.

additionalNames - additional parts of the cache's name.

Throws:

NullPointerException - if cache is null.

IllegalArgumentException - if top-level part of the name is blank.

See Also:

Cache.stats()

registerC3P0DataSource

void registerC3P0DataSource(com.mchange.v2.c3p0.PooledDataSource pooledDataSource,
                            String topLevelName,
                            String... additionalNames)

Registers a C3P0 pool with the MetricCollector, exposing as gauges its various data points for connections, threads, and statement cache.

Parameters:

pooledDataSource - a C3P0 data source to register.

topLevelName - top-level part of the data source's name.

additionalNames - additional parts of the data source's name.

Throws:

NullPointerException - if pooledDataSource is null.

IllegalArgumentException - if top-level part of the name is blank.

instrumentBlockingQueue

<T> BlockingQueue<T> instrumentBlockingQueue(BlockingQueue<T> blockingQueue,
                                             String topLevelName,
                                             String... additionalNames)

Instruments a BlockingQueue. This method registers the blocking queue with the MetricCollector, exposing its size and capacity as gauges.

Type Parameters:

T - type of the elements of the blocking queue.

Parameters:

blockingQueue - a blocking queue to instrument.

topLevelName - top-level part of the blocking queue's name.

additionalNames - additional parts of the blocking queue's name.

Returns:

a possibly proxied instance of the passed in blocking queue.

Throws:

NullPointerException - if blockingQueue is null.

IllegalArgumentException - if top-level part of the name is blank.

instrumentExecutorService

ExecutorService instrumentExecutorService(ExecutorService executorService,
                                          String topLevelName,
                                          String... additionalNames)

Instruments an ExecutorService. This method creates a proxy of a given executor service, exposing its various statistics under this MetricCollector.

Parameters:

executorService - an executor service to instrument.

topLevelName - top-level part of the executor service's name.

additionalNames - additional parts of the executor service's name.

Returns:

a proxied instance of the passed in executor service.

Throws:

NullPointerException - if executorService is null.

IllegalArgumentException - if top-level part of the name is blank.

instrumentScheduledExecutorService

ScheduledExecutorService instrumentScheduledExecutorService(ScheduledExecutorService scheduledExecutorService,
                                                            String topLevelName,
                                                            String... additionalNames)

Instruments a ScheduledExecutorService. This method creates a proxy of a given scheduled executor service, exposing its various statistics under this MetricCollector.

Parameters:

scheduledExecutorService - a scheduled executor service to instrument.

topLevelName - top-level part of the scheduled executor service's name.

additionalNames - additional parts of the scheduled executor service's name.

Returns:

a proxied instance of the passed in scheduled executor service.

Throws:

NullPointerException - if scheduledExecutorService is null.

IllegalArgumentException - if top-level part of the name is blank.

instrumentDataSource

DataSource instrumentDataSource(DataSource dataSource,
                                String topLevelName,
                                String... additionalNames)

Instruments a DataSource, exposing the distribution of connection acquisition times.

Parameters:

dataSource - a data source to instrument.

topLevelName - top-level part of the data source's name.

additionalNames - additional parts of the data source's name.

Returns:

a proxied instance of the passed in data source.

Throws:

NullPointerException - if dataSource is null.

IllegalArgumentException - if top-level part of the name is blank.