Skip to content

Commit a7d8c2c

Browse files
rustagirrustagir
authored
DOCSP-24557: FAQ page (#21)
* DOCSP-24557: faq page * first pass fixes * code block fix * PR comments 1
1 parent b135a69 commit a7d8c2c

File tree

2 files changed

+177
-0
lines changed

2 files changed

+177
-0
lines changed

‎source/faq.txt

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
.. _csharp-faq:
2+
3+
===
4+
FAQ
5+
===
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Why Does the Driver Throw a Timeout During Server Selection?
16+
------------------------------------------------------------
17+
18+
Each driver operation requires that you choose a healthy server
19+
satisfying the :manual:`server selection criteria
20+
</core/read-preference-mechanics>`. If you do not select an appropriate
21+
server within the `server selection timeout <{+api-root+}/P_MongoDB_Driver_MongoServerSettings_ServerSelectionTimeout.htm>`__, the driver throws a
22+
server selection timeout exception. The exception looks similar to the
23+
following:
24+
25+
.. code-block:: none
26+
27+
A timeout occurred after 30000ms selecting a server using CompositeServerSelector{ Selectors = MongoDB.Driver.MongoClient+AreSessionsSupportedServerSelector, LatencyLimitingServerSelector{ AllowedLatencyRange = 00:00:00.0150000 }, OperationsCountServerSelector }.
28+
Client view of cluster state is
29+
{
30+
ClusterId : "1",
31+
Type : "Unknown",
32+
State : "Disconnected",
33+
Servers :
34+
[{
35+
ServerId: "{ ClusterId : 1, EndPoint : "Unspecified/localhost:27017" }",
36+
EndPoint: "Unspecified/localhost:27017",
37+
ReasonChanged: "Heartbeat",
38+
State: "Disconnected",
39+
ServerVersion: ,
40+
TopologyVersion: ,
41+
Type: "Unknown",
42+
HeartbeatException: "<exception details>"
43+
}]
44+
}.
45+
46+
The error message consists of multiple parts:
47+
48+
1. The server selection timeout (30000 ms).
49+
#. The server selectors considered (``CompositeServerSelector``
50+
containing ``AreSessionsSupportedServerSelector``,
51+
``LatencyLimitingServerSelector``, and
52+
``OperationsCountServerSelector``).
53+
#. The driver’s current view of the cluster topology. The list of
54+
servers that the driver is aware of is a key part of this view. Each
55+
server description contains an exhaustive description of its current
56+
state including information about an endpoint, a server version, a
57+
server type, and its current health state. If the server is not
58+
heathy, ``HeartbeatException`` contains the exception from the
59+
last failed heartbeat. Analyzing the ``HeartbeatException`` on each
60+
cluster node can assist in diagnosing most server selection issues.
61+
The following heartbeat exceptions are common:
62+
63+
* ``No connection could be made because the target machine actively
64+
refused it``: The driver cannot see this cluster node. This can be
65+
because the cluster node has crashed, a firewall is preventing
66+
network traffic from reaching the cluster node or port, or some other
67+
network error is preventing traffic from being successfully routed to
68+
the cluster node.
69+
* ``Attempted to read past the end of the stream``: This error
70+
happens when the driver cannot connect to the cluster nodes due to a
71+
network error, misconfigured firewall, or other network issue. To
72+
address this exception, ensure that all cluster nodes are reachable.
73+
This error commonly occurs when the client machine’s IP address is
74+
not configured in the Atlas IPs Access List, which can be found under
75+
the :guilabel:`Network Access` tab for your Atlas Project.
76+
* ``The remote certificate is invalid according to the validation
77+
procedure``: This error typically indicates a TLS/SSL-related problem
78+
such as an expired/invalid certificate or an untrusted root CA. You
79+
can use tools like ``openssl s_client`` to debug TLS/SSL-related
80+
certificate problems.
81+
82+
Why is the Wait Queue for Acquiring a Connection to the Server Full?
83+
--------------------------------------------------------------------
84+
85+
This exception usually indicates a threading or concurrency problem in
86+
your application. The driver checks out a connection from the selected
87+
server’s connection pool for every read or write operation. If
88+
the connection pool is already at ``maxPoolSize`` - 100 by default - then the
89+
requesting thread blocks in a wait queue. The wait queue's default size
90+
is 5 times ``maxPoolSize``, or 500. If the wait queue is also full, the driver
91+
throws a ``MongoWaitQueueFullException``. The exception looks
92+
similar to the following:
93+
94+
.. code-block:: none
95+
96+
MongoDB.Driver.MongoWaitQueueFullException: The wait queue for
97+
acquiring a connection to server myServer is full.
98+
99+
To resolve this issue, try the following steps:
100+
101+
1. Tune your indexes. By improving the performance of your queries,
102+
you can reduce the time that operations take and reduce the number of
103+
concurrent connections needed for your workload.
104+
#. If you have long-running analytical queries, you may wish to isolate
105+
them to dedicated analytics nodes using :manual:`read preference tags
106+
</core/read-preference/>` or a hidden secondary.
107+
#. Increase ``maxPoolSize`` to allow more simultaneous operations to a
108+
given cluster node. If your MongoDB cluster does not have sufficient
109+
resources to handle the additional connections and simultaneous
110+
workload, performance can decrease due to resource contention
111+
on the cluster nodes. Adjust this setting only with careful
112+
consideration and testing.
113+
#. Increase ``waitQueueMultiple`` to allow more threads/tasks to block
114+
waiting for a connection. This is rarely the appropriate solution and
115+
can severely affect your application performance. Before
116+
considering changes to this setting, address the concurrency problems
117+
in your application.
118+
119+
Why are Certain LINQ or Builder Expressions Unsupported?
120+
--------------------------------------------------------
121+
122+
Each LINQ or Builder expression must be available in the Query API. This is not
123+
always possible for the following reasons:
124+
125+
1. You are attempting to use a {+lang-framework+} feature that does not have an
126+
equivalent MongoDB representation. For example, {+lang-framework+} and MongoDB have
127+
different semantics around collations.
128+
#. The driver does not support a particular transformation from LINQ or
129+
Builder expression into a server query. This may happen because the
130+
provided query is too complicated or because a feature has not been
131+
implemented yet in the driver.
132+
133+
If you receive an ``Unsupported filter ...`` or ``Expression not
134+
supported ...`` exception message, try the following
135+
steps:
136+
137+
1. Try configuring the new `LINQ3
138+
<https://mongodb.github.io/mongo-csharp-driver/2.17/reference/driver/crud/linq3/>`__
139+
provider. The LINQ3 provider contains many fixes and new features
140+
over the LINQ2 provider.
141+
#. Try to simplify your query where possible.
142+
#. Provide a query as a ``BsonDocument`` or JSON string. All driver
143+
definition classes such as ``FilterDefinition``,
144+
``ProjectionDefinition``, and ``PipelineDefinition`` support implicit
145+
conversion from ``BsonDocument`` or JSON string. For example, the
146+
following filters are equivalent when used in a query or
147+
aggregation:
148+
149+
.. code-block:: csharp
150+
151+
FilterDefinition<Entity> typedFilter = Builders<Entity>.Filter.Eq(e => e.A, 1);
152+
FilterDefinition<Entity> bsonFilter = new BsonDocument {{ "a", 1 }};
153+
FilterDefinition<Entity> jsonFilter = "{ a : 1 }";
154+
155+
.. note::
156+
157+
If you use ``BsonDocument`` or JSON string, then `BsonClassMap
158+
<https://mongodb.github.io/mongo-csharp-driver/2.17/reference/bson/mapping/>`__,
159+
BSON serialization attributes, and serialization conventions are not
160+
taken into account in the Query API. Field names must match the
161+
names and casing as stored by the server. For example, when referencing
162+
the ``_id`` field, you must refer to it using ``_id`` in
163+
``BsonDocument`` or JSON string definitions. Similarly, if a document
164+
has a field ``FirstName`` annotated with ``[BsonElement("first_name")]``, you
165+
must refer to it as ``first_name`` in ``BsonDocument`` or JSON string
166+
definitions.
167+
168+
You can combine the raw and typed forms in the same query, as the
169+
following code demonstrates:
170+
171+
.. code-block:: csharp
172+
173+
FilterDefinition<Entity> filter = Builders<Entity>.Filter
174+
.And(Builders<Entity>.Filter
175+
.Eq(e => e.A, 1), BsonDocument
176+
.Parse("{ b : 2 }"));

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,5 @@ MongoDB C# Driver
99
/quick-start
1010
/usage-examples
1111
/compatibility
12+
/faq
1213
/issues-and-help

0 commit comments

Comments
 (0)