diff --git a/solr/solr-ref-guide/src/metrics-reporting.adoc b/solr/solr-ref-guide/src/metrics-reporting.adoc index 67203597a71..96241658489 100644 --- a/solr/solr-ref-guide/src/metrics-reporting.adoc +++ b/solr/solr-ref-guide/src/metrics-reporting.adoc @@ -26,51 +26,16 @@ Internally this feature uses the http://metrics.dropwizard.io[Dropwizard Metrics * *timers* - measure the number and duration of events. They provide a count and histogram of timings. * *gauges* - offer instantaneous reading of a current value, e.g., current queue depth, current number of active connections, free heap size. +Some of these meters may be missing or empty for any number of valid reasons. +In these cases, missing values of any type will be returned as `null` by default so empty values won't impact averages or histograms. +This is configurable for several types of missing values; see the < Element>> section below. + Each group of related metrics with unique names is managed in a *metric registry*. Solr maintains several such registries, each corresponding to a high-level group such as: `jvm`, `jetty`, `node`, and `core` (see <> below). For each group (and/or for each registry) there can be several *reporters*, which are components responsible for communication of metrics from selected registries to external systems. Currently implemented reporters support emitting metrics via JMX, Ganglia, Graphite and SLF4J. There is also a dedicated `/admin/metrics` handler that can be queried to report all or a subset of the current metrics from multiple registries. -=== Missing metrics -Long-lived metrics values are still reported when the underlying value is unavailable (eg. "INDEX.sizeInBytes" when -IndexReader is closed). Short-lived transient metrics (such as cache entries) that are properties of complex gauges -(internally represented as `MetricsMap`) are simply skipped when not available, and neither their names nor values -appear in registries (or in /admin/metrics reports). - -When a missing value is encountered by default it's reported as null value, regardless of the metrics type. -This can be configured in the `solr.xml:/solr/metrics/missingValues` element, which recognizes the following child elements -(for string elements a JSON payload is supported): - -`nullNumber`:: -value to use when a missing (null) numeric metrics value is encountered. - -`notANumber`:: -value to use when an invalid numeric value is encountered. - -`nullString`:: -value to use when a missing (null) string metrics is encountered. - -`nullObject`:: -value to use when a missing (null) complex object is encountered. - -Example configuration that returns null for missing numbers, -1 for -invalid numeric values, empty string for missing strings, and a Map for missing -complex objects: - -[source,xml] ----- - - - - -1 - - {"value":"missing"} - - ----- - - == Metric Registries Solr includes multiple metric registries, which group related metrics. @@ -202,6 +167,45 @@ As an example of a section of `solr.xml` that defines some of these custom param ---- +=== The Element +Long-lived metrics values are still reported when the underlying value is unavailable (e.g., "INDEX.sizeInBytes" when +IndexReader is closed). Short-lived transient metrics (such as cache entries) that are properties of complex gauges +(internally represented as `MetricsMap`) are simply skipped when not available, and neither their names nor values +appear in registries (or in `/admin/metrics` reports). + +When a missing value is encountered by default it's reported as null value, regardless of the metrics type. +This can be configured in the `solr.xml:/solr/metrics/missingValues` element, which recognizes the following child elements +(for string elements a JSON payload is supported): + +`nullNumber`:: +The value to use when a missing (null) numeric metrics value is encountered. + +`notANumber`:: +The value to use when an invalid numeric value is encountered. + +`nullString`:: +The value to use when a missing (null) string metrics is encountered. + +`nullObject`:: +The value to use when a missing (null) complex object is encountered. + +Example configuration that returns null for missing numbers, -1 for +invalid numeric values, empty string for missing strings, and a Map for missing +complex objects: + +[source,xml] +---- + + + + -1 + + {"value":"missing"} + + +---- + + == Reporters Reporter configurations are specified in `solr.xml` file in `` sections, for example: