net.centro.rtb.monitoringcenter

Class MonitoringCenter

java.lang.Object

net.centro.rtb.monitoringcenter.MonitoringCenter

public class MonitoringCenter
extends Object

This singleton class is the heart of the MonitoringCenter library. Its responsibilities include

• maintaining overall state of the library
• keeping and reloading configuration parameters
• creating and providing MetricCollector instances
• exposing metrics for pull and push reporting
• registration and execution of health checks
• providing static information about the system (OS and JVM), network node, and application
• and, finally, exposing system (OS and JVM) and Tomcat statuses.

MonitoringCenter is a wrapper around Dropwizard's MetricRegistry and HealthCheckRegistry.

This class must be configured before any application code using it is executed. Thus, it is recommended to run configure(MonitoringCenterConfig) as the first statement in the ContextListener or the main() method (perhaps, right after configuring your logging framework). Please note that MonitoringCenter will configure itself automatically upon calls to getMetricCollector(String, String...) or registerHealthCheck(String, HealthCheck). When configured automatically, the MonitoringCenter will use the default config file as explained in Configurator.defaultConfigFile().

This class is thread-safe.

Method Summary

Modifier and Type	Method and Description
static void	configure(MonitoringCenterConfig config) Configures the MonitoringCenter.
static AppInfo	getAppInfo() Retrieves information about the application, including the application name and build context.
static SortedMap<String,com.codahale.metrics.Counter>	getCountersByNames() Retrieves a sorted map of counters by names.
static SortedMap<String,com.codahale.metrics.Counter>	getCountersByNames(boolean appendPrefix) Retrieves a sorted map of counters by names.
static SortedMap<String,com.codahale.metrics.Counter>	getCountersByNames(boolean appendPrefix, String[] startsWithFilters) Retrieves a sorted map of counters by names.
static MetricCollector	getDatabaseMetricCollector(String... additionalNamespaces) Retrieves a MetricCollector, whose main namespace is "dbs".
static SortedMap<String,com.codahale.metrics.Gauge>	getGaugesByNames() Retrieves a sorted map of gauges by names.
static SortedMap<String,com.codahale.metrics.Gauge>	getGaugesByNames(boolean appendPrefix) Retrieves a sorted map of gauges by names.
static SortedMap<String,com.codahale.metrics.Gauge>	getGaugesByNames(boolean appendPrefix, String[] startsWithFilters) Retrieves a sorted map of gauges by names.
static SortedMap<String,com.codahale.metrics.Histogram>	getHistogramsByNames() Retrieves a sorted map of histograms by names.
static SortedMap<String,com.codahale.metrics.Histogram>	getHistogramsByNames(boolean appendPrefix) Retrieves a sorted map of histograms by names.
static SortedMap<String,com.codahale.metrics.Histogram>	getHistogramsByNames(boolean appendPrefix, String[] startsWithFilters) Retrieves a sorted map of histograms by names.
static SortedMap<String,com.codahale.metrics.Meter>	getMetersByNames() Retrieves a sorted map of meters by names.
static SortedMap<String,com.codahale.metrics.Meter>	getMetersByNames(boolean appendPrefix) Retrieves a sorted map of meters by names.
static SortedMap<String,com.codahale.metrics.Meter>	getMetersByNames(boolean appendPrefix, String[] startsWithFilters) Retrieves a sorted map of meters by names.
static MetricCollector	getMetricCollector(Class<?> clazz, String... namespaces) Retrieves a MetricCollector with a given namespace.
static MetricCollector	getMetricCollector(String mainNamespace, String... additionalNamespaces) Retrieves a MetricCollector with a given namespace.
static SortedMap<String,com.codahale.metrics.Metric>	getMetricsByNames() Retrieves a sorted map of metrics by names.
static SortedMap<String,com.codahale.metrics.Metric>	getMetricsByNames(boolean appendPrefix) Retrieves a sorted map of metrics by names.
static SortedMap<String,com.codahale.metrics.Metric>	getMetricsByNames(boolean appendPrefix, String[] startsWithFilters) Retrieves a sorted map of metrics by names.
static NodeInfo	getNodeInfo() Retrieves information about this network node.
static SystemInfo	getSystemInfo() Retrieves information about the operating system and the JVM.
static SystemStatus	getSystemStatus() Retrieves the current system status, consisting of the operating system and JVM statuses.
static SortedMap<String,com.codahale.metrics.Timer>	getTimersByNames() Retrieves a sorted map of timers by names.
static SortedMap<String,com.codahale.metrics.Timer>	getTimersByNames(boolean appendPrefix) Retrieves a sorted map of timers by names.
static SortedMap<String,com.codahale.metrics.Timer>	getTimersByNames(boolean appendPrefix, String[] startsWithFilters) Retrieves a sorted map of timers by names.
static TomcatStatus	getTomcatStatus() Retrieves the current status for Tomcat's executors and connectors.
static void	registerHealthCheck(String name, com.codahale.metrics.health.HealthCheck healthCheck) Registers a health check.
protected static void	reloadConfig()
static void	removeAllHealthChecks() Removes all registered health checks.
static void	removeAllMetrics() Removes all registered metrics.
static void	removeHealthCheck(String name) Removes a health check, effectively voiding its registration with the MonitoringCenter.
static void	reportMetricsToConsole() Outputs all registered metrics to the standard output stream (System.out).
static void	reportMetricsToLogger(org.slf4j.Logger logger) Outputs all registered metrics to an SLF4J logger.
static com.codahale.metrics.health.HealthCheck.Result	runHealthCheck(String name) Executes a health check and returns its result.
static SortedMap<String,com.codahale.metrics.health.HealthCheck.Result>	runHealthChecks() Executes all registered health checks and returns their results.
static void	shutdown() Shuts the MonitoringCenter down, causing a cascading shutdown on all objects owned by this class.

