DOCS-14598: Address eMRC=true PSA cache pressure

Author: npentrel

source/administration/replica-set-maintenance.txt

@@ -57,6 +57,10 @@ replica sets.
   primary-secondary-arbiter (PSA) replica set or on a replica set that
   is changing to a PSA architecture.
 
+:doc:`/tutorial/mitigate-psa-performance-issues`
+  Prevent storage cache pressure from immobilizing a deployment that has
+  a three-member primary-secondary-arbiter (PSA) architecture.
+
 .. toctree::
    :titlesonly:
    :hidden:
@@ -72,3 +76,4 @@ replica sets.
    /tutorial/configure-replica-set-secondary-sync-target
    /tutorial/rename-unsharded-replica-set
    /tutorial/modify-psa-replica-set-safely
+   /tutorial/mitigate-psa-performance-issues

source/core/replica-set-arbiter.txt

@@ -48,6 +48,11 @@ number of votes to break a tie:
 
 .. end-content-even-votes-example
 
+Performance Issues with PSA replica sets
+----------------------------------------
+
+.. include:: /includes/fact-psa-performance-issues.rst
+
 Replica Set Protocol Version and Arbiter
 -----------------------------------------
 

source/includes/fact-psa-performance-issues.rst

@@ -0,0 +1,5 @@
+If you are using a three-member primary-secondary-arbiter (PSA)
+architecture, the read concern :readconcern:`"majority"` can cause
+performance issues if a secondary is unavailable or lagging. See
+:ref:`performance-issues-psa` for advice on how to mitigate these
+issues.

source/reference/configuration-options.txt

@@ -4145,6 +4145,10 @@ LDAP Parameters
    and is always set to ``true``. In earlier versions of MongoDB, 
    :setting:`~replication.enableMajorityReadConcern` was configurable.
 
+   .. warning::
+
+      .. include:: /includes/fact-psa-performance-issues.rst
+
 
 ``sharding`` Options
 ~~~~~~~~~~~~~~~~~~~~

source/reference/program/mongod.txt

@@ -1837,12 +1837,17 @@ Replication Options
    *Default*: true
 
    Configures support for :readconcern:`"majority"` read concern.
- 
-   Starting in MongoDB 5.0, 
-   :option:`--enableMajorityReadConcern` cannot be changed 
-   and is always set to ``true``. In earlier versions of MongoDB, 
+
+   Starting in MongoDB 5.0,
+   :option:`--enableMajorityReadConcern` cannot be changed
+   and is always set to ``true``. In earlier versions of MongoDB,
    :option:`--enableMajorityReadConcern` was configurable.
 
+   .. warning::
+
+      .. include:: /includes/fact-psa-performance-issues.rst
+
+
 Sharded Cluster Options
 ~~~~~~~~~~~~~~~~~~~~~~~
 

source/reference/read-concern-majority.txt

@@ -42,6 +42,10 @@ Availability
 Read concern :readconcern:`"majority"` is available for use with or
 without causally consistent sessions and transactions.
 
+.. warning::
+
+   .. include:: /includes/fact-psa-performance-issues.rst
+
 Example
 -------
 
@@ -130,48 +134,11 @@ Read Your Own Writes
 
 .. include:: /includes/fact-read-own-writes.rst
 
-.. _disable-read-concern-majority:                                      
-                                                                        
-Disable Read Concern Majority                                           
------------------------------                                           
-                                                                        
-*For 3-Member Primary-Secondary-Arbiter Architecture*                   
+.. _disable-read-concern-majority:
+
+Primary-Secondary-Arbiter Replica Sets
+--------------------------------------
 
 .. include:: /includes/fact-eMRC-always-true-in-5.0.rst
 
-You can disable read concern :readconcern:`"majority"` if you have a       
-three-member replica set with a primary-secondary-arbiter (PSA)            
-architecture or a sharded cluster with a three-member PSA shards.          
-
-.. note::                                                                  
-
-   If you are using a deployment other than a 3-member PSA, you do not  
-   need to disable read concern majority.                                  
-
-With a three-member PSA architecture, the cache pressure will increase  
-if any data bearing node is down. To prevent the storage cache pressure 
-from immobilizing a deployment with a PSA architecture, you can disable 
-read concern by setting either:                                            
-
-- :option:`--enableMajorityReadConcern <mongod                             
-  --enableMajorityReadConcern>` command line option to ``false``.          
-
-- :setting:`replication.enableMajorityReadConcern` configuration file   
-  setting to ``false``.                                                    
-
-To check if read concern "majority" is disabled, You can run               
-:method:`db.serverStatus()` on the :binary:`~bin.mongod` instances and  
-check the :serverstatus:`storageEngine.supportsCommittedReads` field.   
-If ``false``, read concern "majority" is disabled.                         
-                                                                        
-.. important::                                                          
-                                                                        
-   In general, avoid disabling :readconcern:`"majority"` read concern   
-   unless necessary. However, if you have a three-member replica set    
-   with a primary-secondary-arbiter (PSA) architecture or a sharded     
-   cluster with a three-member PSA shard, disable to prevent the        
-   storage cache pressure from immobilizing the deployment.             
-                                                                        
-.. note:: Change Streams                                                
-                                                                        
-   .. include:: /includes/extracts/changestream-disable-rc-majority.rst
+.. include:: /includes/fact-psa-performance-issues.rst

