DOCS-4844: Document need to limit WiredTiger cache

Author: i80and

source/administration/production-notes.txt

@@ -214,17 +214,12 @@ WiredTiger will experience negative performance. For information on
 active operations, see the active read/write (``ar|aw``) column in the
 :program:`mongostat` output.
 
-If you run :program:`mongod` in a container (e.g. ``lxc``, ``cgroups``,
-Docker, etc.) that does *not* have access to all of the RAM available
-in a system, you must set the
-:setting:`wiredTiger.engineConfig.cacheSizeGB` to a value less than the
-amount of RAM available in the container. The exact amount depends on
-the other processes running in the container.
-
-The size of the WiredTiger cache should be sufficient to hold the
-entire working set for the :program:`mongod`. To adjust the size of the
-WiredTiger cache, see
-:setting:`storage.wiredTiger.engineConfig.cacheSizeGB`.
+WiredTiger's default configuration will use either 1GB or half of the
+installed physical RAM for cache, whichever is larger. This size is tunable
+through the :setting:`storage.wiredTiger.engineConfig.cacheSizeGB` setting, and
+should be large enough to hold your entire :term:`working set`.
+
+.. include:: /includes/fact-wiredtiger-cachesizegb.rst
 
 .. seealso:: :ref:`prod-notes-concurrency`
 

source/includes/fact-wiredtiger-cachesizegb.rst

@@ -0,0 +1,12 @@
+The default value for this setting is optimized for a single :program:`mongod`
+instance per node. If a single node contains multiple instances, then you should
+change :setting:`storage.wiredTiger.engineConfig.cacheSizeGB` for each instance
+to a value that is large enough to encompass the entire working dataset,
+but that also leaves room for the other :program:`mongod` instances.
+
+If you run :program:`mongod` in a container (e.g. ``lxc``, ``cgroups``,
+Docker, etc.) that does *not* have access to all of the RAM available
+in a system, you must set the
+:setting:`storage.wiredTiger.engineConfig.cacheSizeGB` to a value less than the
+amount of RAM available in the container. The exact amount depends on
+the other processes running in the container.

source/includes/options-mongod.yaml

@@ -1573,7 +1573,9 @@ description: |
 
   Defines the maximum size of the cache that WiredTiger will use for
   all data. Ensure that {{role}} is sufficient to hold the entire
-  working set for the {{program}} instance.
+  :term:`working set` for the {{program}} instance.
+
+  .. include:: /includes/fact-wiredtiger-cachesizegb.rst
 ---
 program: mongod
 name: wiredTigerCheckpointDelaySecs