org.apache.solr.metrics

Class SolrMetricManager

java.lang.Object

org.apache.solr.metrics.SolrMetricManager

public class SolrMetricManager
extends Object

This class maintains a repository of named MetricRegistry instances, and provides several helper methods for managing various aspects of metrics reporting:

• registry creation, clearing and removal,
• creation of most common metric implementations,
• management of SolrMetricReporter-s specific to a named registry.

MetricRegistry instances are automatically created when first referenced by name. Similarly, instances of Metric implementations, such as Meter, Counter, Timer and Histogram are automatically created and registered under hierarchical names, in a specified registry, when meter(String, String, String...) and other similar methods are called.

This class enforces a common prefix (REGISTRY_NAME_PREFIX) in all registry names.

Solr uses several different registries for collecting metrics belonging to different groups, using SolrInfoMBean.Group as the main name of the registry (plus the above-mentioned prefix). Instances of SolrMetricManager are created for each CoreContainer, and most registries are local to each instance, with the exception of two global registries: solr.jetty and solr.jvm, which are shared between all CoreContainer-s

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SolrMetricManager.AndFilter
static class	SolrMetricManager.OrFilter
static class	SolrMetricManager.PrefixFilter An implementation of MetricFilter that selects metrics with names that start with one of prefixes.
static class	SolrMetricManager.RegexFilter An implementation of MetricFilter that selects metrics with names that match regular expression patterns.

Field Summary

Fields

Modifier and Type	Field and Description
static String	JETTY_REGISTRY Registry name for Jetty-specific metrics.
static String	JVM_REGISTRY Registry name for JVM-specific metrics.
static String	REGISTRY_NAME_PREFIX Common prefix for all registry names that Solr uses.

Constructor Summary

Constructors

Constructor and Description
SolrMetricManager()

Method Summary

Modifier and Type	Method and Description
Set<String>	clearMetrics(String registry, String... metricPath) Remove some metrics from a named registry
void	clearRegistry(String registry) Remove all metrics from a specified registry.
boolean	closeReporter(String registry, String name) Close and unregister a named SolrMetricReporter for a registry.
Set<String>	closeReporters(String registry) Close and unregister all SolrMetricReporter-s for a registry.
com.codahale.metrics.Counter	counter(String registry, String metricName, String... metricPath) Create or get an existing named Counter
static String	enforcePrefix(String name) Enforces the leading REGISTRY_NAME_PREFIX in a name.
static String	getRegistryName(SolrInfoMBean.Group group, String... names) Helper method to construct a properly prefixed registry name based on the group.
Map<String,SolrMetricReporter>	getReporters(String registry) Get a map of reporters for a registry.
com.codahale.metrics.Histogram	histogram(String registry, String metricName, String... metricPath) Create or get an existing named Histogram
void	loadReporter(String registry, SolrResourceLoader loader, PluginInfo pluginInfo) Create and register an instance of SolrMetricReporter.
void	loadReporters(PluginInfo[] pluginInfos, SolrResourceLoader loader, SolrInfoMBean.Group group, String... registryNames) Create and register SolrMetricReporter-s specific to a SolrInfoMBean.Group.
com.codahale.metrics.Meter	meter(String registry, String metricName, String... metricPath) Create or get an existing named Meter
static String	mkName(String name, String... path) This method creates a hierarchical name with arbitrary levels of hierarchy
static String	overridableRegistryName(String registry) Allows named registries to be renamed using System properties.
void	register(String registry, com.codahale.metrics.Metric metric, boolean force, String metricName, String... metricPath) Register an instance of Metric.
void	registerAll(String registry, com.codahale.metrics.MetricSet metrics, boolean force, String... metricPath) Register all metrics in the provided MetricSet, optionally skipping those that already exist.
void	registerGauge(String registry, com.codahale.metrics.Gauge<?> gauge, boolean force, String metricName, String... metricPath)
com.codahale.metrics.MetricRegistry	registry(String registry) Get (or create if not present) a named registry
Set<String>	registryNames() Return a set of existing registry names.
Set<String>	registryNames(Pattern... patterns)
Set<String>	registryNames(String... patterns) Return set of existing registry names that match a regex pattern
void	removeRegistry(String registry) Remove a named registry.
void	swapRegistries(String registry1, String registry2) Swap registries.
com.codahale.metrics.Timer	timer(String registry, String metricName, String... metricPath) Create or get an existing named Timer

