(DOCSP-35335): Add maxConnecting setting for connection pools (#5917) (#6016)

* (DOCSP-35335): Add maxConnecting setting for connection pools

* formatting fix

* add definition

* wording

* add context to changing maxConnecting

* wording

* note relationship with maxPoolSize

* edit

* address tech review comments

* review edit

* add definition for connection storm

* wording

* typo

* more edits

* edit

* wording

Author: jeff-allen-mongo

source/administration/connection-pool-overview.txt

@@ -4,6 +4,10 @@
 Connection Pool Overview
 ========================
 
+.. facet::
+   :name: genre
+   :values: reference
+
 .. default-domain:: mongodb
 
 .. contents:: On this page
@@ -79,13 +83,13 @@ to be established.
 Connection Pool Configuration Settings
 --------------------------------------
 
-To configure the connection pool, set the options:
+You can specify connection pool settings in these locations:
 
-- through the :ref:`MongoDB URI <mongodb-uri>`, 
+- The :ref:`MongoDB URI <mongodb-uri>`
 
-- programmatically when building the ``MongoClient`` instance, or
+- Your application's ``MongoClient`` instance
 
-- in your application framework's configuration files.
+- Your application framework's configuration files
 
 Settings
 ~~~~~~~~
@@ -97,6 +101,33 @@ Settings
    * - Setting
      - Description
 
+   * - :urioption:`connectTimeoutMS`
+
+     - Most drivers default to never time out. Some versions of the 
+       Java drivers (for example, version 3.7) default to ``10``. 
+       
+       *Default:* ``0`` for most drivers. See your :driver:`driver </>` 
+       documentation.
+   
+   * - :urioption:`maxConnecting`
+   
+     - Maximum number of connections a pool may be establishing
+       concurrently.
+
+       ``maxConnecting`` is supported for all drivers **except** the
+       :driver:`Rust Driver </rust/current/>`.
+
+       .. include:: /includes/connection-pool/max-connecting-use-case.rst
+
+       *Default:* ``2``
+   
+   * - :urioption:`maxIdleTimeMS`
+   
+     - The maximum number of milliseconds that a connection can 
+       remain idle in the pool before being removed and closed.
+
+       *Default:* See your :driver:`driver </>` documentation.
+   
    * - :urioption:`maxPoolSize`
 
      - .. _maxpoolsize-cp-setting:
@@ -118,51 +149,31 @@ Settings
 
        *Default*: ``0``
 
-   * - :urioption:`connectTimeoutMS`
-
-     - Most drivers default to never time out. Some versions of the 
-       Java drivers (for example, version 3.7) default to ``10``. 
-       
-       *Default:* ``0`` for most drivers. See your :driver:`driver </>` 
-       documentation.
+   * - :parameter:`ShardingTaskExecutorPoolMaxSize` 
 
-   * - :urioption:`socketTimeoutMS`
+     - Maximum number of outbound connections each TaskExecutor 
+       connection pool can open to any given :binary:`~bin.mongod` 
+       instance.  
 
-     - Number of milliseconds to wait before timeout on a TCP 
-       connection.
-       
-       Do *not* use :urioption:`socketTimeoutMS` as a mechanism for 
-       preventing long-running server operations.
+       *Default*: 2\ :sup:`64` - 1
 
-       Setting low socket timeouts may result in operations that error 
-       before the server responds.
-       
-       *Default*: ``0``, which means no timeout. See your 
-       :driver:`driver </>` documentation.
+       Parameter only applies to sharded deployments.
 
-   * - :urioption:`maxIdleTimeMS`
-   
-     - The maximum number of milliseconds that a connection can 
-       remain idle in the pool before being removed and closed.
+   * - :parameter:`ShardingTaskExecutorPoolMaxSizeForConfigServers`
 
-       *Default:* See your :driver:`driver </>` documentation.
+     - .. include:: /includes/ShardingTaskExecutorPoolMaxSizeForConfigServers-parameter.rst
 
-   * - :urioption:`waitQueueTimeoutMS`
+       *Default*: ``-1``
 
-     - Maximum wait time in milliseconds that a can thread wait for 
-       a connection to become available. A value of ``0`` means there
-       is no limit. 
+       .. versionadded:: 6.0
 
-       *Default*: ``0``. See your :driver:`driver </>` documentation.
-  
    * - :parameter:`ShardingTaskExecutorPoolMinSize` 
 
      - Minimum number of outbound connections each TaskExecutor 
        connection pool can open to any given :binary:`~bin.mongod` 
        instance.
 
-       *Default*: ``1``. See 
-       :parameter:`ShardingTaskExecutorPoolMinSize`.  
+       *Default*: ``1``
 
        Parameter only applies to sharded deployments.
 
@@ -174,24 +185,26 @@ Settings
 
        .. versionadded:: 6.0
 
-   * - :parameter:`ShardingTaskExecutorPoolMaxSize` 
-
-     - Maximum number of outbound connections each TaskExecutor 
-       connection pool can open to any given :binary:`~bin.mongod` 
-       instance.  
-
-       *Default*: 2\ :sup:`64` - 1. See 
-       :parameter:`ShardingTaskExecutorPoolMaxSize`.
+   * - :urioption:`socketTimeoutMS`
 
-       Parameter only applies to sharded deployments.
+     - Number of milliseconds to wait before timeout on a TCP 
+       connection.
+       
+       Do *not* use :urioption:`socketTimeoutMS` as a mechanism for 
+       preventing long-running server operations.
 
-   * - :parameter:`ShardingTaskExecutorPoolMaxSizeForConfigServers`
+       Setting low socket timeouts may result in operations that error 
+       before the server responds.
+       
+       *Default*: ``0``, which means no timeout.
 
-     - .. include:: /includes/ShardingTaskExecutorPoolMaxSizeForConfigServers-parameter.rst
+   * - :urioption:`waitQueueTimeoutMS`
 
-       *Default*: ``-1``
+     - Maximum wait time in milliseconds that a can thread wait for 
+       a connection to become available. A value of ``0`` means there
+       is no limit. 
 
-       .. versionadded:: 6.0
+       *Default*: ``0``
 
 .. toctree::
    :titlesonly:

source/includes/connection-pool/max-connecting-use-case.rst

@@ -0,0 +1,6 @@
+Raising the value of ``maxConnecting`` allows the client to establish
+connection to the server faster, but increases the chance of
+:term:`connection storms <connection storm>`. If the value of
+``maxConnecting`` is too low, your connection pool may experience heavy
+throttling and increased tail latency for clients checking out
+connections.

source/reference/connection-string.txt

@@ -697,6 +697,16 @@ connecting to the MongoDB deployment.
           drivers. For information on your driver, see the
           :driver:`Drivers </>` documentation.
 
+   * - .. urioption:: maxConnecting
+
+     - Maximum number of connections a pool may be establishing
+       concurrently. The default value is ``2``.
+
+       ``maxConnecting`` is supported for all drivers **except** the
+       :driver:`Rust Driver </rust/current/>`.
+
+       .. include:: /includes/connection-pool/max-connecting-use-case.rst
+   
    * - .. urioption:: maxIdleTimeMS
 
      - The maximum number of milliseconds that a connection can remain
@@ -1481,4 +1491,3 @@ The following connects to a sharded cluster with three :binary:`~bin.mongos` ins
 ``D1fficultP%40ssw0rd``:
 
 .. include:: /includes/connection-examples-by-language-sharded.rst
-

source/reference/glossary.txt

@@ -252,6 +252,14 @@ Glossary
       retrying one of the operations in any :term:`write
       conflict`.
 
+   connection storm
+      A scenario where a driver attempts to open more connections to a
+      deployment than that deployment can handle. When requests for new
+      connections fail, the driver requests to establish even more
+      connections in response to the deployment slowing down or failing
+      to open new connections. These continuous requests can overload
+      the deployment and lead to outages.
+
    config database
       An internal database with metadata for a :term:`sharded cluster`.
       Typically, you don't modify the ``config`` database. For more