Methods inherited from class java.lang.Object

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

Method Detail

configure

public static void configure(MonitoringCenterConfig config)

Configures the MonitoringCenter. The idiom of choice for using this method is via static helper methods in the Configurator. This method should be called prior to any other calls to this class.

Parameters:

config - MonitoringCenter configuration.

Throws:

IllegalStateException - if the MonitoringCenter has already been configured.

getMetricCollector

public static MetricCollector getMetricCollector(Class<?> clazz,
                                                 String... namespaces)

Retrieves a MetricCollector with a given namespace. The metric collector's namespace will be constructed from the simple name of the provided class and the optional additional namespaces.

The additional namespaces will be sanitized as described in MetricNamingUtil.join(String, String...).

This method triggers the MonitoringCenter auto-configuration, if the configure(MonitoringCenterConfig) has not been called explicitly.

Parameters:

clazz - class, whose simple name will serve as the main namespace for the metric collector.

namespaces - supplementary namespaces to use for the metric collector.

Returns:

a new or cached metric collector with the provided namespace.

Throws:

NullPointerException - if clazz is null.

getMetricCollector

public static MetricCollector getMetricCollector(String mainNamespace,
                                                 String... additionalNamespaces)

Retrieves a MetricCollector with a given namespace. The metric collector's namespace will be constructed from the main namespace and the optional additional namespaces.

The main namespace will be sanitized in accordance with MetricNamingUtil.sanitize(String). Plus, it cannot be one of the reserved namespaces: "system" and "tomcat". The additional namespaces will be sanitized as described in MetricNamingUtil.join(String, String...).

This method triggers the MonitoringCenter auto-configuration, if the configure(MonitoringCenterConfig) has not been called explicitly.

Parameters:

mainNamespace - main namespace.

additionalNamespaces - supplementary namespaces to use for the metric collector.

Returns:

a new or cached metric collector with the provided namespace.

Throws:

IllegalArgumentException - if mainNamespace is blank.

getDatabaseMetricCollector

public static MetricCollector getDatabaseMetricCollector(String... additionalNamespaces)

Retrieves a MetricCollector, whose main namespace is "dbs". This method is a convenience method for ensuring consistent naming for database-related metrics.

The additional namespaces will be sanitized as described in MetricNamingUtil.join(String, String...).

This method triggers the MonitoringCenter auto-configuration, if the configure(MonitoringCenterConfig) has not been called explicitly.

Parameters:

additionalNamespaces - supplementary namespaces to use for the metric collector.

Returns:

a metric collector, whose main namespace is "dbs".

getCountersByNames

public static SortedMap<String,com.codahale.metrics.Counter> getCountersByNames()

Retrieves a sorted map of counters by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The metric names will not have the node-specific prefix appended.

Returns:

a sorted map of counters by names or an empty map if no counters are found.

getCountersByNames

public static SortedMap<String,com.codahale.metrics.Counter> getCountersByNames(boolean appendPrefix)

Retrieves a sorted map of counters by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending).

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

Returns:

a sorted map of counters by names or an empty map if no counters are found.

getCountersByNames

public static SortedMap<String,com.codahale.metrics.Counter> getCountersByNames(boolean appendPrefix,
                                                                                String[] startsWithFilters)

Retrieves a sorted map of counters by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The retrieved counters have to match the provided filters. These filters can include the MetricNamingUtil.SEPARATOR and multiple wildcards denoted as *.

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

startsWithFilters - an array of filters to apply to names of metrics.

Returns:

a sorted map of counters by names or an empty map if no counters matching the constraints are found.

getMetersByNames

public static SortedMap<String,com.codahale.metrics.Meter> getMetersByNames()

Retrieves a sorted map of meters by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The metric names will not have the node-specific prefix appended.

Returns:

a sorted map of meters by names or an empty map if no meters are found.

getMetersByNames

public static SortedMap<String,com.codahale.metrics.Meter> getMetersByNames(boolean appendPrefix)

Retrieves a sorted map of meters by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending).

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

Returns:

a sorted map of meters by names or an empty map if no meters are found.

getMetersByNames

public static SortedMap<String,com.codahale.metrics.Meter> getMetersByNames(boolean appendPrefix,
                                                                            String[] startsWithFilters)

Retrieves a sorted map of meters by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The retrieved meters have to match the provided filters. These filters can include the MetricNamingUtil.SEPARATOR and multiple wildcards denoted as *.

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

startsWithFilters - an array of filters to apply to names of metrics.

Returns:

a sorted map of meters by names or an empty map if no meters matching the constraints are found.

getHistogramsByNames

public static SortedMap<String,com.codahale.metrics.Histogram> getHistogramsByNames()

Retrieves a sorted map of histograms by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The metric names will not have the node-specific prefix appended.

Returns:

a sorted map of histograms by names or an empty map if no histograms are found.

getHistogramsByNames

public static SortedMap<String,com.codahale.metrics.Histogram> getHistogramsByNames(boolean appendPrefix)

Retrieves a sorted map of histograms by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending).

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

Returns:

a sorted map of histograms by names or an empty map if no histograms are found.

getHistogramsByNames

public static SortedMap<String,com.codahale.metrics.Histogram> getHistogramsByNames(boolean appendPrefix,
                                                                                    String[] startsWithFilters)

Retrieves a sorted map of histograms by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The retrieved histograms have to match the provided filters. These filters can include the MetricNamingUtil.SEPARATOR and multiple wildcards denoted as *.

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

startsWithFilters - an array of filters to apply to names of metrics.

Returns:

a sorted map of histograms by names or an empty map if no histograms matching the constraints are found.

getTimersByNames

public static SortedMap<String,com.codahale.metrics.Timer> getTimersByNames()

Retrieves a sorted map of timers by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The metric names will not have the node-specific prefix appended.

Returns:

a sorted map of timers by names or an empty map if no timers are found.

getTimersByNames

public static SortedMap<String,com.codahale.metrics.Timer> getTimersByNames(boolean appendPrefix)

Retrieves a sorted map of timers by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending).

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

Returns:

a sorted map of timers by names or an empty map if no timers are found.

getTimersByNames

public static SortedMap<String,com.codahale.metrics.Timer> getTimersByNames(boolean appendPrefix,
                                                                            String[] startsWithFilters)

Retrieves a sorted map of timers by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The retrieved timers have to match the provided filters. These filters can include the MetricNamingUtil.SEPARATOR and multiple wildcards denoted as *.

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

startsWithFilters - an array of filters to apply to names of metrics.

Returns:

a sorted map of timers by names or an empty map if no timers matching the constraints are found.

getGaugesByNames

public static SortedMap<String,com.codahale.metrics.Gauge> getGaugesByNames()

Retrieves a sorted map of gauges by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The metric names will not have the node-specific prefix appended.

Returns:

a sorted map of gauges by names or an empty map if no gauges are found.

getGaugesByNames

public static SortedMap<String,com.codahale.metrics.Gauge> getGaugesByNames(boolean appendPrefix)

Retrieves a sorted map of gauges by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending).

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

Returns:

a sorted map of gauges by names or an empty map if no gauges are found.

getGaugesByNames

public static SortedMap<String,com.codahale.metrics.Gauge> getGaugesByNames(boolean appendPrefix,
                                                                            String[] startsWithFilters)

Retrieves a sorted map of gauges by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The retrieved gauges have to match the provided filters. These filters can include the MetricNamingUtil.SEPARATOR and multiple wildcards denoted as *.

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

startsWithFilters - an array of filters to apply to names of metrics.

Returns:

a sorted map of gauges by names or an empty map if no gauges matching the constraints are found.

getMetricsByNames

public static SortedMap<String,com.codahale.metrics.Metric> getMetricsByNames()

Retrieves a sorted map of metrics by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The metric names will not have the node-specific prefix appended.

Returns:

a sorted map of metrics by names or an empty map if no metrics are found.

getMetricsByNames

public static SortedMap<String,com.codahale.metrics.Metric> getMetricsByNames(boolean appendPrefix)

Retrieves a sorted map of metrics by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending).

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

Returns:

a sorted map of metrics by names or an empty map if no metrics are found.

getMetricsByNames

public static SortedMap<String,com.codahale.metrics.Metric> getMetricsByNames(boolean appendPrefix,
                                                                              String[] startsWithFilters)

Retrieves a sorted map of metrics by names. The returned map is sorted in accordance with natural order of metric names (alphabetical ascending). The retrieved metrics have to match the provided filters. These filters can include the MetricNamingUtil.SEPARATOR and multiple wildcards denoted as *.

If appendPrefix is true, the node-specific prefix will be appended to all metric names.

Parameters:

appendPrefix - whether to append the node-specific prefix to names of metrics or not.

startsWithFilters - an array of filters to apply to names of metrics.

Returns:

a sorted map of metrics by names or an empty map if no metrics matching the constraints are found.

removeAllMetrics

public static void removeAllMetrics()

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

reportMetricsToConsole

public static void reportMetricsToConsole()

Outputs all registered metrics to the standard output stream (System.out).

reportMetricsToLogger

public static void reportMetricsToLogger(org.slf4j.Logger logger)

Outputs all registered metrics to an SLF4J logger.

Parameters:

logger - an SLF4J logger to output metrics to.

registerHealthCheck

public static void registerHealthCheck(String name,
                                       com.codahale.metrics.health.HealthCheck healthCheck)

Registers a health check. This method is thread-safe. An attempt to register a health check, which has already been registered will be a no-op. The actual name of the health check may contain a postfix, depending on the value returned by NamingConfig.isAppendTypeToHealthCheckNames().

All illegal characters contained in the provided name will be escaped as documented for MetricNamingUtil.sanitize(String).

This method triggers the MonitoringCenter auto-configuration, if the configure(MonitoringCenterConfig) has not been called explicitly.

Parameters:

name - name of the health check to register.

healthCheck - a health check to register.

Throws:

NullPointerException - if healthCheck is null.

IllegalArgumentException - if name is blank.

runHealthChecks

public static SortedMap<String,com.codahale.metrics.health.HealthCheck.Result> runHealthChecks()

Executes all registered health checks and returns their results. The returned map is sorted in accordance with natural order of health check names (alphabetical ascending).

Returns:

sorted map of results of executed health checks by health check names; an empty map if the MonitoringCenter has not been configured.

runHealthCheck

public static com.codahale.metrics.health.HealthCheck.Result runHealthCheck(String name)

Executes a health check and returns its result. The actual name of the health check may contain a postfix, depending on the value returned by NamingConfig.isAppendTypeToHealthCheckNames().

All illegal characters contained in the provided name will be escaped as documented for MetricNamingUtil.sanitize(String).

Parameters:

name - name of the health check to execute.

Returns:

result of the executed health check.

Throws:

IllegalArgumentException - if name is blank.

NoSuchElementException - if MonitoringCenter has not been configured or if health check could not be found.

removeAllHealthChecks

public static void removeAllHealthChecks()

Removes all registered health checks. This method is especially useful for unit tests.

removeHealthCheck

public static void removeHealthCheck(String name)

Removes a health check, effectively voiding its registration with the MonitoringCenter. The actual name of the health check may contain a postfix, depending on the value returned by NamingConfig.isAppendTypeToHealthCheckNames().

All illegal characters contained in the provided name will be escaped as documented for MetricNamingUtil.sanitize(String).

Parameters:

name - name of the health check to remove.

Throws:

IllegalArgumentException - if name is blank.

getSystemStatus

public static SystemStatus getSystemStatus()

Retrieves the current system status, consisting of the operating system and JVM statuses.

Returns:

the current system status, consisting of the operating system and JVM statuses.

getTomcatStatus

public static TomcatStatus getTomcatStatus()

Retrieves the current status for Tomcat's executors and connectors.

Returns:

the current status for Tomcat's executors and connectors; null if MonitoringCenter has not been configured.

getSystemInfo

public static SystemInfo getSystemInfo()

Retrieves information about the operating system and the JVM.

Returns:

information about the operating system and the JVM; null if MonitoringCenter has not been configured.

getNodeInfo

public static NodeInfo getNodeInfo()

Retrieves information about this network node. In this context, the definition of a node is somewhat loose and generally means any physical or virtual server running one or more applications.

Returns:

information about this network node; null if MonitoringCenter has not been configured.

getAppInfo

public static AppInfo getAppInfo()

Retrieves information about the application, including the application name and build context.

Returns:

information about the application; null if MonitoringCenter has not been configured.

shutdown

public static void shutdown()

Shuts the MonitoringCenter down, causing a cascading shutdown on all objects owned by this class. This method is synchronous and it may block for a few seconds.

reloadConfig

protected static void reloadConfig()