Methods inherited from class java.lang.Object

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

Field Detail

REGISTRY_NAME_PREFIX

public static final String REGISTRY_NAME_PREFIX

Common prefix for all registry names that Solr uses.

See Also:

Constant Field Values

JETTY_REGISTRY

public static final String JETTY_REGISTRY

Registry name for Jetty-specific metrics. This name is also subject to overrides controlled by system properties. This registry is shared between instances of SolrMetricManager.

JVM_REGISTRY

public static final String JVM_REGISTRY

Registry name for JVM-specific metrics. This name is also subject to overrides controlled by system properties. This registry is shared between instances of SolrMetricManager.

Constructor Detail

SolrMetricManager

public SolrMetricManager()

Method Detail

registryNames

public Set<String> registryNames()

Return a set of existing registry names.

registryNames

public Set<String> registryNames(String... patterns)
                          throws PatternSyntaxException

Return set of existing registry names that match a regex pattern

Parameters:

patterns - regex patterns. NOTE: users need to make sure that patterns that don't start with a wildcard use the full registry name starting with REGISTRY_NAME_PREFIX

Returns:

set of existing registry names where at least one pattern matched.

Throws:

PatternSyntaxException

registryNames

public Set<String> registryNames(Pattern... patterns)

registry

public com.codahale.metrics.MetricRegistry registry(String registry)

Get (or create if not present) a named registry

Parameters:

registry - name of the registry

Returns:

existing or newly created registry

removeRegistry

public void removeRegistry(String registry)

Remove a named registry.

Parameters:

registry - name of the registry to remove

swapRegistries

public void swapRegistries(String registry1,
                           String registry2)

Swap registries. This is useful eg. during SolrCore rename or swap operations. NOTE: this operation is not supported for shared registries.

Parameters:

registry1 - source registry

registry2 - target registry. Note: when used after core rename the target registry doesn't exist, so the swap operation will only rename the existing registry without creating an empty one under the previous name.

registerAll

public void registerAll(String registry,
                        com.codahale.metrics.MetricSet metrics,
                        boolean force,
                        String... metricPath)
                 throws Exception

Register all metrics in the provided MetricSet, optionally skipping those that already exist.

Parameters:

registry - registry name

metrics - metric set to register

force - if true then already existing metrics with the same name will be replaced. When false and a metric with the same name already exists an exception will be thrown.

metricPath - (optional) additional top-most metric name path elements

Throws:

Exception - if a metric with this name already exists.

clearRegistry

public void clearRegistry(String registry)

Remove all metrics from a specified registry.

Parameters:

registry - registry name

clearMetrics

public Set<String> clearMetrics(String registry,
                                String... metricPath)

Remove some metrics from a named registry

Parameters:

registry - registry name

metricPath - (optional) top-most metric name path elements. If empty then this is equivalent to calling clearRegistry(String), otherwise non-empty elements will be joined using dotted notation to form a fully-qualified prefix. Metrics with names that start with the prefix will be removed.

Returns:

set of metrics names that have been removed.

meter

public com.codahale.metrics.Meter meter(String registry,
                                        String metricName,
                                        String... metricPath)

Create or get an existing named Meter

Parameters:

registry - registry name

metricName - metric name, either final name or a fully-qualified name using dotted notation

metricPath - (optional) additional top-most metric name path elements

Returns:

existing or a newly created Meter

timer

public com.codahale.metrics.Timer timer(String registry,
                                        String metricName,
                                        String... metricPath)

Create or get an existing named Timer

Parameters:

registry - registry name

metricName - metric name, either final name or a fully-qualified name using dotted notation

metricPath - (optional) additional top-most metric name path elements

Returns:

existing or a newly created Timer

counter

public com.codahale.metrics.Counter counter(String registry,
                                            String metricName,
                                            String... metricPath)

Create or get an existing named Counter

Parameters:

registry - registry name

metricName - metric name, either final name or a fully-qualified name using dotted notation

metricPath - (optional) additional top-most metric name path elements

Returns:

existing or a newly created Counter

histogram

public com.codahale.metrics.Histogram histogram(String registry,
                                                String metricName,
                                                String... metricPath)

Create or get an existing named Histogram

