DOCS-4844: Document need to limit WiredTiger cache

Author: i80and

source/administration/production-notes.txt

@@ -175,6 +175,12 @@ maintain reasonable connection pool sizes. Adjust the connection pool
 size to suit your use case, beginning at 110-115% of the typical number
 of concurrent database requests.
 
+When using the :ref:`WiredTiger storage engine <storage-wiredtiger>`,
+the number of incoming connections to WiredTiger should be less than
+or equal to the number of cores available on the machine.
+
+.. TODO add guidance for MMAPv1
+
 The :dbcommand:`connPoolStats` command returns information regarding
 the number of open connections to the current database for
 :program:`mongos` and :program:`mongod` instances in sharded clusters.
@@ -214,17 +220,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,13 @@
+By default a :program:`mongod` instance assumes that it is the only instance
+running on a node, and will consume system resources accordingly. 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