DOCSP-34058-backport-queryStats-v6.0 (#8485)

jeff-allen-mongo · web-flow · commit b7db78999aa4 · 2024-07-19T16:34:33.000-04:00
* Backport-queryStats-v7.0 (#8484) * (DOCSP-26200): queryStats aggregation stage (#4524) * (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 * 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 * (DOCSP-33461): Toggle $queryStats logging (#5329) * initial page setup * WIP * WIP * first draft * formatting * tweak * formatting * wording * add learn more * reorder * add link to transformed output * minimalism * add examples * update toc depth * add output examples * edits * add missing ref * add versions * edit * edit * (DOCSP-33461): Toggle $queryStats logging (#5329) * initial page setup * WIP * WIP * first draft * formatting * tweak * formatting * wording * add learn more * reorder * add link to transformed output * minimalism * add examples * update toc depth * add output examples * edits * adjust versionadded
diff --git a/snooty.toml b/snooty.toml
@@ -145,6 +145,7 @@ toc_landing_pages = [
    "/reference/mongodb-wire-protocol/",
    "/reference/operator/aggregation-pipeline",
    "/reference/operator/aggregation",
+   "/reference/operator/aggregation/queryStats",
    "/reference/operator/query-array",
    "/reference/operator/query-bitwise",
    "/reference/operator/query-comparison",
diff --git a/source/includes/aggregation/queryStats/description.rst b/source/includes/aggregation/queryStats/description.rst
@@ -0,0 +1 @@
+Returns runtime statistics for recorded queries.
diff --git a/source/includes/aggregation/queryStats/logging-intro.rst b/source/includes/aggregation/queryStats/logging-intro.rst
@@ -0,0 +1,6 @@
+MongoDB records |queryStats| operations in the :atlas:`deployment logs
+</mongodb-logs/>`. By default, MongoDB only logs the invocation of
+``$queryStats`` operations, not the operation's output. For
+``$queryStats`` operations that include the ``transformIdentifiers``
+option, you can specify whether the transformed output is included in
+the log entry.
diff --git a/source/includes/aggregation/queryStats/unsupported-warning.rst b/source/includes/aggregation/queryStats/unsupported-warning.rst
@@ -0,0 +1,6 @@
+.. warning::
+
+   The ``$queryStats`` aggregation stage is unsupported and is not
+   guaranteed to be stable in a future release. Don't build
+   functionality that relies on a specific output format of this stage,
+   since the output may change in a future release.
diff --git a/source/includes/extracts-agg-stages.yaml b/source/includes/extracts-agg-stages.yaml
@@ -154,6 +154,12 @@ content: |
           
           See also :pipeline:`$unset` for removing existing fields.
 
+      * - :pipeline:`$queryStats`
+
+        - .. include:: /includes/aggregation/queryStats/description.rst
+
+          .. include:: /includes/aggregation/queryStats/unsupported-warning.rst
+
       * - :pipeline:`$redact`
 
         - Reshapes each document in the stream by restricting the
diff --git a/source/reference/audit-message.txt b/source/reference/audit-message.txt
@@ -1,3 +1,5 @@
+.. _audit-message:
+
 ===========================
 System Event Audit Messages
 ===========================
diff --git a/source/reference/method/cursor.allowPartialResults.txt b/source/reference/method/cursor.allowPartialResults.txt
@@ -1,3 +1,5 @@
+.. _cursor-allowPartialResults:
+
 ============================
 cursor.allowPartialResults()
 ============================
@@ -30,5 +32,3 @@ syntax:
 .. code-block:: javascript
 
    db.collection.find(<query>, <projection>).allowPartialResults()
-
-
diff --git a/source/reference/method/cursor.batchSize.txt b/source/reference/method/cursor.batchSize.txt
@@ -1,3 +1,5 @@
+.. _cursor-batchSize:
+
 ==================
 cursor.batchSize()
 ==================
diff --git a/source/reference/method/cursor.maxTimeMS.txt b/source/reference/method/cursor.maxTimeMS.txt
@@ -1,3 +1,5 @@
+.. _cursor-maxTimeMS:
+
 ==================
 cursor.maxTimeMS()
 ==================
@@ -146,4 +148,3 @@ Examples
    .. code-block:: javascript
 
       db.collection.find({description: /August [0-9]+, 1969/}).maxTimeMS(50)
-
diff --git a/source/reference/method/cursor.noCursorTimeout.txt b/source/reference/method/cursor.noCursorTimeout.txt
@@ -1,3 +1,5 @@
+.. _cursor-noCursorTimeout:
+
 ========================
 cursor.noCursorTimeout()
 ========================
diff --git a/source/reference/operator/aggregation-pipeline.txt b/source/reference/operator/aggregation-pipeline.txt
@@ -413,6 +413,7 @@ Alphabetical Listing of Stages
    /reference/operator/aggregation/out
    /reference/operator/aggregation/planCacheStats
    /reference/operator/aggregation/project
+   /reference/operator/aggregation/queryStats
    /reference/operator/aggregation/redact
    /reference/operator/aggregation/replaceRoot
    /reference/operator/aggregation/replaceWith
diff --git a/source/reference/operator/aggregation/queryStats.txt b/source/reference/operator/aggregation/queryStats.txt
diff --git a/source/reference/operator/aggregation/queryStats/toggle-logging.txt b/source/reference/operator/aggregation/queryStats/toggle-logging.txt
diff --git a/source/reference/privilege-actions.txt b/source/reference/privilege-actions.txt
diff --git a/source/reference/stable-api.txt b/source/reference/stable-api.txt

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Returns runtime statistics for recorded queries.`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _audit-message:`
	`2`	`+`
`1`	`3`	`===========================`
`2`	`4`	`System Event Audit Messages`
`3`	`5`	`===========================`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _cursor-batchSize:`
	`2`	`+`
`1`	`3`	`==================`
`2`	`4`	`cursor.batchSize()`
`3`	`5`	`==================`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _cursor-noCursorTimeout:`
	`2`	`+`
`1`	`3`	`========================`
`2`	`4`	`cursor.noCursorTimeout()`
`3`	`5`	`========================`