From 264d47822df8a514987d441cfa8863c9183c724c Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 23 May 2025 13:40:02 -0400 Subject: [PATCH 1/4] DOCSP-47065: Load balancing --- source/connect/connection-options.txt | 2 ++ source/crud/read-write-pref.txt | 36 +++++++++++++++++++++++++-- 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 54868fec..24af6ccd 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -248,6 +248,8 @@ Authentication Options To learn about the authentication options available in the {+driver-short+}, see :ref:`Authentication Mechanisms. ` +.. _php-selection-discovery-options: + Server Selection and Discovery Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/crud/read-write-pref.txt b/source/crud/read-write-pref.txt index 8b54f2da..bc9c531c 100644 --- a/source/crud/read-write-pref.txt +++ b/source/crud/read-write-pref.txt @@ -208,7 +208,7 @@ This section shows how to further customize your read operation settings in the following ways: - :ref:`Apply a tag set ` -- :ref:`Specify a local threshold ` +- :ref:`Configure load balancing behavior ` .. _php-tag-sets: @@ -241,10 +241,42 @@ to prefer reads from secondary replica set members in the following order: :start-after: start-tag-set :end-before: end-tag-set +.. _php-load-balancing: + +Load Balancing +~~~~~~~~~~~~~~ + +When connecting to a sharded cluster or a replica set, the {+library-short+} uses +**load balancing** to handle read and write requests. Load balancing allows the library to +distribute these requests across multiple servers, which avoids overwhelming +any one server and ensures optimal performance. + +When connecting to a sharded cluster, the {+library-short+} determines the closest mongos +instance by calculating which one has the lowest network round-trip time. Then, the library +determines the latency window by adding this mongos's average round-trip time to the +:ref:`localThresholdMS value `. The library load balances requests +across up to two random mongos instances that fall within the latency window. For each request, +the library chooses the server with the lower operation load by determining its ``operationCount`` +value. + +When connecting to a replica set, the {+library-short+} first selects replica set members +according to your read preference. Then, the library follows the same process as +described in the preceding paragraph. After calculating the latency window, the library +selects up to two random replica set members that fall within the window and chooses +the member with the lower ``operationCount`` value to receive the request. + +.. tip:: + + To learn more about load balancing, see :manual:`Sharded Cluster Balancer + ` in the {+mdb-server+} manual. + + To learn how to customize the library's server selection behavior, see + :ref:`php-selection-discovery-options` in the Specify Connection Options guide. + .. _php-local-threshold: Local Threshold -~~~~~~~~~~~~~~~ +``````````````` If multiple replica-set members match the read preference and tag sets you specify, the {+php-library+} reads from the nearest replica-set members, chosen according to From 3fd210ea116069bda68a7ea344772ea87a3ebb01 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 23 May 2025 13:43:07 -0400 Subject: [PATCH 2/4] edit --- source/crud/read-write-pref.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/crud/read-write-pref.txt b/source/crud/read-write-pref.txt index bc9c531c..52485a4a 100644 --- a/source/crud/read-write-pref.txt +++ b/source/crud/read-write-pref.txt @@ -278,14 +278,14 @@ the member with the lower ``operationCount`` value to receive the request. Local Threshold ``````````````` -If multiple replica-set members match the read preference and tag sets you specify, -the {+php-library+} reads from the nearest replica-set members, chosen according to -their ping time. - -By default, the library uses only members whose ping times are within 15 milliseconds -of the nearest member for queries. To distribute reads between members with -higher latencies, pass an options array to the ``MongoDB\Client`` constructor that -sets the ``localThresholdMS`` option. +The {+library-short+} uses the local threshold value to calculate the +latency window for server selection. This value determines the servers +that are eligible to receive read and write requests. + +By default, the driver uses only mongos instances or replica set members whose +ping times are within 15 milliseconds of the nearest server. To +distribute reads among servers with higher latencies, pass an options array to +the ``MongoDB\Client`` constructor that sets the ``localThresholdMS`` option. The following example specifies a local threshold of 35 milliseconds: From 7e94d6ce9ce2d88fb6c14b9958b7a6386c1d4066 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 23 May 2025 13:43:49 -0400 Subject: [PATCH 3/4] word --- source/crud/read-write-pref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/read-write-pref.txt b/source/crud/read-write-pref.txt index 52485a4a..aaf17542 100644 --- a/source/crud/read-write-pref.txt +++ b/source/crud/read-write-pref.txt @@ -282,7 +282,7 @@ The {+library-short+} uses the local threshold value to calculate the latency window for server selection. This value determines the servers that are eligible to receive read and write requests. -By default, the driver uses only mongos instances or replica set members whose +By default, the library uses only mongos instances or replica set members whose ping times are within 15 milliseconds of the nearest server. To distribute reads among servers with higher latencies, pass an options array to the ``MongoDB\Client`` constructor that sets the ``localThresholdMS`` option. From f75bc75382576664a18b770985bb9a271f9e5391 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 29 May 2025 10:11:34 -0400 Subject: [PATCH 4/4] RR feedback --- source/crud/read-write-pref.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/crud/read-write-pref.txt b/source/crud/read-write-pref.txt index aaf17542..04aaa7ba 100644 --- a/source/crud/read-write-pref.txt +++ b/source/crud/read-write-pref.txt @@ -248,14 +248,14 @@ Load Balancing When connecting to a sharded cluster or a replica set, the {+library-short+} uses **load balancing** to handle read and write requests. Load balancing allows the library to -distribute these requests across multiple servers, which avoids overwhelming -any one server and ensures optimal performance. +distribute these requests across multiple servers to avoid overwhelming +any one server and ensure optimal performance. -When connecting to a sharded cluster, the {+library-short+} determines the closest mongos +When connecting to a sharded cluster, the {+library-short+} determines the closest ``mongos`` instance by calculating which one has the lowest network round-trip time. Then, the library -determines the latency window by adding this mongos's average round-trip time to the +determines the latency window by adding this ``mongos``'s average round-trip time to the :ref:`localThresholdMS value `. The library load balances requests -across up to two random mongos instances that fall within the latency window. For each request, +across up to two random ``mongos`` instances that fall within the latency window. For each request, the library chooses the server with the lower operation load by determining its ``operationCount`` value. @@ -267,11 +267,11 @@ the member with the lower ``operationCount`` value to receive the request. .. tip:: - To learn more about load balancing, see :manual:`Sharded Cluster Balancer - ` in the {+mdb-server+} manual. + To learn more about load balancing, see :manual:`Sharded Cluster Balancer + ` in the {+mdb-server+} manual. - To learn how to customize the library's server selection behavior, see - :ref:`php-selection-discovery-options` in the Specify Connection Options guide. + To learn how to customize the library's server selection behavior, see + :ref:`php-selection-discovery-options` in the Specify Connection Options guide. .. _php-local-threshold: @@ -282,7 +282,7 @@ The {+library-short+} uses the local threshold value to calculate the latency window for server selection. This value determines the servers that are eligible to receive read and write requests. -By default, the library uses only mongos instances or replica set members whose +By default, the library uses only ``mongos`` instances or replica set members whose ping times are within 15 milliseconds of the nearest server. To distribute reads among servers with higher latencies, pass an options array to the ``MongoDB\Client`` constructor that sets the ``localThresholdMS`` option.