DOCS-11925: electionTimeoutMillis parameter

Author: kay-kim

source/includes/extracts-rs-stepdown.yaml

@@ -0,0 +1,15 @@
+ref: rs-stepdown-election-handoff
+content: |
+
+   .. versionchanged:: 4.0.2
+
+      If the parameter :parameter:`enableElectionHandoff` is true
+      (default), when a primary steps down from :method:`rs.stepDown()`
+      (or the :dbcommand:`replSetStepDown` command without the ``force:
+      true``), the stepped-down primary nominates an eligible secondary
+      to call an election immediately. Otherwise, secondaries can wait
+      up to :rsconf:`settings.electionTimeoutMillis` before calling an
+      election. The stepped down primary does not wait for the effects
+      of the handoff. For more information, see
+      :parameter:`enableElectionHandoff`.
+...

source/includes/fact-stepdown-write-fail.rst

@@ -2,7 +2,7 @@
 
    All writes to the primary fail during the period starting when the
    |command-method-name| |command-method| is received until either a new
-   primary is elected, or if there are no electible secondaries, the
+   primary is elected, or if there are no electable secondaries, the
    original primary resumes normal operation. The time period where
    writes fail is at maximum:
 

source/includes/stepdown-behavior.rst

@@ -1,10 +1,16 @@
 .. versionadded:: 3.0
 
+Concurrent Operations
+~~~~~~~~~~~~~~~~~~~~~
+
 The |command-method-name| |command-method| attempts to
 terminate long running user operations that block the primary
 from stepping down, such as an index build, a write operation or a
 map-reduce job.
 
+Availability of Eligible Secondaries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The |command-method| then initiates a catchup period where it waits up to
 ``secondaryCatchUpPeriodSeconds``, by default 10 seconds, for a
 secondary to become up-to-date with the primary. The primary only steps
@@ -17,8 +23,12 @@ period, the primary does not step down and the |command-method| errors.
 
 Once the primary steps down successfully, that node cannot become the
 primary for the remainder of the |stepdown-secs| period,
-which began when the node received the |command-method|. The
-|command-method-name| |command-method| forces all clients currently
+which began when the node received the |command-method|. 
+
+Client Connections
+~~~~~~~~~~~~~~~~~~
+
+The |command-method-name| |command-method| forces all clients currently
 connected to the database to disconnect. This helps ensure that the
 clients maintain an accurate view of the replica set.
 

source/reference/command/replSetStepDown.txt

@@ -47,8 +47,16 @@ Behavior
 
 .. include:: /includes/stepdown-behavior.rst
 
+Writes During Stepdown
+~~~~~~~~~~~~~~~~~~~~~~
+
 .. include:: /includes/fact-stepdown-write-fail.rst
 
+Election Handoff
+~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/rs-stepdown-election-handoff.rst
+
 Examples
 --------
 

source/reference/method/rs.stepDown.txt

@@ -39,4 +39,13 @@ Behavior
 
 .. include:: /includes/stepdown-behavior.rst
 
+Writes During Stepdown
+~~~~~~~~~~~~~~~~~~~~~~
+
 .. include:: /includes/fact-stepdown-write-fail.rst
+
+Election Handoff
+~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/rs-stepdown-election-handoff.rst
+

source/reference/parameters.txt

@@ -1404,6 +1404,37 @@ Replication Parameters
 
    For more information, see :ref:`rollback-data-files`.
 
+.. parameter:: enableElectionHandoff
+
+   .. versionadded:: 4.0.2
+
+   *Type*: boolean
+
+   *Default*: true
+
+   A flag that can reduce the downtime after the primary steps down
+   from either the :method:`rs.stepDown()` method or the
+   :dbcommand:`replSetStepDown` command. Specifically, if true, when a
+   primary steps down after :method:`rs.stepDown()` (or the
+   :dbcommand:`replSetStepDown` command without the ``force: true``),
+   it nominates an eligible secondary to call an election immediately.
+   If false, after the step down, secondaries can wait up to
+   :rsconf:`settings.electionTimeoutMillis` before calling an election.
+
+   An eligible secondary must be caught up with the stepped down
+   primary and have :rsconf:`~members[n].priority` greater than 0. If
+   multiple secondary members meet this criteria, the stepped down
+   primary selects the eligible secondary with the highest
+   :rsconf:`~members[n].priority`. If the more than one eligible
+   secondary members have the same :rsconf:`~members[n].priority`, the
+   stepped down primary selects the secondary with the lowest
+   :rsconf:`~members[n]._id`. The stepped down primary does not wait
+   for the effects of the handoff.
+
+   The parameter has no impact if the primary steps down for reasons
+   other than :method:`rs.stepDown()` (or the
+   :dbcommand:`replSetStepDown` command without the ``force: true``).
+
 Sharding Parameters
 ~~~~~~~~~~~~~~~~~~~
 

source/reference/replica-configuration.txt

@@ -477,7 +477,11 @@ Replica Set Configuration Fields
         sensitivity to primary node or network slowness or spottiness.
 
       The setting only applies when using :rsconf:`protocolVersion: 1`.
-      
+
+      .. note::
+
+         .. include:: /includes/extracts/rs-stepdown-election-handoff.rst
+
    .. rsconf::  settings.catchUpTimeoutMillis
 
       .. versionadded:: 3.4

source/tutorial/force-member-to-be-primary.txt

@@ -37,6 +37,10 @@ available for a set to reconfigure a set or elect a primary. See
 Procedures
 ----------
 
+.. note::
+
+   .. include:: /includes/extracts/rs-stepdown-election-handoff.rst
+
 .. _replica-set-force-member-to-be-primary-via-priority-setting:
 
 Force a Member to be Primary by Setting its Priority High