From 459e6156b20def25b480714caad90a1e3aa5735e Mon Sep 17 00:00:00 2001 From: Joseph Dougherty Date: Thu, 14 Oct 2021 11:28:30 -0400 Subject: [PATCH] DOCSP-16501 adds connection pool overview --- snooty.toml | 1 + .../analyzing-mongodb-performance.txt | 1 + .../connection-pool-overview.txt | 183 ++++++++++++++++++ source/core/security-ldap-external.txt | 2 + source/reference/glossary.txt | 5 + source/tutorial.txt | 2 +- .../connection-pool-performance-tuning.txt | 108 +++++++++++ 7 files changed, 301 insertions(+), 1 deletion(-) create mode 100644 source/administration/connection-pool-overview.txt create mode 100644 source/tutorial/connection-pool-performance-tuning.txt diff --git a/snooty.toml b/snooty.toml index 0036dc0699e..fb9be1516a3 100644 --- a/snooty.toml +++ b/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", diff --git a/source/administration/analyzing-mongodb-performance.txt b/source/administration/analyzing-mongodb-performance.txt index 7f78edca978..ac353caca1f 100644 --- a/source/administration/analyzing-mongodb-performance.txt +++ b/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 diff --git a/source/administration/connection-pool-overview.txt b/source/administration/connection-pool-overview.txt new file mode 100644 index 00000000000..f31ae962a0a --- /dev/null +++ b/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 ` 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 `. + +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 `, + +- 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 diff --git a/source/core/security-ldap-external.txt b/source/core/security-ldap-external.txt index dbb33900921..454fe050cfd 100644 --- a/source/core/security-ldap-external.txt +++ b/source/core/security-ldap-external.txt @@ -92,6 +92,8 @@ authorization: - :ref:`security-kerberos` - :ref:`security-auth-x509` +.. _ldap-connection-pool-behavior: + Connection Pool ~~~~~~~~~~~~~~~ diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 2ecec61ac1f..4e2e0ba90aa 100644 --- a/source/reference/glossary.txt +++ b/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 diff --git a/source/tutorial.txt b/source/tutorial.txt index d1c25dc20d5..3e664a93160 100644 --- a/source/tutorial.txt +++ b/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: diff --git a/source/tutorial/connection-pool-performance-tuning.txt b/source/tutorial/connection-pool-performance-tuning.txt new file mode 100644 index 00000000000..b451ddcdcfe --- /dev/null +++ b/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 ` 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 ` 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 ` 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 `, 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 ` or real time panel + show more connection attempts than expected. + + - Decrease the :ref:`maxPoolSize ` 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).