Skip to content

Commit d62c455

Browse files
author
Mohammad Hunan Chughtai
authored
Docsp 8053 faq common iss (#53)
* test push * (DOCSP-8053): updated source to include faq and common issues page * updated spacing * updated statement to questions * removed temp placeholder txt * fixed format * removed odd question * updated wording for simplicity * update verbiage * fixed link format * updated links * updated link formatting * updated link formatting * updated link formatting * updated verbiage * added file desc link * update txt formatting * added diff b/w connectTimeout, socketTimeout, and maxtimems ques * added connection-settings subtext as additional questions * cleaned text for How can I prevent the driver from hanging during connection or from spending too long trying to reach unreachable replica sets? * updated wording for Should I use socketTimeoutMS as a way to prevent long-running operations from slowing down the server? * update formatting * update formatting * update formatting * update wording on How can I prevent sockets from timing out before they become active? * updated wording for question How can I prevent long-running operations from slowing down the server? * updated wording for What does the keepAlive setting do? * fixed formatting + updated wording for What can I do if I'm experiencing unexpected network behavior? * updated numbered bullets formatting * added code snippets to code snippets folder and literal included + fixed title casing * fixed formatting * update formatting * fixed formatting * updated issues and help * Test push content * test content formatting * (DOCSP-8053): cleaned up unneeded question * replaced monospacing with quotes for headers
1 parent 284db91 commit d62c455

File tree

4 files changed

+273
-0
lines changed

4 files changed

+273
-0
lines changed

‎source/code-snippets/faq/econnresetWithClientConnect-example.js

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// create a new MongoClient
2+
const client = new MongoClient(
3+
"mongodb://localhost:27017/test?maxPoolSize=5000",
4+
);
5+
client.connect(function(err) {
6+
// connection
7+
});

‎source/code-snippets/faq/maxTimeMS-example.js

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
// Execute a find command
2+
collection
3+
.find({ $where: "sleep(100) || true" })
4+
.maxTimeMS(50)
5+
.count(function(err, count) {});

‎source/faq.txt

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,209 @@ FAQ
55
.. default-domain:: mongodb
66

77
Frequently Asked Questions
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
16+
What Is the Difference Between "connectTimeoutMS", "socketTimeoutMS" and "maxTimeMS" ?
17+
--------------------------------------------------------------------------------------------
18+
19+
.. list-table::
20+
:header-rows: 1
21+
22+
* - Setting
23+
- Default Value
24+
- Description
25+
* - connectTimeoutMS
26+
- 30000
27+
- ``connectTimeoutMS`` is a `connection-setting <https://mongodb.github.io/node-mongodb-native/3.5/reference/connecting/connection-settings/>`_ option that sets the time in milliseconds to establish a connection to the MongoDB server before timing out.
28+
* - socketTimeoutMS
29+
- 360000
30+
- ``socketTimeoutMS`` is a ``connection-settings`` option that sets the number of milliseconds a socket stays inactive after the driver has successfully connected before closing the connection.
31+
* - maxTimeMS
32+
- N/A
33+
- :node-api:`maxTimeMS() </Cursor.html#maxTimeMS>` is a :manual:`cursor method </reference/method/js-cursor>` that specifies the max time limit for processing an operation on a cursor. If an operation runs over the time allotted it will return a timeout error.
34+
35+
How Can I Prevent the Driver From Hanging During Connection or From Spending Too Long Trying to Reach Unreachable Replica Sets?
36+
-------------------------------------------------------------------------------------------------------------------------------
37+
38+
To prevent the driver from hanging during connection or to prevent the
39+
driver from spending too long trying to reach unreachable replica sets,
40+
you can set the ``connectTimeoutMS`` option of your
41+
``connection-settings``. Generally, you should ensure that the
42+
``connectTimeoutMS`` setting is not lower than the longest network
43+
latency you have to a member of the set. If one of the secondary members
44+
is on the other side of the planet and has a latency of 10000
45+
milliseconds, setting the ``connectTimeoutMS`` to anything lower will
46+
prevent the driver from ever connecting to that member.
47+
48+
Should I Use "socketTimeoutMS" as a Way of Preventing Long-Running Operations From Slowing Down the Server?
49+
-------------------------------------------------------------------------------------------------------------
50+
51+
No, you should **not** use ``socketTimeoutMS`` to end operations that
52+
may run for too long and slow down the application. Attempting to do so
53+
may not achieve the intended result.
54+
55+
Closing the socket causes a reconnect of the driver's connection pool,
56+
introducing latency to any other queued up operations. Chronically slow
57+
operations will, therefore, cause a large number of reconnect requests,
58+
negatively impacting throughput and performance.
59+
60+
Also, closing the socket does not terminate the operation; it will
61+
continue to run on the MongoDB server, which could cause data
62+
inconsistencies if the application retries the operation on failure.
63+
64+
However, there are important use cases for ``socketTimeoutMS`` -
65+
consider the following cases:
66+
67+
- A MongoDB process erroring out
68+
- A misconfigured firewall causing a socket connection without sending a ``FIN`` packet
69+
70+
In those cases, there is no way to detect that the connection has died.
71+
Setting the ``socketTimeoutMS`` is essential to ensure that the sockets
72+
are closed correctly. A good rule of thumb is to set ``socketTimeoutMS``
73+
to two to three times the length of the slowest operation that runs
74+
through the driver.
75+
76+
How Can I Prevent Sockets From Timing out Before They Become Active?
77+
--------------------------------------------------------------------
78+
Having a large connection pool does not always reduce reconnection
79+
requests. Consider the following example:
80+
81+
An application has a connection pool size of 5 sockets and has the
82+
``socketTimeoutMS`` option set to 5000 milliseconds. Operations occur,
83+
on average, every 3000 milliseconds, and reconnection requests are
84+
frequent. Each socket times out after 5000 milliseconds, which means
85+
that all sockets must do something during those 5000 milliseconds to
86+
avoid closing.
87+
88+
One message every 3000 milliseconds is not enough to keep the sockets
89+
active, so several of the sockets will time out after 5000 milliseconds.
90+
Reduce the ``poolSize`` in the connection settings to fix the problem.
91+
92+
What Does a Value of "0" mean for "connectTimeoutMS" and "socketTimeoutMS"?
93+
---------------------------------------------------------------------------
94+
95+
Setting ``connectTimeoutMS`` and ``socketTimeoutMS`` to the value ``0`` has
96+
causes the application to use the operating system's default socket timeout value.
97+
98+
How Can I Prevent Long-Running Operations From Slowing Down the Server?
99+
-----------------------------------------------------------------------
100+
101+
By using ``maxTimeMS()`` you can prevent long-running operations from
102+
slowing down the server. This method allows the MongoDB server to cancel
103+
operations that run for more than the set value of ``maxTimeMS``.
104+
105+
The following example demonstrates how to use MaxTimeMS with a find
106+
operation:
107+
108+
.. literalinclude:: /code-snippets/faq/maxTimeMS-example.js
109+
:language: javascript
110+
:linenos:
111+
112+
What Does the "keepAlive" Setting Do?
113+
---------------------------------------
114+
115+
``keepAlive`` is a ``connection-setting`` that sets the number of
116+
milliseconds to wait before initiating a :wikipedia:`TLS keepAlive
117+
<Keepalive#TCP_keepalive>` on a TCP Socket. The ``keepAlive`` option
118+
will keep a socket alive by sending periodic probes to MongoDB. However,
119+
this only works if the operating system supports ``SO_KEEPALIVE``\ .
120+
121+
.. warning::
122+
If a firewall ignores or drops the ``keepAlive`` packets this may not work
123+
124+
What Can I Do If I'm Experiencing Unexpected Network Behavior?
125+
--------------------------------------------------------------
126+
Internal firewalls that exist between application servers and MongoDB
127+
are often misconfigured and are overly aggressive in their removal of
128+
socket connections.
129+
130+
If you experience unexpected network behavior, here
131+
are some things to check:
132+
133+
#. The firewall should send a ``FIN packet`` when closing a socket,allowing the driver to detect that the socket is closed.
134+
#. The firewall should allow ``keepAlive`` probes.
135+
136+
What Can I Do If I'm Getting "ECONNRESET" When Calling "client.connect()"?
137+
------------------------------------------------------------------------------
138+
139+
In most operating systems, each connection is associated with a `file
140+
descriptor
141+
<https://www.computerhope.com/jargon/f/file-descriptor.htm>`_. There is
142+
typically a limit set by the operating system on the number of file
143+
descriptors used by a single process. An ``ECONNRESET`` error can occur
144+
if the connection pool size surpasses the limit of ``file descriptors``.
145+
146+
Consider the following operation:
147+
148+
.. literalinclude:: /code-snippets/faq/econnresetWithClientConnect-example.js
149+
:language: javascript
150+
:linenos:
151+
152+
If this operation causes an ``ECONNRESET`` error, you may have run into
153+
the ``file descriptor`` limit for your Node.js process. In that case you
154+
must increase the number of ``file descriptors`` for the Node.js process. On
155+
MacOS and Linux you do this with the `ulimit
156+
<https://ss64.com/bash/ulimit.html>`_ shell command.
157+
158+
.. code-block:: sh
159+
160+
ulimit -n 6000
161+
162+
This sets the maximum number of ``file descriptors`` for the process to
163+
6000, allowing Node.js to connect with a pool size of 5000 sockets.
164+
165+
How Can I Prevent a Slow Operation From Delaying Other Operations?
166+
------------------------------------------------------------------
167+
168+
A slow operation may delay your other operations that occur after it, if
169+
the ``poolSize`` has not been set in the `connection settings
170+
<https://mongodb.github.io/node-mongodb-native/3.5/reference/connecting/connection-settings/>`_.
171+
MongoDB is synchronous and uses a single execution thread per socket,
172+
meaning that MongoDB will execute one single operation per socket at any
173+
point in time. Any other operation sent to that socket will have to wait
174+
until the current operation is finished. If you have a slow-running
175+
operation that holds up other operations, the best solution is to create
176+
a separate connection pool for the slow operation, isolating it from
177+
other, faster operations.
178+
179+
.. note::
180+
If the number of operations is greater than the set ``poolSize`` and
181+
a slow operation occurs, subsequent operations will be delayed.
182+
183+
How Can I Ensure My Connection String Is Valid for a Replica Set?
184+
-----------------------------------------------------------------
185+
186+
The connection string passed to the driver must use exact hostnames for
187+
the servers as set in the :manual:`Replica Set Config </reference/replica-configuration/>`.
188+
Given the following configuration settings for your `Replica Set`, in
189+
order for the `Replica Set` discovery and :manual:`failover
190+
</reference/glossary/#term-failover>` to work the driver should be able
191+
to reach ``server1``, ``server2``, and ``server3``.
192+
193+
.. code-block:: JSON
194+
195+
{
196+
"_id": "testSet",
197+
"version": 1,
198+
"protocolVersion": 1,
199+
"members": [
200+
{
201+
"_id": 1,
202+
"host": "server1:31000"
203+
},
204+
{
205+
"_id": 2,
206+
"host": "server2:31001"
207+
},
208+
{
209+
"_id": 3,
210+
"host": "server3:31002"
211+
}
212+
]
213+
}

‎source/issues-and-help.txt

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,58 @@ Issues & Help
33
=============
44

55
.. default-domain:: mongodb
6+
7+
Our developer community is vibrant and highly engaged, with extensive experience using Node.js with MongoDB.
8+
Often, the quickest way to get support for
9+
general questions is through the `mongodb-user google group <http://groups.google.com/group/mongodb-user>`_
10+
or through `stackoverflow <http://stackoverflow.com/questions/tagged/mongodb+nodejs>`_.
11+
12+
Refer to our `support channels <http://www.mongodb.org/about/support>`_ documentation for more information.
13+
14+
Bugs / Feature Requests
15+
-----------------------
16+
17+
To report a bug or to request a new feature in the Node.js driver,
18+
please open a case in our issue management tool, JIRA:
19+
20+
21+
* `Create an account and login <https://jira.mongodb.org>`_.
22+
* Navigate to `the NODE project <https://jira.mongodb.org/browse/NODE>`_.
23+
* Click **Create Issue**. Please provide as much information as possible about the
24+
issue and the steps to reproduce it.
25+
26+
Bug reports in JIRA for the Node.js driver and the Core Server (i.e. SERVER) project are **public**.
27+
28+
If you’ve identified a security vulnerability in a driver or any other
29+
MongoDB project, please report it according to the instructions found in the `Create a Vulnerability Report <http://docs.mongodb.org/manual/tutorial/create-a-vulnerability-report>`_.
30+
31+
Pull Requests
32+
-------------
33+
34+
We are happy to accept contributions to help improve the driver.
35+
We will review user contributions to ensure they meet the standards of the codebase.
36+
Pull requests must pass the ``travis.ci`` checks as well as include documentation
37+
and tests.
38+
39+
To get started check out the source and work on a branch:
40+
41+
.. code-block:: bash
42+
43+
git clone https://github.com/mongodb/node-mongodb-native.git
44+
cd node-mongodb-native
45+
npm install
46+
git checkout -b myNewFeature
47+
48+
To run the test suite, you must have a server topology running and provide the URI to the command.
49+
For example, if you have a single server running at ``"mongodb://localhost:27017"``, you can run the following:
50+
51+
.. code-block:: bash
52+
53+
MONGODB_URI="mongodb://localhost:27017" npm test
54+
55+
Note that, depending on the type of topology that you are running (standalone, replicaset, etc.), different tests will be run.
56+
57+
.. note::
58+
59+
There are many tools that can help you with setting up different topologies for local testing.
60+
Some examples are `mtools <https://pypi.org/project/mtools/>`_ and `mongo-orchestration <https://pypi.org/project/mongo-orchestration/>`_.

0 commit comments

Comments
 (0)