DOCS-13943 Add plan cache limit and stats

Author: npentrel

source/core/query-plans.txt

@@ -141,14 +141,42 @@ Users can also:
 
 .. seealso:: :ref:`query-hash-plan-cache-key`
 
+Plan Cache Debug Info Size Limit
+--------------------------------
+
+Starting in 4.2.12 (and 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 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>`
+
+When ``plan cache`` entries are stored with stripped debug information,
+the :dbcommand:`planCacheListQueryShapes` command output contains only
+``queryHash`` fields in the ``shapes`` array. Similarly, detailed
+execution statistics for the candidate plans are omitted from the
+:dbcommand:`planCacheListPlans` command output when ``plan cache``
+entries are stored with stripped debug information. When debug info is
+present, you can find these detailed statistics in the ``plans.reason``
+field.
+
+The estimated size in bytes of a ``plan cache`` entry is available in
+the output of :pipeline:`$planCacheStats` and
+:dbcommand:`planCacheListPlans`.
+
 .. _query-hash-plan-cache-key:
 
 ``queryHash`` and ``planCacheKey``
 ----------------------------------
 
 .. _query-hash:
 
-
 ``queryHash``
 ~~~~~~~~~~~~~
 

source/reference/operator/aggregation/planCacheStats.txt

@@ -108,7 +108,8 @@ document similar to the following:
          <number>,
          ...
       ],
-      "indexFilterSet" : <boolean>
+      "indexFilterSet" : <boolean>,
+      "estimatedSizeBytes" : <num> // Available starting in MongoDB 4.2.12, 4.0.23, 3.6.23
    }
 
 Each document includes various query plan and execution stats,
@@ -123,7 +124,9 @@ including:
 
    * - ``createdFromQuery``
 
-     - A document that contains the specific query that resulted in
+     - .. _plancachestats-createdFromQuery:
+
+       A document that contains the specific query that resulted in
        this cache entry; i.e.
 
        .. code-block:: javascript
@@ -161,9 +164,11 @@ including:
        currently available indexes for that shape. For more information, see
        :data:`explain.queryPlanner.planCacheKey`
 
-   * - ``cachedPlan``
+   * - :ref:`cachedPlan <plancachestats-cachedPlan>`
+
+     - .. _plancachestats-cachedPlan:
 
-     - The details of the cached plan. See :data:`explain.queryPlanner`.
+       The details of the cached plan. See :data:`explain.queryPlanner`.
 
    * - ``works``
 
@@ -175,24 +180,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>`
 
-     - An array of scores for the candidate plans listed in the
+     - .. _plancachestats-candidatePlanScores:
+
+       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.2.12 (*and 4.0.23 and 3.6.23*)
+
+
 Examples
 --------
 
@@ -275,7 +292,8 @@ The operation returns all entries in the cache:
          1.5003000000000002,
          1.5003000000000002
       ],
-      "indexFilterSet" : false
+      "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(3160)      // Available starting in MongoDB 4.2.12, 4.0.23, 3.6.23
    }
    {                                               // Plan Cache Entry 2
       "createdFromQuery" : {
@@ -303,7 +321,8 @@ The operation returns all entries in the cache:
          1.0003000000000002,
          1.0003000000000002
       ],
-      "indexFilterSet" : false
+      "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(2539)      // Available starting in MongoDB 4.2.12, 4.0.23, 3.6.23
    }
    {                                               // Plan Cache Entry 3
       "createdFromQuery" : {
@@ -331,7 +350,8 @@ The operation returns all entries in the cache:
          1.7503000000000002,
          1.7503000000000002
       ],
-      "indexFilterSet" : false
+      "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(3183)      // Available starting in MongoDB 4.2.12, 4.0.23, 3.6.23
    }
    {                                               // Plan Cache Entry 4
       "createdFromQuery" : {
@@ -363,7 +383,8 @@ The operation returns all entries in the cache:
          1.6669666666666665,
          1.6669666666666665
       ],
-      "indexFilterSet" : false
+      "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(4653)     // Available starting in MongoDB 4.2.12, 4.0.23, 3.6.23
    }
 
 See also :ref:`plan-cache-key`. 
@@ -415,7 +436,7 @@ specific information for a particular query shape:
 
 .. code-block:: javascript
 
-   db.orders.aggregate( [ 
+   db.orders.aggregate( [
       { $planCacheStats: { } },
       { $match: { planCacheKey: "DD67E353"} }
    ] )
@@ -424,7 +445,7 @@ The operation returns the following:
 
 .. code-block:: javascript
    :copyable: false
-   
+
    {
       "createdFromQuery" : {
          "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" },
@@ -589,7 +610,8 @@ The operation returns the following:
          1.5003000000000002,
          1.5003000000000002
       ],
-      "indexFilterSet" : false
+      "indexFilterSet" : false,
+      "estimatedSizeBytes" : NumberLong(3160)      // Available starting in MongoDB 4.2.12, 4.0.23, 3.6.23
    }
 
 See also :ref:`plan-cache-key` and :ref:`query-hash`.