[lucene-solr] branch branch_8x updated: SOLR-14683: move "Missing Metrics" section down to config section; add short blurb to intro text

[ct...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ctargett pushed a commit to branch branch_8x
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git


The following commit(s) were added to refs/heads/branch_8x by this push:
     new 139ec4f  SOLR-14683: move "Missing Metrics" section down to config section; add short blurb to intro text
139ec4f is described below

commit 139ec4f99431b6e78ef50d3a74beabbbc4b90f19
Author: Cassandra Targett <ct...@apache.org>
AuthorDate: Tue Nov 17 11:57:40 2020 -0600

    SOLR-14683: move "Missing Metrics" section down to config section; add short blurb to intro text
---
 solr/solr-ref-guide/src/metrics-reporting.adoc | 82 ++++++++++++++------------
 1 file changed, 43 insertions(+), 39 deletions(-)

diff --git a/solr/solr-ref-guide/src/metrics-reporting.adoc b/solr/solr-ref-guide/src/metrics-reporting.adoc
index ff66b1d..e27b7a9 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 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
 </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>
+----
+
+
 == Reporters
 
 Reporter configurations are specified in `solr.xml` file in `<metrics><reporter>` sections, for example: