DOCS-8723: maxStalenessSeconds

source/core/read-preference-mechanics.txt

@@ -35,6 +35,8 @@ settings.
 
 The read preference is re-evaluated for each operation.
 
+.. include:: /includes/fact-3.4-added-maxStalenessSeconds.rst
+
 .. include:: /includes/extracts/server-selection-read-preference-replica-sets.rst
 
 .. index:: read preference; sharding
@@ -48,7 +50,7 @@ Read Preference for Sharded Clusters
 Load Balancing
 ~~~~~~~~~~~~~~
 
-If there is more than one :program:`mongos` instances in the connection
+If there is more than one :program:`mongos` instance in the connection
 seed list, the driver determines which :program:`mongos` is the
 "closest" (i.e. the member with the lowest average network
 round-trip-time) and calculates the latency window by adding the
@@ -65,7 +67,9 @@ applies the read preference when reading from the shards. Server
 selection is governed by the :doc:`read preference
 </core/read-preference>` and :setting:`replication.localPingThresholdMs` settings.
 
-.. versionchanged:: 3.0.0
+.. include:: /includes/fact-3.4-added-maxStalenessSeconds.rst
+
+.. versionchanged:: 3.0
 
    The read preference is re-evaluated for each operation.
 

source/core/read-preference.txt

@@ -135,6 +135,59 @@ For more information, see :ref:`read preference background
 behavior <replica-set-read-preference-behavior>`. See also the
 :api:`documentation for your driver <>`.
 
+.. _replica-set-read-preference-max-staleness:
+
+``maxStalenessSeconds``
+-----------------------
+
+.. versionadded:: 3.4
+
+Replica set members can lag behind the :term:`primary` due to network
+congestion, low disk throughput, long-running operations, etc. The read
+preference ``maxStalenessSeconds`` option lets you specify a maximum
+replication lag, or "staleness", for reads from :term:`secondaries
+<secondary>`. When a secondary's estimated staleness exceeds
+``maxStalenessSeconds``, the client stops using it for read operations.
+
+.. include:: /includes/fact-important-maxStalenessSeconds-intended-use.rst
+
+To use ``maxStalenessSeconds``, all of the
+MongoDB instances in your deployment must be using MongoDB 3.4 or
+later. If any instances are on an earlier version of MongoDB, the
+driver or :program:`mongos` will raise an error.
+
+You can specify ``maxStalenessSeconds`` with the following read
+preference modes:
+
+- :readmode:`primaryPreferred`
+- :readmode:`secondary`
+- :readmode:`secondaryPreferred`
+- :readmode:`nearest`
+
+Max staleness is not compatible with mode :readmode:`primary` and only
+applies when :ref:`selecting
+<replica-set-read-preference-behavior-member-selection>` a
+:term:`secondary` member of a set for a read operation.
+
+When selecting a server for a read operation with ``maxStalenessSeconds``, clients
+estimate how stale each secondary is by comparing the secondary's last
+write to that of the primary. The client will then direct the read
+operation to a secondary whose estimated lag is less than or equal to
+``maxStalenessSeconds``.
+
+If there is no primary, the client uses the secondary with the most
+recent write for the comparison.
+
+By default, there is no maximum staleness and clients will not consider a
+secondary's lag when choosing where to direct a read operation. 
+
+You must specify a ``maxStalenessSeconds`` value of 90 seconds or
+longer: specifying a smaller ``maxStalenessSeconds`` value will raise
+an error. Clients estimate secondaries' staleness by periodically
+checking the latest write date of each replica set member. Since these
+checks are infrequent, the staleness estimate is coarse. Thus, clients
+cannot enforce a ``maxStalenessSeconds`` value of less than 90 seconds.
+
 .. index:: tag sets
 .. index:: read preference; tag sets
 .. _replica-set-read-preference-tag-sets:

source/includes/apiargs-method-cursor.readPref-param.yaml

@@ -1,5 +1,5 @@
 arg_name: param
-description: |-
+description: |
   One of the following :term:`read preference` modes: :readmode:`primary`,
   :readmode:`primaryPreferred`, :readmode:`secondary`,
   :readmode:`secondaryPreferred`, or :readmode:`nearest`
@@ -10,14 +10,44 @@ optional: false
 position: 1
 type: string
 ---
+# TODO: Uncomment this when SERVER-27346 is resolved
+# (also add maxStalenessSeconds to the def in ref/meth/cursor.readPref)
+# # # # # # # # # # # # # # # # # # # # #
+# arg_name: param
+# pre: |
+#   .. versionadded:: 3.4
+#
+# description : |
+#   Specifies, in seconds, how stale a secondary can be before the client
+#   stops using it for read operations. For details, see:
+#   :ref:`replica-set-read-preference-max-staleness`.
+#
+#   By default, there is no maximum staleness and clients will not consider a
+#   secondary's lag when choosing where to direct a read operation.
+#
+#   The minimum {{arg_name}} value is 90 seconds. Specifying a
+#   value of less than 90 seconds will produce an error.
+#
+#   .. important::
+#      To use ``maxStalenessSeconds``, all of the
+#      MongoDB instances in your deployment must be using MongoDB 3.4 or
+#      later. If any instances are on an earlier version of MongoDB, the
+#      driver of :program:`mongos` will raise an error.
+# interface: method
+# name: maxStalenessSeconds
+# operation: cursor.readPref
+# optional: true
+# position: 2
+# type: non-negative integer
+---
 arg_name: param
-description: |-
+description: |
   A :term:`tag set` used to specify custom read preference modes. For details,
   see :ref:`replica-set-read-preference-tag-sets`.
 interface: method
 name: tagSet
 operation: cursor.readPref
 optional: true
-position: 2
+position: 3
 type: array
 ...

source/includes/extracts-read-preference-modes.yaml

@@ -0,0 +1,139 @@
+ref: _maxStalenessSeconds
+content: |
+  When the {{mode}} read preference includes a :ref:`maxStalenessSeconds value
+  <replica-set-read-preference-max-staleness>`{{noPrimary}},
+  the client estimates how stale each
+  secondary is by comparing the secondary's last write
+  to that of the {{compare}}. The client then directs the read operation to a
+  secondary whose estimated lag is less than or equal to ``maxStalenessSeconds``.
+  {{readFromSecondary}}
+---
+ref: maxStaleness-primaryPreferred
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _maxStalenessSeconds
+replacement:
+  mode: ":readmode:`primaryPreferred`"
+  noPrimary: " and there is no primary from which to read"
+  compare: "secondary with the most recent write"
+  readFromSecondary: ""
+---
+ref: maxStaleness-secondary
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _maxStalenessSeconds
+replacement:
+  mode: ":readmode:`secondary`"
+  noPrimary: ""
+  compare: "primary"
+  readFromSecondary: |
+    If there is no primary, the client uses the secondary with the most
+    recent write for the comparison.
+---
+ref: maxStaleness-secondaryPreferred
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _maxStalenessSeconds
+replacement:
+  mode: ":readmode:`secondaryPreferred`"
+  noPrimary: ""
+  compare: "primary"
+  readFromSecondary: |
+    If there is no primary, the client uses the secondary with the most
+    recent write for the comparison. If there are no secondaries with
+    estimated lag less than or equal to ``maxStalenessSeconds``, the
+    client directs the read operation to the replica set's primary.
+---
+ref: _tagSets
+content: |
+  When the read preference includes :ref:`tag sets
+  <replica-set-read-preference-tag-sets>`{{noPrimary}},
+  the client attempts to find secondary members that match the
+  specified tag sets and directs reads to a random secondary from among
+  the :ref:`nearest group
+  <replica-set-read-preference-behavior-nearest>` of matching
+  secondaries. If no secondaries have matching tags, {{behavior}}
+---
+ref: tagSets-primaryPreferred
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _tagSets
+replacement:
+  noPrimary: " and there is no primary from which to read"
+  behavior: "the read operation produces an error."
+---
+ref: tagSets-secondary
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _tagSets
+replacement:
+  noPrimary: ""
+  behavior: "the read operation produces an error. [#capacity-planning]_"
+---
+ref: tagSets-secondaryPreferred
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _tagSets
+replacement:
+  noPrimary: ""
+  behavior: "the client ignores tags and reads from the primary."
+---
+ref: _maxStaleness-and-tagSets
+content: |
+  When the read preference includes a ``maxStalenessSeconds`` value
+  **and** tag sets, the client filters by staleness first and
+  then by the specified tags.{{nearestBehavior}}
+---
+ref: maxStaleness-and-tagSets-general
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _maxStaleness-and-tagSets
+replacement:
+  nearestBehavior: ""
+---
+ref: maxStaleness-and-tagSets-nearest
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _maxStaleness-and-tagSets
+replacement:
+  nearestBehavior: |
+    From the remaining :program:`mongod` instances, the client then
+    randomly directs the read to an instance that falls within the
+    acceptable latency window. The read preference :ref:`member
+    selection <replica-set-read-preference-behavior-nearest>`
+    documentation describes the process in detail.
+---
+ref: _secondary-reads-stale-data
+content: |
+  Read operations using the {{mode}} mode may return stale data. Use the
+  ``maxStalenessSeconds`` option to avoid reading from secondaries
+  that the client estimates are overly stale.
+---
+ref: secondary-reads-stale-data-primaryPreferred
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _secondary-reads-stale-data
+replacement:
+  mode: ":readmode:`primaryPreferred`"
+---
+ref: secondary-reads-stale-data-secondary
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _secondary-reads-stale-data
+replacement:
+  mode: ":readmode:`secondary`"
+---
+ref: secondary-reads-stale-data-secondaryPreferred
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _secondary-reads-stale-data
+replacement:
+  mode: ":readmode:`secondaryPreferred`"
+---
+ref: secondary-reads-stale-data-nearest
+inherit:
+  file: extracts-read-preference-modes.yaml
+  ref: _secondary-reads-stale-data
+replacement:
+  mode: ":readmode:`nearest`"
+...

source/includes/extracts-server-selection-read-preference.yaml

@@ -14,14 +14,11 @@ content: |
       * - :readmode:`secondary`
 
         - #. The {{actor}} assembles a list of eligible secondary members.
-             :doc:`Tag sets </tutorial/configure-replica-set-tag-sets>`
-             and :doc:`read concern </reference/read-concern>` can further
+             :ref:`maxStalenessSeconds
+             <replica-set-read-preference-max-staleness>` and :doc:`tag
+             sets </tutorial/configure-replica-set-tag-sets>` can further
              restrict the eligibility of the members.
 
-             .. COMMENT To DocsTeam: 
-                In 3.4, will have maxStalenessMS which we'll need to  add here.
-                See https://jira.mongodb.org/browse/DOCS-8723.
-
           #. If the list of eligible members is not empty, the {{actor}}
              determines which eligible member is the "closest" (i.e. the
              member with the lowest average network round-trip-time) and
@@ -37,15 +34,12 @@ content: |
       * - :readmode:`nearest`
 
         - #. The {{actor}} assembles a list of eligible members (primary and
-             secondaries). :doc:`Tag sets
-             </tutorial/configure-replica-set-tag-sets>` and :doc:`read
-             concern</reference/read-concern>` can further limit the
+             secondaries). :ref:`maxStalenessSeconds
+             <replica-set-read-preference-max-staleness>` and :doc:`tag sets
+             </tutorial/configure-replica-set-tag-sets>`
+             can further limit the
              eligibility of the members.
 
-             .. COMMENT To DocsTeam: 
-                In 3.4, will have maxStalenessMS which we'll need to  add here.
-                See https://jira.mongodb.org/browse/DOCS-8723.
-
           #. If the list of eligible members is not empty, the {{actor}}
              determines which eligible member is the "closest" (i.e. the
              member with the lowest average network round-trip-time) and
@@ -68,7 +62,7 @@ content: |
 
       * - :readmode:`secondaryPreferred`
 
-        - #. Following the server selection process for the for the read
+        - #. Following the server selection process for the read
              preference ``secondary``, if a list of eligible secondary
              members is non-empty, {{actor}} chooses an eligible secondary member.
 

source/includes/fact-3.4-added-maxStalenessSeconds.rst

@@ -0,0 +1,7 @@
+.. versionadded:: 3.4
+   MongoDB 3.4 adds the ``maxStalenessSeconds`` read preference option
+   ``maxStalenessSeconds`` specifies the maximum replication lag, or
+   "staleness", that a :term:`secondary` can suffer and still be eligible
+   for read operations.
+
+.. include:: /includes/fact-important-maxStalenessSeconds-intended-use.rst

source/includes/fact-important-maxStalenessSeconds-intended-use.rst

@@ -0,0 +1,9 @@
+.. important:: 
+   The ``maxStalenessSeconds`` read preference option is intended for
+   applications that read from secondaries and want to avoid reading
+   from a secondary that has fallen overly far behind in replicating
+   the primary's writes. For example, a secondary might stop
+   replicating due to a network outage between itself and the primary.
+   In that case, the client should stop reading from the secondary
+   until an administrator resolves the outage and the secondary catches
+   up.

source/reference/connection-string.txt

@@ -364,6 +364,36 @@ on a per-connection basis in the connection string:
        The default value is :readmode:`primary`, which sends all read
        operations to the replica set's :term:`primary`.
 
+   * - .. urioption:: maxStalenessSeconds
+
+     - .. versionadded:: 3.4
+
+       Specifies, in seconds, how stale a secondary can be before the client
+       stops using it for read operations. For details, see:
+       :ref:`replica-set-read-preference-max-staleness`.
+
+       By default, there is no maximum staleness and clients will not consider a
+       secondary's lag when choosing where to direct a read operation.
+
+       The minimum :urioption:`maxStalenessSeconds` value is 90
+       seconds. Specifying a value between 0 and 90 seconds will produce
+       an error. MongoDB drivers treat a ``maxStalenessSeconds`` value
+       of ``-1`` as "no max staleness", the same as if
+       ``maxStalenessSeconds`` is omitted.
+
+       .. important::
+          To use ``maxStalenessSeconds``, all of the
+          MongoDB instances in your deployment must be using MongoDB 3.4 or
+          later. If any instances are on an earlier version of MongoDB, the
+          driver or :program:`mongos` will raise an error.
+
+       The following specifies a maxStalenessSeconds value of 120 seconds
+       with the :readmode:`secondary` read preference mode:
+
+       .. code-block:: none
+
+          mongodb://host.example.com/?readPreference=secondary&maxStalenessSeconds=120
+
    * - .. urioption:: readPreferenceTags
 
      - Specifies a tag set as a comma-separated list of colon-separated