DOCSP-16501 adds connection pool overview

snooty.toml

@@ -18,6 +18,7 @@ toc_landing_pages = [
    "/administration/analyzing-mongodb-performance",
    "/administration/backup-sharded-clusters",
    "/administration/configuration-and-maintenance",
+   "/administration/connection-pool-overview",
    "/administration/install-community",
    "/administration/install-enterprise-linux",
    "/administration/install-enterprise",

source/administration/analyzing-mongodb-performance.txt

@@ -259,6 +259,7 @@ analyzing or debugging issues with support from MongoDB Inc. engineers.
    :titlesonly:
    :hidden:
 
+   /administration/connection-pool-overview
    /tutorial/manage-the-database-profiler
    /tutorial/transparent-huge-pages
    /reference/ulimit

source/administration/connection-pool-overview.txt

@@ -0,0 +1,183 @@
+.. _connection-pool-overview:
+
+========================
+Connection Pool Overview
+========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+This document describes how to use a connection pool to manage 
+connections between applications and MongoDB instances. 
+
+What is a Connection Pool?
+--------------------------
+
+Definition
+~~~~~~~~~~
+
+A :ref:`connection pool <connection-pool-overview>` is a cache of open,
+ready-to-use database connections maintained by the :driver:`driver </>`. 
+Your application can seamlessly get connections from the pool, perform 
+operations, and return connections back to the pool. Connection pools 
+are thread-safe. 
+
+Benefits of a Connection Pool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A connection pool helps reduce application latency and the number of 
+times new connections are created.
+
+A connection pool creates connections at startup. Applications do not 
+need to manually return connections to the pool. Instead, connections 
+return to the pool automatically.
+
+Some connections are active and some are inactive but available. 
+If your application requests a connection and there’s an available 
+connection in the pool, a new connection does not need to be created.
+
+Create and Use a Connection Pool
+--------------------------------
+
+Use an Instance of your Driver's ``MongoClient`` Object 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most :driver:`drivers </>` provide an object of type ``MongoClient``.
+
+Use one ``MongoClient`` instance per application unless the
+application is connecting to many separate clusters. Each 
+``MongoClient`` instance manages its own connection pool to the 
+MongoDB cluster or node specified when the ``MongoClient`` is created.
+``MongoClient`` objects are thread-safe in most drivers.
+
+.. note::
+
+   Store your ``MongoClient`` instance in a place that is globally
+   accessible by your application. 
+
+Authentication
+~~~~~~~~~~~~~~
+
+To use a connection pool with LDAP, see
+:ref:`LDAP Connection Pool Behavior <ldap-connection-pool-behavior>`.
+
+Sharded Cluster Connection Pooling
+----------------------------------
+
+:binary:`~bin.mongos` routers have connection pools for each node in the 
+cluster. The availability of connections to individual nodes within a 
+sharded cluster affects latency. Operations must wait for a connection
+to be established.
+
+Connection Pool Configuration Settings
+--------------------------------------
+
+To configure the connection pool, set the options:
+
+- through the :ref:`MongoDB URI <mongodb-uri>`, 
+
+- programmatically when building the ``MongoClient`` instance, or
+
+- in your application framework's configuration files.
+
+Settings
+~~~~~~~~
+
+.. list-table::
+   :widths: 25,75                                                          
+   :header-rows: 1
+
+   * - Setting
+     - Description
+
+   * - :urioption:`maxPoolSize`
+
+     - .. _maxpoolsize-cp-setting:
+
+       Maximum number of connections opened in the pool. When the 
+       connection pool reaches the maximum number of connections, new 
+       connections wait up until to the value of 
+       :urioption:`waitQueueTimeoutMS`.
+
+       *Default:* ``100`` 
+
+   * - :urioption:`minPoolSize`
+
+     - .. _minpoolsize-cp-setting:
+
+       Minimum number of connections opened in the pool. 
+       The value of :urioption:`minPoolSize` must be less than 
+       the value of :urioption:`maxPoolSize`.
+
+       *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.
+
+   * - :urioption:`socketTimeoutMS`
+
+     - 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.
+
+       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.
+
+   * - :urioption:`maxIdleTimeMS`
+
+     - Amount of time that a connection can be idle in the pool before 
+       closing. Idle connections close until the number of 
+       open connections equals :urioption:`minPoolSize`.
+
+       *Default:* See your :driver:`driver </>` documentation.
+
+   * - :urioption:`waitQueueTimeoutMS`
+
+     - 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. 
+
+       *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`.  
+
+       This setting only applies to sharded deployments.
+
+   * - :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`.
+
+       This setting only applies to sharded deployments.
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   /tutorial/connection-pool-performance-tuning

source/core/security-ldap-external.txt

@@ -92,6 +92,8 @@ authorization:
 - :ref:`security-kerberos`
 - :ref:`security-auth-x509`
 
+.. _ldap-connection-pool-behavior:
+
 Connection Pool
 ~~~~~~~~~~~~~~~
 

source/reference/glossary.txt

@@ -188,6 +188,11 @@ Glossary
       associated with a :term:`sharded cluster`.
       See :ref:`sharding-config-server`.
 
+   connection pool
+     A cache of database connections maintained by the driver. These 
+     connections are re-used when connections to the database are 
+     required, instead of opening new connections.
+
    container
       A collected set of software and its dependent libraries that are
       packaged together to make transferring between computing

source/tutorial.txt

@@ -116,7 +116,7 @@ Development Patterns
 - :doc:`/tutorial/troubleshoot-map-function`
 - :doc:`/tutorial/troubleshoot-reduce-function`
 - :doc:`/tutorial/store-javascript-function-on-server`
-
+- :doc:`/tutorial/connection-pool-performance-tuning`
 
 
 .. _tutorials-text-search:

source/tutorial/connection-pool-performance-tuning.txt

@@ -0,0 +1,108 @@
+.. _connection-pool-performance-tuning:
+
+====================================
+Tuning Your Connection Pool Settings
+====================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+
+.. list-table::
+   :widths: 25,75
+   :header-rows: 1
+
+   * - Problem
+
+     - Solution
+
+   * - Slow application-side operation times that are not reflected in 
+       the database :doc:`server logs </reference/log-messages>` or the
+       real time panel.
+
+     - Use :urioption:`connectTimeoutMS` to ensure the driver does not 
+       wait indefinitely during the connection phase.
+
+       Set :urioption:`connectTimeoutMS` to a value greater than the 
+       longest network latency you have to a member of the set. 
+
+       For example: if a member has a latency of 10000 milliseconds, 
+       setting :urioption:`connectTimeoutMS` to ``5000`` 
+       (milliseconds) prevents the driver from connecting to that 
+       member.
+
+   * - A misconfigured firewall closes a socket connection incorrectly
+       and the driver cannot detect that the connection closed 
+       improperly. 
+
+     - Use :urioption:`socketTimeoutMS` to ensure that sockets are 
+       always closed. 
+
+       Set :urioption:`socketTimeoutMS` to two or three times the 
+       length of the slowest operation that the driver runs.
+
+   * - The :doc:`server logs </reference/log-messages>` or real time panel
+       show that the application spends too much time creating new 
+       connections.
+
+     - Not enough connections are available at startup. 
+       Allocate connections in the pool by setting 
+       :urioption:`minPoolSize`. 
+
+       Set :ref:`minPoolSize <minpoolsize-cp-setting>` to the number 
+       of connections you want to be available at startup.
+
+       The ``MongoClient`` instance ensures that number of 
+       connections exists at all times. 
+
+   * - The load on the database is low and there's a small number of 
+       active connections at any time. Application performs fewer 
+       operations at any one time than expected. 
+
+     - Increase :ref:`maxPoolSize <maxpoolsize-cp-setting>`, or increase 
+       the number of active threads in your application or the framework 
+       you are using. 
+
+   * - Database CPU usage is higher than expected. The 
+       :doc:`server logs </reference/log-messages>` or real time panel
+       show more connection attempts than expected.
+
+     - Decrease the :ref:`maxPoolSize <maxpoolsize-cp-setting>` or 
+       reduce the number of threads in your application. This can reduce 
+       load and response times.
+
+.. warning::
+
+   Do not use :urioption:`socketTimeoutMS` to prevent long-running 
+   server operations. Instead, use :method:`~cursor.maxTimeMS` with 
+   queries so that the server can cancel long-running operations.
+
+
+Calculate Maximum Number of Connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Calculate usage to find the number of operations running for each
+connection.
+
+Consider four application servers connecting to a replica set with three
+members. In this scenario, each of the four application servers
+creates a connection pool for each replica set member.
+
+Calculate the maximum number of connections that are opened by 
+each application server by multiplying :urioption:`maxPoolSize` by the 
+number of members.  
+
+Calculate outgoing connections from an application to a three-member 
+replica set:
+
+**100** (:urioption:`maxPoolSize` default ``100``) x **3** (replica set members) = **300** (outgoing connections from the application).
+
+Calculate incoming connections from four application servers to a 
+replica set:
+
+**100** (:urioption:`maxPoolSize` default ``100``) x **4** (application servers) = **400** (incoming connections to each mongod).