DOCSP-33233-query-analyzer-metrics (#5541) (#5554)

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

* DOCSP-33233-query-analyzer-metrics

---------

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/includes/analyzeShardKey-command-fields.rst

@@ -41,6 +41,8 @@
 
        Defaults to ``true``.
 
+       .. include:: /includes/analyzeShardKey-read-and-write-distribution-metrics.rst
+
    * - ``sampleRate``
      - double
      - Optional

source/includes/analyzeShardKey-read-and-write-distribution-metrics.rst

@@ -0,0 +1,6 @@
+To return read and write distribution metrics for a collection using
+:dbcommand:`analyzeShardKey`, you must configure the query
+analyzer to sample the queries run on the collection. Otherwise,
+``analyzeShardKey`` returns the read and write distribution metrics as
+``0`` values. To configure the query analyzer, see
+:ref:`configureQueryAnalyzer`.

source/includes/analyzeShardKey-readWriteDistribution-structure.rst

@@ -41,3 +41,4 @@ returned when ``readWriteDistribution`` is set to ``true``:
       }
    }
 
+.. include:: /includes/analyzeShardKey-read-and-write-distribution-metrics.rst

source/includes/shard-key-read-write-distribution.rst

@@ -1,26 +1,29 @@
-``readWriteDistribution`` consists of the metrics about the query 
+``readWriteDistribution`` contains metrics about the query 
 routing patterns and the :ref:`hotness 
 <sharding-troubleshooting-monotonicity>` of shard key ranges. These 
-metrics are based on sampled queries. You can configure query sampling
-for a collection with ``configureQueryAnalyzer``. These 
-metrics are only returned when ``readWriteDistribution`` is true. The 
-metrics are calculated when |analyzeShardKey| is run based on sampled 
-read and write queries and are not be returned if there are no sampled 
-queries.
+metrics are based on sampled queries.
+
+To configure query sampling for a collection, use the
+``configureQueryAnalyzer`` command. The read and write distribution
+metrics are only returned if ``readWriteDistribution`` is ``true``. The
+metrics are calculated when |analyzeShardKey| is run and the metrics use
+the sampled read and write queries. If there are no sampled queries,
+read and write distribution metrics aren't returned.
 
 - If there are no sampled read queries, the command returns
   ``writeDistribution`` but omits ``readDistribution``.
 
 - If there are no sampled write queries, the command returns
   ``readDistribution`` but omits ``writeDistribution``.
 
+.. include:: /includes/analyzeShardKey-read-and-write-distribution-metrics.rst
 
 .. list-table::
    :header-rows: 1
 
    * - ``keyCharacteristics`` Value
      - ``readWriteDistribution`` Value 
-     - Behaviors
+     - Results Returned
 
    * - ``true``
      - ``false``
@@ -30,8 +33,8 @@ queries.
          omits :ref:`readWriteDistribution <read-write-distribution-output>`
          metrics.
 
-       - If the shard key does not have a |suppindx|, 
-         |analyzeShardKey| raises an 
+       - If the shard key doesn't have a |suppindx|, 
+         |analyzeShardKey| returns an 
          ``IllegalOperation`` error.
 
    * - ``false``
@@ -45,6 +48,6 @@ queries.
        - |analyzeShardKey| returns both ``readWriteDistribution`` 
          metrics and ``keyCharacteristics`` metrics.
 
-       - If the shard key does not have a supporting index, 
+       - If the shard key doesn't have a supporting index, 
          |analyzeShardKey| returns ``readWriteDistribution`` metrics 
          and omits ``keyCharacteristics`` metrics.