diff --git a/snooty.toml b/snooty.toml index 1f20e7e9..752e3cee 100644 --- a/snooty.toml +++ b/snooty.toml @@ -8,14 +8,16 @@ intersphinx = [ ] toc_landing_pages = [ - "/write-operations", - "/read", "/connect", "/indexes", - "work-with-indexes", + "/work-with-indexes", "/data-formats", "/builders", "/aggregation", + "/connect/connection-options", + "/logging-and-monitoring", + "/databases-and-collections", + "/api" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/connect.txt b/source/connect.txt index cc47d76d..ca6d1a99 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -19,15 +19,12 @@ Connection Guide :keywords: client, ssl, tls, localhost .. toctree:: - :titlesonly: - :maxdepth: 1 Create a MongoClient Choose a Connection Target - Connection Options + Connection Options AWS Lambda - -.. /connect/connection-troubleshooting + Connection Troubleshooting Overview -------- diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 2c065e10..f01765be 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -4,12 +4,6 @@ Specify Connection Options ========================== -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - .. facet:: :name: genre :values: reference @@ -23,9 +17,10 @@ Specify Connection Options Stable API Limit Server Execution Time + Connection Pools .. /connect/network-compression -.. /connect/server-selection +.. /connect/server-selection Overview -------- diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt new file mode 100644 index 00000000..e8b95f19 --- /dev/null +++ b/source/connect/connection-pools.txt @@ -0,0 +1,16 @@ +.. _kotlin-sync-connection-pools: + +================ +Connection Pools +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + + +.. _kotlin-sync-connection-pool-settings: + +.. TODO \ No newline at end of file diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index f0332efd..3696be0d 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -70,6 +70,8 @@ deployment: :end-before: end-connect-local :dedent: +.. _kotlin-sync-connect-replica-set: + Replica Sets ------------ diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt new file mode 100644 index 00000000..06fe1a59 --- /dev/null +++ b/source/connect/connection-troubleshooting.txt @@ -0,0 +1,308 @@ +.. _kotlin-sync-connection-troubleshooting: + +========================== +Connection Troubleshooting +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, disconnected, deployment + +.. sharedinclude:: dbx/connection-troubleshooting.rst + + .. replacement:: non-connection-issue-callout + + .. note:: + + This page addresses only connection issues. If you encounter other + issues when using MongoDB or the driver, visit the following resources: + + - The :ref:`Issues & Help ` page for + information about reporting bugs, contributing to the driver, and + finding more resources + - The :community-forum:`MongoDB Community Forums ` for + questions, discussions, or general technical support + + .. replacement:: server-selection-timeout-error + + .. code-block:: none + :copyable: false + + Error: couldn't connect to server 127.0.0.1:27017 + + .. replacement:: check-connection-string-anchor + + .. _kotlin-sync-connection-string-port: + + .. replacement:: multiple-hosts-connection-guide-link + + To learn how to specify multiple replica set hosts, see the + :ref:`kotlin-sync-connect-replica-set` section of the Connection Guide. + + .. replacement:: configure-firewall-anchor + + .. _kotlin-sync-connection-firewall: + + .. replacement:: authentication-error-anchor + + .. _kotlin-sync-authentication-error: + + .. replacement:: scram-failure-error + + .. code-block:: none + :copyable: false + + Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017. + + .. replacement:: check-credentials-formatting-anchor + + .. _kotlin-sync-connection-string-auth: + + .. replacement:: learn-more-connection-string-admonition + + .. tip:: + + For more information about using connection strings, + see :ref:`Connection URI ` in the Connection Guide. + + .. replacement:: percent-encode-example + + .. replacement:: verify-authentication-database-anchor + + .. _kotlin-sync-verify-auth-db: + + .. replacement:: credentials-provider-alternative-method-description + + If you construct a client by using a ``MongoCredential``, the builder method + corresponds to the authentication mechanism. The following code shows the builder + method for the ``SCRAM-SHA-256`` authentication mechanism: + + .. code-block:: kotlin + :copyable: false + + val credential = MongoCredential.createScramSha256Credential( + "", "", "".toCharArray() + ) + + val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("", )) + ) + } + .credential(credential) + .build() + + val mongoClient = MongoClient.create(settings) + + .. replacement:: authentication-guide-reference + + To learn more about specifying authentication mechanisms, see the :ref:`kotlin-sync-auth` + section. + + .. replacement:: verify-authentication-mechanism-anchor + + .. _kotlin-sync-verify-auth-mechanism: + + .. replacement:: authsource-param-code-block + + .. code-block:: kotlin + :copyable: false + + val mongoClient = MongoClient.create("mongodb://:@:/?authSource=users"); + + .. replacement:: dns-resolution-anchor + + .. _kotlin-sync-dns-resolution-error: + + .. replacement:: dns-error-message + + .. code-block:: none + :copyable: false + + com.mongodb.MongoSocketWriteException: Exception sending message + + .. replacement:: check-the-number-of-connections-anchor + + .. _kotlin-sync-connection-num-connections: + + .. replacement:: mongo-client-class + + ``MongoClient`` + + .. replacement:: max-pool-size-param + + ``maxPoolSize`` + + .. replacement:: max-pool-size-default + + ``100`` + + .. replacement:: max-idle-time-param + + ``maxIdleTimeMS`` + + .. replacement:: scram-failure-error + + .. code-block:: + + Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017. + + .. replacement:: check-credentials-formatting-anchor + + .. _kotlin-sync-troubleshooting-connection-string-auth: + + .. replacement:: connection-pools-learn-more + + To learn more about how connection pooling works in the driver, see the + :ref:`Connection Pools ` page. + +.. _kotlin-sync-timeout-errors: + +Timeout Errors +-------------- + +When you send messages through the driver to the server, sometimes the +messages take a while to respond. When this happens, you might receive an error +message similar to one of the following messages: + +.. code-block:: none + :copyable: false + + Timed out after 30000 ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. + +.. code-block:: none + :copyable: false + + No server chosen by ReadPreferenceServerSelector{readPreference=primary} from cluster description + +If you receive one of these errors, try the following methods to resolve the +issue. + +Set ``maxConnectionTimeoutMS`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``maxConnectionTimeoutMS`` option indicates the time the {+driver-short+} waits +for a connection before timing out. The default value is ``10000``. You can +increase this value or set it to ``0`` if you want the driver to never timeout. + +Set ``maxConnectionLifeTime`` and ``maxConnectionIdleTime`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Consider setting ``maxConnectionLifeTime`` and +``maxConnectionIdleTime``. These parameters configure how long the driver +maintains a connection to a MongoDB instance. For more information about these +parameters, see :ref:`Connection Pool Settings `. + +.. _kotlin-sync-server-selection-errors: + +Server Selection Timeout Exceptions +----------------------------------- + +Your application might not be able to complete a request even when some servers +are available, causing the driver to return a server selection timeout +exception. + +This exception is of type ``MongoTimeoutException``. The following +shows a sample of the exception that occurs if you attempt to send a +request to a replica set in which the primary is not reachable: + +.. code-block:: none + + com.mongodb.MongoTimeoutException: + Timed out while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. + Client view of cluster state is + {type=REPLICA_SET, + servers=[ + {address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}, + {address=localhost:27018, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}, + {address=localhost:27019, type=REPLICA_SET_SECONDARY, roundTripTime=15.0 ms, state=CONNECTED} + ] + } + +The error includes a view of the cluster state that describes the +connection state of each node, which can help you identify the source of +your connection issue. + +In the preceding error, the only connected server, ``localhost:27019``, +is a secondary node. Because of this, the request times out as the +driver is unable to select a server that satisfies the read preference +of ``primary``. In this situation, you can still perform read operations +against the connected secondary node if you set the read preference to +``secondary``, ``secondaryPreferred``, or ``nearest``. + +You can also specify the ``serverSelectionTimeoutMS`` connection option +to adjust the amount of time in which the driver must select a server. To +learn more, see the :ref:`kotlin-sync-connection-options` guide. + +.. _kotlin-sync-miscellaneous-errors: + +Miscellaneous Errors +-------------------- + +This section shows connection errors that do not fall into a broader category. + +Monitor Thread Exception +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + :copyable: false + + INFO: Exception in monitor thread while connecting to server ssc-cluster-01-shard-00-02.9cbnp.mongodb.net:27017 + +This log line indicates that the monitor that continuously +checks the status of each replica set member or ``mongos`` server failed to +contact one of the nodes or servers. This is an expected message during server +maintenance operations and can be safely ignored. + +Certificate Request Exception +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + :copyable: false + + javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request + +This is a known issue in certain versions of the JDK that can occur when +attempting to connect by using the TLS 1.3 protocol. + +If you encounter this error when connecting to your MongoDB instance or +cluster, update your JDK to one of the following patch versions or newer: + +- JDK 11.0.7 +- JDK 13.0.3 +- JDK 14.0.2 + +To learn more about this issue, see the +`issue description `__ +in the OpenJDK Bug system tracker issue. + +.. _kotlin-sync-debugging-tips: + +Debugging Tips +-------------- + +While not related to a specific error message, this section includes +information that can help in the process of troubleshooting connection +issues. + +Verbose Logging for TLS/SSL +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use the ``-Djavax.net.debug=all`` system property to enable +debug-level logging related to all connections, including those +established by using TLS/SSL. + +Enabling debug-level logging can help you diagnose the root problem of +connection issues. To learn more about the TLS/SSL logging messages, +see the `Debugging SSL/TLS Connections `__ +Java documentation. \ No newline at end of file