From 655b4fb134543299207b8b03d3b53b4c387c7aa0 Mon Sep 17 00:00:00 2001
From: Jeff Allen <jeffrey.allen@10gen.com>
Date: Wed, 18 Aug 2021 11:57:08 -0400
Subject: [PATCH] (DOCS-14449): maxCatchUpPercentageBeforeBlockingWrites server
 parameter

---
 source/reference/command/moveChunk.txt        |  9 +++++
 source/reference/parameters.txt               | 34 +++++++++++++++++++
 source/release-notes/5.0.txt                  | 18 ++++++++++
 .../migrate-chunks-in-sharded-cluster.txt     |  2 ++
 4 files changed, 63 insertions(+)

diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt
index 6cceb331a2f..9bcadabb2b6 100644
--- a/source/reference/command/moveChunk.txt
+++ b/source/reference/command/moveChunk.txt
@@ -220,5 +220,14 @@ while :dbcommand:`moveChunk` is running, you may see this
 error. You may retry the :dbcommand:`moveChunk` operation without
 side effects.
 
+``maxCatchUpPercentageBeforeBlockingWrites`` Server Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 5.0 (and 4.4.7, 4.2.15 4.0.26), you can set the
+:parameter:`maxCatchUpPercentageBeforeBlockingWrites` to specify the
+maximum allowed percentage of data not yet migrated
+during a :dbcommand:`moveChunk` operation when compared to the
+total size (in MBs) of the chunk being transferred.
+
 
 .. admin-only
diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt
index 966c43c2983..954d91bdd5d 100644
--- a/source/reference/parameters.txt
+++ b/source/reference/parameters.txt
@@ -2735,6 +2735,40 @@ Sharding Parameters
       - :parameter:`readHedgingMode`
       - :ref:`mongos-hedged-reads`
 
+.. parameter:: maxCatchUpPercentageBeforeBlockingWrites
+
+   .. versionadded:: 5.0 (*Also available starting in 4.4.7, 4.2.15, 4.0.26*)
+
+   *Type*: integer
+
+   *Default*: 10
+
+   |mongod-only|
+
+   For :dbcommand:`moveChunk` operations, specifies the maximum
+   percentage of untrasferred data allowed by the migration protocol
+   (expressed in percentage of the total chunk size) to
+   transition from the ``catchup`` phase to the ``commit`` phase.
+   
+   Setting a higher catchup percentage can decrease the amount of time
+   it takes for the migration to complete at the cost of increased
+   latency during concurrent :method:`upsert <db.collection.updateOne>`
+   and :method:`delete <db.collection.deleteOne>` operations.
+
+   For example, to set the maximum percentage to 20, you can issue the
+   followingduring startup:
+
+   .. code-block:: bash
+
+      mongod --setParameter maxCatchUpPercentageBeforeBlockingWrites=20
+
+   You cannot change
+   :parameter:`maxCatchUpPercentageBeforeBlockingWrites` during runtime.
+
+   .. seealso::
+
+      `Live Migration Protocol <https://github.com/mongodb/mongo/blob/master/src/mongo/db/s/README.md#the-live-migration-protocol>`__
+
 .. parameter:: readHedgingMode
 
    .. versionadded:: 4.4
diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt
index f15463df2a0..1eb59f710cf 100644
--- a/source/release-notes/5.0.txt
+++ b/source/release-notes/5.0.txt
@@ -526,6 +526,24 @@ merged.
 The ``owningShard`` field helps identify shards where split or merge
 operations frequently occur.
 
+``maxCatchUpPercentageBeforeBlockingWrites`` Server Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 5.0 (and 4.4.7, 4.2.15 4.0.26), you can set the
+:parameter:`maxCatchUpPercentageBeforeBlockingWrites` to specify the
+maximum allowed percentage of data not yet migrated
+during a :dbcommand:`moveChunk` operation when compared to the
+total size (in MBs) of the chunk being transferred.
+
+This parameter can affect the behavior of:
+
+- :dbcommand:`moveChunk` commands that are run manually.
+
+- Load balancer functionality, which automatically runs multiple
+  :dbcommand:`moveChunk` commands to evenly distribute chunks across
+  shards. See :ref:`sharding-balancing`.
+
+
 .. _5.0-rel-notes-shell:
 
 Shell Changes
diff --git a/source/tutorial/migrate-chunks-in-sharded-cluster.txt b/source/tutorial/migrate-chunks-in-sharded-cluster.txt
index 81d0f4140e2..074daa31c56 100644
--- a/source/tutorial/migrate-chunks-in-sharded-cluster.txt
+++ b/source/tutorial/migrate-chunks-in-sharded-cluster.txt
@@ -1,3 +1,5 @@
+.. _migrate-chunks-sharded-cluster:
+
 ===================================
 Migrate Chunks in a Sharded Cluster
 ===================================