Parameters:

registry - registry name

metricName - metric name, either final name or a fully-qualified name using dotted notation

metricPath - (optional) additional top-most metric name path elements

Returns:

existing or a newly created Histogram

register

public void register(String registry,
                     com.codahale.metrics.Metric metric,
                     boolean force,
                     String metricName,
                     String... metricPath)

Register an instance of Metric.

Parameters:

registry - registry name

metric - metric instance

force - if true then an already existing metric with the same name will be replaced. When false and a metric with the same name already exists an exception will be thrown.

metricName - metric name, either final name or a fully-qualified name using dotted notation

metricPath - (optional) additional top-most metric name path elements

registerGauge

public void registerGauge(String registry,
                          com.codahale.metrics.Gauge<?> gauge,
                          boolean force,
                          String metricName,
                          String... metricPath)

mkName

public static String mkName(String name,
                            String... path)

This method creates a hierarchical name with arbitrary levels of hierarchy

Parameters:

name - the final segment of the name, must not be null or empty.

path - optional path segments, starting from the top level. Empty or null segments will be skipped.

Returns:

fully-qualified name using dotted notation, with all valid hierarchy segments prepended to the name.

overridableRegistryName

public static String overridableRegistryName(String registry)

Allows named registries to be renamed using System properties. This would be mostly be useful if you want to combine the metrics from a few registries for a single reporter.

For example, in order to collect metrics from related cores in a single registry you could specify the following system properties:

   ... -Dsolr.core.collection1=solr.core.allCollections -Dsolr.core.collection2=solr.core.allCollections
 

NOTE: Once a registry is renamed in a way that its metrics are combined with another repository it is no longer possible to retrieve the original metrics until this renaming is removed and the Solr SolrInfoMBean.Group of components that reported to that name is restarted.

Parameters:

registry - The name of the registry

Returns:

A potentially overridden (via System properties) registry name

enforcePrefix

public static String enforcePrefix(String name)

Enforces the leading REGISTRY_NAME_PREFIX in a name.

Parameters:

name - input name, possibly without the prefix

Returns:

original name if it contained the prefix, or the input name with the prefix prepended.

getRegistryName

public static String getRegistryName(SolrInfoMBean.Group group,
                                     String... names)

Helper method to construct a properly prefixed registry name based on the group.

Parameters:

group - reporting group

names - optional child elements of the registry name. If exactly one element is provided and it already contains the required prefix and group name then this value will be used, and the group parameter will be ignored.

Returns:

fully-qualified and prefixed registry name, with overrides applied.

loadReporters

public void loadReporters(PluginInfo[] pluginInfos,
                          SolrResourceLoader loader,
                          SolrInfoMBean.Group group,
                          String... registryNames)

Create and register SolrMetricReporter-s specific to a SolrInfoMBean.Group. Note: reporters that specify neither "group" nor "registry" attributes are treated as universal - they will always be loaded for any group. These two attributes may also contain multiple comma- or whitespace-separated values, in which case the reporter will be loaded for any matching value from the list. If both attributes are present then only "group" attribute will be processed.

Parameters:

pluginInfos - plugin configurations

loader - resource loader

group - selected group, not null

registryNames - optional child registry name elements

loadReporter

public void loadReporter(String registry,
                         SolrResourceLoader loader,
                         PluginInfo pluginInfo)
                  throws Exception

Create and register an instance of SolrMetricReporter.

Parameters:

registry - reporter is associated with this registry

loader - loader to use when creating an instance of the reporter

pluginInfo - plugin configuration. Plugin "name" and "class" attributes are required.

Throws:

Exception - if any argument is missing or invalid

closeReporter

public boolean closeReporter(String registry,
                             String name)

Close and unregister a named SolrMetricReporter for a registry.

Parameters:

registry - registry name

name - reporter name

Returns:

true if a named reporter existed and was closed.

closeReporters

public Set<String> closeReporters(String registry)

Close and unregister all SolrMetricReporter-s for a registry.

Parameters:

registry - registry name

Returns:

names of closed reporters

getReporters

public Map<String,SolrMetricReporter> getReporters(String registry)

Get a map of reporters for a registry. Keys are reporter names, values are reporter instances.

Parameters:

registry - registry name

Returns:

map of reporters and their names, may be empty but never null