DOCS-14892 distributed deadlock in transactions v5.3 (#678)

* DOCS-14892 Distributed deadlock in transactions

* DOCS-14892 Distributed deadlock in transactions

* Staging fixes

* Staging fixes

* Review feedback

* Staging fixes

* Review feedback

* Review feedback

Author: Dave

source/reference/parameters.txt

@@ -3085,6 +3085,57 @@ Sharding Parameters
 
       `Live Migration Protocol <https://github.com/mongodb/mongo/blob/master/src/mongo/db/s/README.md#the-live-migration-protocol>`__
 
+.. parameter:: metadataRefreshInTransactionMaxWaitBehindCritSecMS
+
+   .. versionadded:: 5.2 (*Also available starting in 5.1.0, 5.0.4*)
+
+   *Type*: integer
+
+   *Default*: 500
+
+   |mongod-only|
+
+   Limits the time a shard waits for a critical section within a
+   transaction. 
+
+   When a query accesses a shard, a :ref:`chunk migration
+   <migrate-chunks-sharded-cluster>` or :ref:`DDL operation
+   <transactions-operations-ddl>` may already hold the critical
+   section for the collection. If the query finds the critical
+   section is taken, the shard waits until the critical section has
+   been released. When the shard returns control to :binary:`mongos`,
+   :binary:`mongos` retries the query. However, if a multi-shard
+   transaction interacts with an operation that takes the critical
+   section on multiple shards, the interaction can result in a
+   distributed deadlock.
+
+
+   :parameter:`metadataRefreshInTransactionMaxWaitBehindCritSecMS`
+   limits the maximum time a shard waits within a transaction for the
+   critical section to be released.
+
+   To reduce the maximum wait time for the critical section within a
+   transaction, lower the the value of
+   :parameter:`metadataRefreshInTransactionMaxWaitBehindCritSecMS`. 
+
+   .. warning::
+
+      If :parameter:`metadataRefreshInTransactionMaxWaitBehindCritSecMS`
+      is too low, :binary:`mongos` could use all of its retry attempts
+      and return an error.
+
+   You can set 
+   :parameter:`metadataRefreshInTransactionMaxWaitBehindCritSecMS` at
+   startup and during runtime.
+
+   For example, to set :parameter:`metadataRefreshInTransactionMaxWaitBehindCritSecMS`
+   to 400 milliseconds:
+
+   .. code-block:: javascript
+
+      db.adminCommand( { setParameter: 1, metadataRefreshInTransactionMaxWaitBehindCritSecMS: 400 } )
+
+
 .. parameter:: readHedgingMode
 
    .. versionadded:: 4.4

source/release-notes/5.2.txt

@@ -204,6 +204,15 @@ Starting in MongoDB 5.2, the :dbcommand:`setAllowMigrations` command:
   <sharding-chunk-migration-manual>` from committing
 - Excludes the collection from new balancer rounds
 
+Limit Wait Time For Critical Section
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 5.2 (and 5.0.4, 5.1.0)
+
+The :parameter:`metadataRefreshInTransactionMaxWaitBehindCritSecMS`
+parameter limits the time a shard waits for a critical section within a
+transaction.
+
 .. _5.2-rel-notes-general:
 
 General Improvements