Skip to content

Commit d7d931c

Browse files
jeff-allen-mongojeff-allen-mongo
authored
(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
1 parent c72ca44 commit d7d931c

File tree

4 files changed

+163
-2
lines changed

4 files changed

+163
-2
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,7 @@ toc_landing_pages = [
160160
"/reference/mongodb-wire-protocol/",
161161
"/reference/operator/aggregation-pipeline",
162162
"/reference/operator/aggregation",
163+
"/reference/operator/aggregation/queryStats",
163164
"/reference/operator/query-array",
164165
"/reference/operator/query-bitwise",
165166
"/reference/operator/query-comparison",

‎source/includes/aggregation/queryStats/logging-intro.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
MongoDB records |queryStats| operations in the :atlas:`deployment logs
2+
</mongodb-logs/>`. By default, MongoDB only logs the invocation of
3+
``$queryStats`` operations, not the operation's output. For
4+
``$queryStats`` operations that include the ``transformIdentifiers``
5+
option, you can specify whether the transformed output is included in
6+
the log entry.

‎source/reference/operator/aggregation/queryStats.txt

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,8 +152,8 @@ options like ``hint`` and ``comment``.
152152
For the complete list of options included in a query stats entry, see
153153
:ref:`queryStats-find-query-shape`.
154154

155-
How $queryStats Transforms Data Using transformIdentifiers
156-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155+
How $queryStats Transforms Data
156+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157157

158158
When an HMAC key is specified to the ``transformIdentifiers`` option,
159159
``$queryStats`` uses the HMAC key to apply an HMAC-SHA-256 hash function
@@ -181,6 +181,16 @@ following data:
181181
For an example of transformed output, see
182182
:ref:`queryStats-example-transformed`.
183183

184+
$queryStats Log Entries
185+
~~~~~~~~~~~~~~~~~~~~~~~
186+
187+
.. |queryStats| replace:: ``$queryStats``
188+
189+
.. include:: /includes/aggregation/queryStats/logging-intro.rst
190+
191+
To learn how to control ``$queryStats`` logging behavior, see
192+
:ref:`queryStats-toggle-logging`.
193+
184194
Output
185195
------
186196

@@ -938,3 +948,9 @@ retains the data it collects with ``$queryStats`` for four years.
938948
When Atlas runs ``$queryStats`` on your deployment, it uses a unique
939949
HMAC key per Atlas organization to transform your data and avoid
940950
collecting sensitive information.
951+
952+
.. toctree::
953+
:titlesonly:
954+
:hidden:
955+
956+
/reference/operator/aggregation/queryStats/toggle-logging

‎source/reference/operator/aggregation/queryStats/toggle-logging.txt

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
.. _queryStats-toggle-logging:
2+
3+
=============================
4+
Toggle $queryStats Log Output
5+
=============================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. |queryStats| replace:: :pipeline:`$queryStats`
16+
17+
.. include:: /includes/aggregation/queryStats/logging-intro.rst
18+
19+
Including ``$queryStats`` output in the logs provides more information
20+
on specific ``$queryStats`` operations, but can negatively impact
21+
cluster performance as log updates take more time and resources.
22+
23+
About this Task
24+
---------------
25+
26+
When MongoDB logs ``$queryStats`` output, the results are redacted and
27+
anonymized. ``$queryStats`` output does not contain literals or field
28+
values.
29+
30+
For an example of transformed ``$queryStats`` output, see
31+
:ref:`queryStats-example-transformed`.
32+
33+
Steps
34+
-----
35+
36+
.. procedure::
37+
:style: normal
38+
39+
.. step:: Open the :guilabel:`Database Deployments` page for your project
40+
41+
.. step:: Click :guilabel:`Edit Config`
42+
43+
.. step:: Select your cluster from the dropdown
44+
45+
.. step:: Open the :guilabel:`Additional Settings` dropdown
46+
47+
.. step:: Open the :guilabel:`More Configuration Options` dropdown
48+
49+
.. step:: Toggle the :guilabel:`Enable Logging of Redacted and Anonymized Query Data` setting
50+
51+
.. step:: Click :guilabel:`Review Changes`
52+
53+
.. step:: Click :guilabel:`Apply Changes`
54+
55+
Examples
56+
--------
57+
58+
The following examples show the differences in log messages when
59+
``$queryStats`` output is included.
60+
61+
.. note::
62+
63+
The example log entries are reformatted for readability.
64+
65+
``$queryStats`` Output Omitted (Default Behavior)
66+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67+
68+
.. code-block:: javascript
69+
:copyable: false
70+
71+
{
72+
"t":{"$date":"2023-11-27T20:58:59.212+00:00"},"s":"D1", "c":"QRYSTATS",
73+
"id":7808300, "ctx":"conn31","msg":"Logging invocation
74+
$queryStats","attr":{"commandSpec":{"transformIdentifiers":{"algorithm":"hmac-sha-256","hmacKey":"###"}}
75+
}
76+
77+
``$queryStats`` Output Included
78+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79+
80+
.. code-block:: javascript
81+
:copyable: false
82+
83+
{
84+
"t":{"$date":"2023-11-27T20:58:59.212+00:00"},"s":"D1", "c":"QRYSTATS",
85+
"id":7808300, "ctx":"conn31","msg":"Logging invocation
86+
$queryStats","attr":{"commandSpec":{"transformIdentifiers":{"algorithm":"hmac-sha-256","hmacKey":"###"}}
87+
}
88+
89+
{
90+
"t":{"$date":"2023-11-27T20:58:59.212+00:00"},"s":"D3", "c":"QRYSTATS",
91+
"id":7808301, "ctx":"conn31","msg":"Logging all outputs of
92+
$queryStats","attr":{"thisOutput":"{key: {queryShape: {cmdNs: {db:
93+
\"hYt+nW/sr1/Zc3YR8nlGWFoesJdvywkw+cR9rMGzXU4=\", coll:
94+
\"TRx6R3rvstYgX96gNmeOi5E3QVsOqzRbv7A9j3q7OvM=\"}, command: \"find\",
95+
filter: {Wb/Uu22DzKZ/Os+ZvLgPKFKGZPV4cIMZ3Ybv1HfYih4=: {$lt:
96+
\"?date\"}}, projection: {r5zQZllsGoqQuQp4Jm0eH2M6RrMqH84KHowcFaiverg=:
97+
true}, sort: {r5zQZllsGoqQuQp4Jm0eH2M6RrMqH84KHowcFaiverg=: 1}},
98+
readConcern: {}, collectionType: \"nonExistent\"}, metrics:
99+
{lastExecutionMicros: 208, execCount: 21, totalExecMicros: {sum: 6079,
100+
max: 1875, min: 198, sumOfSquares: 4401645}, firstResponseExecMicros:
101+
{sum: 6079, max: 1875, min: 198, sumOfSquares: 4401645}, docsReturned:
102+
{sum: 0, max: 0, min: 0, sumOfSquares: 0}, firstSeenTimestamp:
103+
2023-11-27T19:15:51.317Z, latestSeenTimestamp:
104+
2023-11-27T20:55:51.309Z}, asOf: 2023-11-27T20:58:59.212Z}"}
105+
}
106+
107+
{
108+
"t":{"$date":"2023-11-27T20:58:59.213+00:00"},"s":"D3", "c":"QRYSTATS",
109+
"id":7808301, "ctx":"conn31","msg":"Logging all outputs of
110+
$queryStats","attr":{"thisOutput":"{key: {queryShape: {cmdNs: {db:
111+
\"j+Caz+gxt7vl++gmeCAWrvyhDL17WaNrSIDi6Au7VI0=\", coll:
112+
\"f/LCkK/kVEbt4fk2NNbyDPhxas+kzCLLcVbjeNBbhyg=\"}, let:
113+
{pUZAyEEImSXcu8deG05tfIf6F/H92YsFnkZXIeRQtgc=: \"?number\"}, command:
114+
\"aggregate\", pipeline: [{$group: {_id: \"?number\",
115+
5E6FSc5VxCvIZK0jrqkY3k3aX51jSc73hQwO/8kH0lo=: {$sum: \"?number\"}}}],
116+
explain: true, allowDiskUse: false}, client: {driver: {name:
117+
\"nodejs|mongosh\", version: \"5.1.0\"}, os: {type: \"Darwin\", name:
118+
\"darwin\", architecture: \"arm64\", version: \"22.6.0\"}, platform:
119+
\"Node.js v16.19.1, LE (unified)\", version: \"5.1.0|1.8.0\",
120+
application: {name: \"mongosh 1.8.0\"}}, collectionType: \"collection\",
121+
cursor: {batchSize: \"?number\"}}, metrics: {lastExecutionMicros: 0,
122+
execCount: 1, totalExecMicros: {sum: 0, max: 0, min: 0, sumOfSquares:
123+
0}, firstResponseExecMicros: {sum: 0, max: 0, min: 0, sumOfSquares: 0},
124+
docsReturned: {sum: 0, max: 0, min: 0, sumOfSquares: 0},
125+
firstSeenTimestamp: 2023-11-27T19:31:36.463Z, latestSeenTimestamp:
126+
2023-11-27T19:31:36.463Z}, asOf: 2023-11-27T20:58:59.213Z}"}
127+
}
128+
129+
// Additional $queryStats output...
130+
131+
Learn More
132+
----------
133+
134+
- :ref:`auditing`
135+
136+
- :ref:`audit-message`
137+
138+
- :atlas:`Configure a Custom Auditing Filter </database-auditing/#std-label-auditing-custom-filter>`

0 commit comments

Comments
 (0)