DOCS-15168-set-retry-parameters-v6.1 (#1681)

* Review feedback

* DOCS-15168 set retry parameters

* Sync update from another PR

Author: Dave Cuthbert

source/includes/reference/fact-parameters-cache-pressure.rst

@@ -0,0 +1,13 @@
+In rare circumstances, a write can fail due to cache pressure. When
+this happens MongoDB issues a ``TemporarilyUnavailable`` error and
+increments the ``temporarilyUnavailableErrors`` counter in two places:
+the slow query log and the :ref:`Full Time Diagnostic Data Collection
+(FTDC) <ftdc-stub>`.
+
+Individual operations within multi-document transactions never return
+``TemporarilyUnavailable`` errors.
+
+Adjust the write retry properties by modifying the
+:parameter:`temporarilyUnavailableBackoffBaseMs` and
+:parameter:`temporarilyUnavailableMaxRetries` parameters.
+

source/reference/parameters.txt

@@ -2601,11 +2601,11 @@ If you attempt to update ``disableSplitHorizonIPCheck`` at runtime,
    parallel. Values can range from 1 to 256 inclusive. However, the
    maximum number of threads used is capped at twice the number of
    available cores.
-   
+
    You can only set :parameter:`replWriterThreadCount` at startup and
    cannot change this setting with the :dbcommand:`setParameter`
    command.
-
+   
    .. seealso::
 
       :parameter:`replWriterMinThreadCount`
@@ -4376,6 +4376,76 @@ Storage Parameters
       - :parameter:`journalCommitInterval`
       - :setting:`storage.syncPeriodSecs`
 
+.. parameter:: temporarilyUnavailableBackoffBaseMs
+
+   |mongod-only|
+
+   Specifies the initial delay before retying a write operation that was
+   rolled back due to cache pressure.
+
+   .. include:: /includes/reference/fact-parameters-cache-pressure.rst
+
+   The parameter accepts:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 80
+
+      * - Value
+        - Description
+
+      * - ``integer >= 0``
+
+        - Defaults to 1 second. The initial delay between retries. The
+          value increases with each retry to a maximum of 55 seconds. A
+          larger value increases the chance that the cache pressure
+          will be reduced before the next retry.
+          
+          To configure number of retires, use 
+          :parameter:`temporarilyUnavailableMaxRetries`.
+
+   To set a new value, use :method:`db.adminCommand()`:
+
+   .. code-block:: javascript
+
+      db.adminCommand( { setParameter: 1, temporarilyUnavailableBackoffBaseMs: 3 } )
+
+   *Available starting in MongoDB 6.1.0*
+
+.. parameter:: temporarilyUnavailableMaxRetries
+
+   |mongod-only|
+
+   Specifies the maximum number of retries when a write operation is
+   rolled back due to cache pressure.
+
+   .. include:: /includes/reference/fact-parameters-cache-pressure.rst
+
+   The parameter accepts:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 80
+
+      * - Value
+        - Description
+
+      * - ``integer >= 0``
+
+        - Defaults to 10. The maximum number of retries.
+          
+          There is an increasing delay between retries. To configure
+          the backoff time, use 
+          :parameter:`temporarilyUnavailableBackoffBaseMs`.
+
+   To set a new value, use :method:`db.adminCommand()`:
+
+   .. code-block:: javascript
+
+      db.adminCommand( { setParameter: 1, temporarilyUnavailableMaxRetries: 5 } )
+
+   *Available starting in MongoDB 6.1.0*
+
 WiredTiger Parameters
 ~~~~~~~~~~~~~~~~~~~~~
 

source/release-notes/6.1.txt

@@ -99,6 +99,21 @@ Starting in MongoDB 6.1, the :dbcommand:`serverStatus` command and the
 
        - :serverstatus:`connections.rejected`
 
+Storage Engine
+~~~~~~~~~~~~~~
+
+.. include:: /includes/reference/fact-parameters-cache-pressure.rst
+
+Server Parameters
+-----------------
+
+Starting in MongoDB 6.1, MongoDB adds the following new parameters:
+
+- :parameter:`temporarilyUnavailableBackoffBaseMs` adjusts the time
+  between retries after a write failure. 
+- :parameter:`temporarilyUnavailableMaxRetries` limits the number of
+  retries after a write failure.
+
 Report an Issue
 ---------------