source/release-notes/5.0-compatibility.txt

@@ -136,14 +136,13 @@ replacement shell is :mongosh:`mongosh </>`.
 Shell packaging also changes in MongoDB v5.0. Refer to the 
 :mongosh:`installation instructions </install>` for further details.
 
-Replica Sets
-------------
-
 ``enableMajorityReadConcern`` Is Not Configurable
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: /includes/fact-eMRC-always-true-in-5.0.rst
 
+.. include:: /includes/fact-psa-performance-issues.rst
+
 ``secondaryDelaySecs`` Configuration Setting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/release-notes/5.0.txt

@@ -225,6 +225,8 @@ limited to an integer between ``0`` and ``255`` inclusive.
 
 .. include:: /includes/fact-eMRC-always-true-in-5.0.rst
 
+.. include:: /includes/fact-psa-performance-issues.rst
+
 Enhanced Thread Pool Timeout Control
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/tutorial/add-replica-set-arbiter.txt

@@ -34,6 +34,11 @@ server or a monitoring host.
 Considerations
 --------------
 
+Primary-Secondary-Arbiter Replica Sets
+--------------------------------------
+
+.. include:: /includes/fact-psa-performance-issues.rst
+
 Replica Set Protocol Version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/tutorial/mitigate-psa-performance-issues.txt

@@ -0,0 +1,78 @@
+.. _performance-issues-psa:
+
+================================================
+Mitigate Performance Issues with PSA Replica Set
+================================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+In a three-member replica set with a primary-secondary-arbiter (PSA)
+architecture or a sharded cluster with three-member PSA shards, a
+data-bearing node that is down or lagged can lead to performance issues.
+
+If one data-bearing node goes down, the other node becomes the primary.
+Writes with :writeconcern:`w:1 <\<number\>>` continue to succeed in this
+state but writes with write concern :writeconcern:`"majority"` cannot
+succeed and the commit point starts to lag. If your PSA replica set
+contains a lagged secondary and your replica set requires two nodes to
+majority commit a change, your commit point also lags.
+
+With a lagged commit point, two things can affect your cluster
+performance:
+
+- The storage engine keeps **all** changes that happen after the commit
+  point on disk to retain a :term:`durable` history. The extra I/O from
+  these writes tends to increase over time. This can greatly impact
+  write performance and increase cache pressure.
+- MongoDB allows the :ref:`oplog <replica-set-oplog>` to grow past its
+  configured size limit to avoid deleting the :data:`majority commit
+  point <replSetGetStatus.optimes.lastCommittedOpTime>`.
+
+To reduce the cache pressure and increased write traffic, set
+:rsconf:`votes: 0 <members[n].votes>` and :rsconf:`priority: 0
+<members[n].priority>` for the node that is unavailable or lagging. For
+write operations issued with "majority", only voting members are
+considered to determine the number of nodes needed to perform a majority
+commit. Setting the configuration of the node to :rsconf:`votes: 0
+<members[n].votes>` reduces the number of nodes required to commit a
+write with write concern :writeconcern:`"majority"` from two to one and
+allows these writes to succeed.
+
+If you want to later change :rsconf:`votes <members[n].votes>` back to a
+non-zero number, use the :method:`rs.reconfigForPSASet()` method.
+
+.. note::
+
+   In earlier versions of MongoDB,
+   :setting:`~replication.enableMajorityReadConcern` and
+   :option:`--enableMajorityReadConcern` were configurable allowing you
+   to disable the default read concern :readconcern:`"majority"` which
+   had a similar effect.
+
+Procedure
+---------
+
+To reduce the cache pressure and increased write traffic for a
+deployment with a three-member primary-secondary-arbiter (PSA)
+architecture, set ``{ votes: 0, priority: 0 }`` for the secondary that
+is unavailable or lagging:
+
+.. code-block:: javascript
+
+   cfg = rs.conf();
+   cfg["members"][<array_index>]["votes"] = 0;
+   cfg["members"][<array_index>]["priority"] = 0;
+   rs.reconfig(cfg);
+
+
+If you want to change the configuration of the secondary later, use the
+:method:`rs.reconfigForPSASet()` method.