Skip to content

Commit a5de5ad

Browse files
jmikolajmikola
committed
PHPLIB-790: Server Selection docs
1 parent c8aa4af commit a5de5ad

File tree

2 files changed

+135
-0
lines changed

2 files changed

+135
-0
lines changed

‎docs/faq.txt

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
==========================
2+
Frequently Asked Questions
3+
==========================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Server Selection and Monitoring
14+
-------------------------------
15+
16+
Before an operation can be executed, the |php-library| must first select a
17+
server from the topology (e.g. replica set, sharded cluster). Selecting a server
18+
requires an accurate view of the topology, so the driver (i.e. ``mongodb``
19+
extension) regularly monitors the servers to which it is connected. This process
20+
is discussed in more detail in the following:
21+
22+
- `Single-threaded Mode <http://mongoc.org/libmongoc/current/connection-pooling.html#single-mode>`_ in the libmongoc documentation
23+
- `Server Discovery and Monitoring <https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst>`_ specification
24+
- `Server Selection <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst>`_ specification
25+
26+
The following connection string and URI options are relevant to server selection
27+
and monitoring:
28+
29+
connectTimeoutMS
30+
~~~~~~~~~~~~~~~~
31+
32+
``connectTimeoutMS`` specifies the limit for both establishing a connection to
33+
a server *and* the socket timeout for server monitoring (``hello`` commands).
34+
This defaults to 10 seconds for single-threaded drivers such as PHP.
35+
36+
When a server times out during monitoring, it will not be re-checked until at
37+
least five seconds
38+
(`cooldownMS <https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-monitoring.rst#cooldownms>`_)
39+
have elapsed. This timeout is intended to avoid having single-threaded drivers
40+
block for ``connectTimeoutMS`` on *each* subsequent scan after an error.
41+
42+
Applications can consider setting this option to slightly more than the greatest
43+
latency among servers in the cluster. For example, if the greatest ``ping`` time
44+
between the PHP application server and a database server is 200ms, it may be
45+
reasonable to specify a timeout of one second. This would allow ample time for
46+
establishing a connection and monitoring an accessible server, while also
47+
significantly reducing the time to detect an inaccessible server.
48+
49+
heartbeatFrequencyMS
50+
~~~~~~~~~~~~~~~~~~~~
51+
52+
``heartbeatFrequencyMS`` determines how often monitoring should occur. This
53+
defaults to 60 seconds for single-threaded drivers and can be set as low as
54+
500ms.
55+
56+
serverSelectionTimeoutMS
57+
~~~~~~~~~~~~~~~~~~~~~~~~
58+
59+
``serverSelectionTimeoutMS`` determines the maximum amount of time to spend in
60+
the server selection loop. This defaults to 30 seconds, but applications will
61+
typically fail sooner if ``serverSelectionTryOnce`` is ``true`` and a smaller
62+
``connectTimeoutMS`` value is in effect.
63+
64+
The original default was established at a time when replica set elections took
65+
much longer to complete. Applications can consider setting this option to
66+
slightly more than the expected completion time for an election. For example,
67+
:manual:`Replica Set Elections </core/replica-set-elections/>` states that
68+
elections will not typically exceed 12 seconds, so a 15-second timeout may be
69+
reasonable. Applications connecting to a sharded cluster may consider a smaller
70+
value still, since ``mongos`` insulates the driver from elections.
71+
72+
That said, ``serverSelectionTimeoutMS`` should generally not be set to a value
73+
smaller than ``connectTimeoutMS``.
74+
75+
serverSelectionTryOnce
76+
~~~~~~~~~~~~~~~~~~~~~~
77+
78+
``serverSelectionTryOnce`` determines whether the driver should give up after
79+
the first failed server selection attempt or continue waiting until
80+
``serverSelectionTimeoutMS`` is reached. PHP defaults to ``true``, which allows
81+
the driver to "fail fast" when a server cannot be selected (e.g. no primary
82+
during a failover).
83+
84+
The default behavior is generally desirable for a high-traffic web applications,
85+
as it means the worker process will not be blocked in a server selection loop
86+
and can instead return an error response and immediately go on to serve another
87+
request. Additionally, other driver features such as retryable reads and writes
88+
can still enable applications to avoid transient errors such as a failover.
89+
90+
That said, applications that prioritize resiliency over response time (and
91+
worker pool utilization) may want to specify ``false`` for
92+
``serverSelectionTryOnce``.
93+
94+
socketCheckIntervalMS
95+
~~~~~~~~~~~~~~~~~~~~~
96+
97+
``socketCheckIntervalMS`` determines how often a socket should be checked (using
98+
a ``ping`` command) if it has not been used recently. This defaults to 5 seconds
99+
and is intentionally lower than ``heartbeatFrequencyMS`` to better allow
100+
single-threaded drivers to recover dropped connections.
101+
102+
The purpose of this option is explained in greater detail in the
103+
`Server Selection <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#what-is-the-purpose-of-socketcheckintervalms>`_ spec.
104+
105+
socketTimeoutMS
106+
~~~~~~~~~~~~~~~
107+
108+
``socketTimeoutMS`` determines the maximum amount of time to spend reading or
109+
writing to a socket. Since server monitoring uses ``connectTimeoutMS`` for its
110+
socket timeouts, ``socketTimeoutMS`` only applies to operations executed by the
111+
application.
112+
113+
``socketTimeoutMS`` defaults to 5 minutes; however, it's likely that a PHP web
114+
request would be terminated sooner due to
115+
`max_execution_time <https://www.php.net/manual/en/info.configuration.php#ini.max-execution-time>`_,
116+
which defaults to 30 seconds for web SAPIs. In a CLI environment, where
117+
``max_execution_time`` is unlimited by default, it is more likely that
118+
``socketTimeoutMS`` could be reached.
119+
120+
.. note::
121+
122+
``socketTimeoutMS`` is not directly related to server selection and
123+
monitoring; however, it is frequently associated with the other options and
124+
therefore bears mentioning.
125+
126+
Server Selection Failures
127+
-------------------------
128+
129+
For example:
130+
131+
.. code-block:: none
132+
133+
No suitable servers found (`serverSelectionTryOnce` set): [connection refused calling hello on 'example.com:27017']
134+

‎docs/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,4 @@ encounter in the library documentation:
6666
/tutorial
6767
/upgrade
6868
/reference
69+
/faq

0 commit comments

Comments
 (0)