DOCS-13943 Add plan cache limit and stats

Author: npentrel

source/core/query-plans.txt

@@ -141,14 +141,36 @@ Users can also:
 
 .. seealso:: :ref:`query-hash-plan-cache-key`
 
+Plan Cache Debug Info Size Limit
+--------------------------------
+
+Starting in MongoDB 4.4.3 (and 4.2.12, 4.0.23, and 3.6.23), the
+:doc:`plan cache </core/query-plans>` will save full ``plan cache``
+entries only if the cumulative size of the ``plan caches`` for all
+collections is lower than
+:parameter:`internalQueryCacheMaxSizeBytesBeforeStripDebugInfo`, which
+defaults to 0.5 GB. When the cumulative size of the ``plan caches`` for
+all collections exceeds this threshold, additional ``plan cache``
+entries are stored without the following debug information:
+
+- :ref:`createdFromQuery <plancachestats-createdFromQuery>`
+- :ref:`cachedPlan <plancachestats-cachedPlan>`
+- :ref:`creationExecStats <plancachestats-creationExecStats>`
+- :ref:`candidatePlanScores <plancachestats-candidatePlanScores>`
+
+Setting ``internalQueryCacheMaxSizeBytesBeforeStripDebugInfo`` to 0,
+will result in no debug information being stored.
+
+The estimated size in bytes of a ``plan cache`` entry is available in
+the output of :pipeline:`$planCacheStats`.
+
 .. _query-hash-plan-cache-key:
 
 ``queryHash`` and ``planCacheKey``
 ----------------------------------
 
 .. _query-hash:
 
-
 ``queryHash``
 ~~~~~~~~~~~~~
 

source/reference/method/PlanCache.list.txt

@@ -248,7 +248,8 @@ associated with the following shapes:
             1.5002
          ],
          "indexFilterSet" : false,
-         "host" : "mongodb1.example.net:27018", 
+         "estimatedSizeBytes" : NumberLong(3160),   // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
+         "host" : "mongodb1.example.net:27018",
          "shard" : "shardA"                         // Available if run on sharded cluster
       },
 
@@ -292,7 +293,7 @@ associated with the following shapes:
 
 For details on the output, see :ref:`$planCacheStats output
 <planCacheStats-output>`.
-     
+
 .. planCache-list-query-shapes:
 
 List Query Shapes
@@ -311,7 +312,7 @@ example, the following operation passes in a pipeline with a
 .. code-block:: javascript
 
    db.orders.getPlanCache().list( [ { $project: {createdFromQuery: 1, queryHash: 1 } } ] )
- 
+
 The operation returns the following query shapes:
 
 .. code-block:: javascript
@@ -521,6 +522,7 @@ The operation returns the following:
             1.5002
          ],
          "indexFilterSet" : false,
+         "estimatedSizeBytes" : NumberLong(3160),   // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
          "host" : "mongodb1.example.net:27018",
          "shard" : "shardA"                         // Available if run on sharded cluster
       }

source/reference/operator/aggregation/planCacheStats.txt

@@ -129,6 +129,7 @@ document similar to the following:
          ...
       ],
       "indexFilterSet" : <boolean>,
+      "estimatedSizeBytes" : <num>, // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
       "host" : <string>,   // Available starting in MongoDB 4.4
       "shard" : <string>   // Available starting in MongoDB 4.4 if run on sharded cluster
    }
@@ -189,9 +190,11 @@ including:
        currently available indexes for that shape. For more information, see
        :data:`explain.queryPlanner.planCacheKey`
 
-   * - ``cachedPlan``
+   * - :ref:`cachedPlan <plancachestats-cachedPlan>`
 
-     - The details of the cached plan. See :data:`explain.queryPlanner`.
+     - .. _plancachestats-cachedPlan:
+
+       The details of the cached plan. See :data:`explain.queryPlanner`.
 
    * - ``works``
 
@@ -203,24 +206,36 @@ including:
    * - ``timeOfCreation``
      - Time of creation for the entry.
 
-   * - ``creationExecStats``
+   * - :ref:`creationExecStats <plancachestats-creationExecStats>`
+
+     - .. _plancachestats-creationExecStats:
 
-     - An array of execution stats documents. The array contains a
+       An array of execution stats documents. The array contains a
        document for each candidate plan.
 
        For details on the execution stats, see
        :data:`explain.executionStats`.
 
-   * - ``candidatePlanScores``
+   * - :ref:`candidatePlanScores <plancachestats-candidatePlanScores>`
+
+     - .. _plancachestats-candidatePlanScores:
 
-     - An array of scores for the candidate plans listed in the
+       An array of scores for the candidate plans listed in the
        ``creationExecStats`` array.
 
    * - ``indexFilterSet``
 
      - A boolean that indicates whether the an :ref:`index filter
        <index-filters>` exists for the query shape.
 
+   * - ``estimatedSizeBytes``
+
+     - A number that describes the estimated size in bytes of a plan
+       cache entry.
+
+       .. versionadded:: 4.4.3 (*Also available starting in 4.2.12,
+          4.0.23, and 3.6.23*)
+
    * - :ref:`host <plancachestats-host>`
 
      - .. _plancachestats-host:
@@ -330,6 +345,7 @@ The operation returns all entries in the cache:
          1.5002
       ],
       "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(3160),     // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
       "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
       "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
    }
@@ -360,6 +376,7 @@ The operation returns all entries in the cache:
          1.0002
       ],
       "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(2539),     // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
       "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
       "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
    }
@@ -390,6 +407,7 @@ The operation returns all entries in the cache:
          1.7502
       ],
       "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(3183),     // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
       "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
       "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
    }
@@ -424,6 +442,7 @@ The operation returns all entries in the cache:
          1.6668666666666665
       ],
       "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(4653),     // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
       "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
       "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
    }
@@ -476,7 +495,7 @@ specific information for a particular query shape:
 
 .. code-block:: javascript
 
-   db.orders.aggregate( [ 
+   db.orders.aggregate( [
       { $planCacheStats: { } },
       { $match: { planCacheKey: "DD67E353"} }
    ] )
@@ -485,7 +504,7 @@ The operation returns the following:
 
 .. code-block:: javascript
    :copyable: false
-   
+
    {
       "createdFromQuery" : {
          "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" },
@@ -651,6 +670,7 @@ The operation returns the following:
          1.5002
       ],
       "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(3160),     // Available starting in MongoDB 4.4.3, 4.2.12, 4.0.23, 3.6.23
       "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
       "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
    }

source/reference/parameters.txt

@@ -1406,7 +1406,28 @@ General Parameters
 
       mongod --setParameter "tcmallocReleaseRate=5.0"
 
-   
+.. parameter:: internalQueryCacheMaxSizeBytesBeforeStripDebugInfo
+
+   .. versionadded:: 4.4.3 (*Also available starting in 4.2.12,
+      4.0.23, and 3.6.23*)
+
+   Default: 536870912 (0.5 GB)
+
+   Specifies the maximum cumulative size of the :doc:`plan caches
+   </core/query-plans>` for all collections under which
+   the ``plan cache`` will save full ``plan cache`` entries. When
+   the cumulative size of the ``plan caches`` for all collections
+   exceeds this threshold, additional ``plan cache`` entries are stored
+   without the following debug information:
+
+   - :ref:`createdFromQuery <plancachestats-createdFromQuery>`
+   - :ref:`cachedPlan <plancachestats-cachedPlan>`
+   - :ref:`creationExecStats <plancachestats-creationExecStats>`
+   - :ref:`candidatePlanScores <plancachestats-candidatePlanScores>`
+
+   Setting ``internalQueryCacheMaxSizeBytesBeforeStripDebugInfo`` to 0,
+   will result in no debug information being stored.
+
 Logging Parameters
 ~~~~~~~~~~~~~~~~~~