(DOCSP-33099): queryStats serverStatus metrics (#4811)

jeff-allen-mongo · web-flow · commit f7c8253cf6d7 · 2023-09-29T11:29:05.000-04:00
* (DOCSP-26200): queryStats aggregation stage * WIP * WIP * WIP * Remove accidental file * add TODO * add missing ref * formatting * WIP * WIP * WIP * wording * WIP * edits * add examples * try to fix table format * add transformed example * remove TODO * more table formatting * add atlas data collection * table formatting * clarity * add more context for data collection * table formatting * wording tweaks * address review comments * formatting * use simplified examples * add input/output * edits * add link to transformed example * spacing * edits * (DOCSP-33099): queryStats serverStatus metrics * (DOCSP-33099): serverStatus metrics for queryStats * formatting * clarity * address review comments * fix incomplete sentence * rework transformation section * edits * remove notion of a 'cache' * remove extra queryStats heading * minimalism * fix collation link formatting * move virtual collection details to the queryStats page * change wording for output fields * (DOCSP-26200): queryStats aggregation stage * WIP * WIP * WIP * Remove accidental file * add TODO * add missing ref * formatting * WIP * WIP * WIP * wording * WIP * edits * add examples * try to fix table format * add transformed example * remove TODO * more table formatting * add atlas data collection * table formatting * clarity * add more context for data collection * table formatting * wording tweaks * address review comments * formatting * use simplified examples * add input/output * edits * add link to transformed example * spacing * edits * address review comments * fix incomplete sentence * rework transformation section * edits * fix collation link formatting * change wording for output fields * edit glossary * more edits * remove glossary entry * formatting * edits * Address review feedback * wording * review edit * address review comments * edit * wording * WIP review edits * remove Atlas data collection info * (DOCSP-33347): Re-add Atlas data collection info * typo * minimalism * typo * clarity * remove Atlas data collection info * edits * (DOCSP-33347): Re-add Atlas data collection info * add find queryShape properties * change case * formatting * abstracted > normalized consistency * clarify privilege * address review comments * review edits
diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt
@@ -3883,6 +3883,55 @@ planCache
    Number of slot-based execution engine query plans which were not found 
    in the query cache and went through the query planning phase.
 
+.. _server-status-queryStats:
+
+queryStats
+~~~~~~~~~~
+
+.. versionadded:: 7.1
+
+.. code-block:: javascript
+
+   queryStats: {
+      numEvicted: Long("<num>"),
+      numRateLimitedRequests: Long("<num>"),
+      queryStatsStoreSizeEstimateBytes: Long("<num>"),
+      numQueryStatsStoreWriteErrors: Long("<num>"),
+      numHmacApplicationErrors: Long("<num>")
+   },
+
+.. serverstatus:: queryStats
+
+   A document that contains metrics for the :pipeline:`$queryStats`
+   aggregation stage.
+
+.. serverstatus:: queryStats.numEvicted
+
+   Number of queries that the ``$queryStats`` virtual collection has
+   evicted due to space contraints.
+
+.. serverstatus:: queryStats.numRateLimitedRequests
+
+   Number of times that query stats were not recorded for a query due to
+   rate limiting.
+
+.. serverstatus:: queryStats.queryStatsStoreSizeEstimateBytes
+
+   Current estimated size of objects in the ``$queryStats`` virtual
+   collection.
+
+.. serverstatus:: queryStats.numQueryStatsStoreWriteErrors
+
+   Number of times this MongoDB process failed to store a new query
+   stats key. Generally, these failures happen when the
+   ``$queryStats`` virtual collection runs out of space.
+
+.. serverstatus:: queryStats.numHmacApplicationErrors
+
+   Number of times this MongoDB process failed to compute a one-way
+   tokenized query stats key when ``$queryStats`` was called with the
+   ``transformIdentifiers`` option.
+
 .. _server-status-queryAnalyzers:                                       
                                                                         
 queryAnalyzers                                  
diff --git a/source/reference/operator/aggregation/queryStats.txt b/source/reference/operator/aggregation/queryStats.txt
@@ -126,6 +126,13 @@ Behavior
 The following sections describe behavioral details of the
 ``$queryStats`` stage.
 
+How $queryStats Tracks Query Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Statistics for the ``$queryStats`` stage are tracked in a virtual
+collection that is stored in-memory. The memory limit for the virtual
+collection is 1% of the system's total memory.
+
 How $queryStats Groups Returned Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/release-notes/7.1.txt b/source/release-notes/7.1.txt
@@ -98,7 +98,10 @@ serverStatus Output Change
 output:
 
 Change Stream Metrics 
-  - :serverstatus:`metrics.changeStreams.showExpandedEvents`
+  :serverstatus:`metrics.changeStreams.showExpandedEvents`
+
+Query Stats Metrics
+  :serverstatus:`queryStats`
 
 .. toctree::
    :titlesonly:
