Apache Solr open-source search software
SOLR-14683: move "Missing Metrics" section down to config section; add short blurb to intro text
Cassandra Targett2b5b0f999c3d
diff --git a/solr/solr-ref-guide/src/metrics-reporting.adoc b/solr/solr-ref-guide/src/metrics-reporting.adocindex 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 <<The <metrics> <missingValues> 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 <<Metric Registries>> 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]------<metrics>- <missingValues>- <null name="nullNumber"/>- <int name="notANumber">-1</int>- <str name="nullString"></str>- <str name="nullObject">{"value":"missing"}</str>- </missingValues>-</metrics>-------== Metric RegistriesSolr 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</metrics>----+=== The <metrics> <missingValues> 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]+----+<metrics>+ <missingValues>+ <null name="nullNumber"/>+ <int name="notANumber">-1</int>+ <str name="nullString"></str>+ <str name="nullObject">{"value":"missing"}</str>+ </missingValues>+</metrics>+----++== ReportersReporter configurations are specified in `solr.xml` file in `<metrics><reporter>` sections, for example: