(DOCS-15063): Change to balancerCollectionStatus output (#2085)

* (DOCS-15063): Update balancerCollectionStatus command page

* more updates

* edits

* small edits

* tweak

* wording

* add details per tech review

* formatting - note

Author: jeff-allen-mongo

source/includes/sharding/balancer-status-defrag-example.rst

@@ -0,0 +1,19 @@
+If the queried namespace is going through chunk defragmentation, the
+|balancer-command| returns output similar to the following:
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+      "balancerCompliant": false,
+      "firstComplianceViolation": "defragmentingChunks",
+      "details": {
+         "currentPhase": "moveAndMergeChunks",
+         "progress": { "remainingChunksToProcess": 1 }
+      }
+   }
+
+.. note::
+   
+   Chunk defragmentation occurs in multiple phases. The ``progress`` field
+   only pertains to the current phase. 

source/includes/sharding/balancer-status-defrag-release-notes.rst

@@ -0,0 +1,7 @@
+Starting in MongoDB 5.3, the :dbcommand:`balancerCollectionStatus`
+command returns detailed information when run on a namespace going
+through chunk defragmentation. The output includes the current phase of
+the defragmentation and how many chunks are left to process.
+
+To see example output, see
+:ref:`balancer-collection-status-defrag-output-command`.

source/reference/command/balancerCollectionStatus.txt

@@ -99,9 +99,9 @@ The following is an example of a document returned by the command:
 
    * - ``"firstComplianceViolation"``
 
-     - A string that indicates the reason  chunks for this namespace need to be
-       moved. The field is only available if ``"balancerCompliant"`` is
-       ``false``.
+     - A string that indicates the reason chunks for this namespace need
+       to be moved. The field is only available if
+       ``"balancerCompliant"`` is ``false``.
 
        Possible values are:
 
@@ -112,43 +112,55 @@ The following is an example of a document returned by the command:
           * - Value
             - Description
 
+          * - ``"chunksImbalance"``
+      
+            - The difference in the number of chunks between the shard
+              with the most chunks for the collection and the shard
+              with the fewest chunks for the collection exceed the
+              :ref:`migration threshold<sharding-migration-thresholds>`.
+
+          * - ``"defragmentingChunks"``
+
+            - The queried namespace is currently going through the chunk
+              defragmentation process. Defragmentation can be triggered
+              by the :dbcommand:`configureCollectionBalancing` command.
+          
           * - ``"draining"``
 
             - A :ref:`remove shard operation
               <remove-shard-remove-chunks>` is in progress and MongoDB
               must drain chunks off the removed shard to other shard(s).
 
-              .. note::
-
-                 If the ``"firstComplianceViolation"`` returns
-                 ``"draining"``, there may also be pending chunk
-                 migration due to ``"zoneViolation"``.
-
           * - ``"zoneViolation"``
 
             - Chunks violate the :ref:`defined zone ranges
               <zone-sharding-balancer>` for a shard.
 
-              .. note::
+       .. note::
 
-                 If the ``"firstComplianceViolation"`` responds with
-                 ``"zoneViolation"``, there may also be pending chunk
-                 migrations due to ``"chunksImbalance"``.
+          This field only returns information on the *first* violation
+          observed by MongoDB. There may be additional pending chunk
+          migrations due to a different reason than the one reported in
+          ``firstComplianceViolation``.
 
-          * - ``"chunksImbalance"``
-      
-            - The difference in the number of chunks between the shard
-              with the most chunks for the collection and the shard
-              with the fewest chunks for the collection exceed the
-              :ref:`migration threshold<sharding-migration-thresholds>`.
+   * - ``"details"``
+     
+     - An object containing information on the ongoing defragmentation
+       process. This object indicates the current phase of the
+       defragmentation and how many chunks are left to process in that
+       phase. For example output, see
+       :ref:`balancer-collection-status-defrag-output-command`.
+       
+       This field is only returned when ``firstComplianceViolation`` is
+       ``defragmentingChunks``. 
 
 In addition to the command-specific return fields, the command also
 returns the ``ok`` status field, the ``operationTime`` field, and the
 ``$clusterTime`` field for the operation. For details on these fields,
 see :ref:`command-response`.
 
-Example
--------
+Examples
+--------
 
 To check whether the chunks of a sharded collection ``test.contacts``
 is currently in balance, connect to a :binary:`~bin.mongos` instance
@@ -177,3 +189,11 @@ returns an output similar to the following:
       }
    }
 
+.. _balancer-collection-status-defrag-output-command:
+
+Ongoing Defragmentation Process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. |balancer-command| replace:: ``balancerCollectionStatus`` command
+
+.. include:: /includes/sharding/balancer-status-defrag-example.rst

source/reference/command/configureCollectionBalancing.txt

@@ -128,6 +128,8 @@ To tell the balancer to defragment a sharded collection, use the
    } )
 
 Use this command to have the balancer defragment a sharded collection.
+To monitor the chunk defragmentation process, use the
+:dbcommand:`balancerCollectionStatus` command.
 
 Reconfigure and Defragment Collections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -143,4 +145,3 @@ together:
       chunkSize: 512,
       defragmentCollection: true
    } )
-

source/reference/method/sh.balancerCollectionStatus.txt

@@ -75,8 +75,8 @@ The built-in :authrole:`clusterManager` role provides the appropriate
 privileges.
 
 
-Example
--------
+Examples
+--------
 
 To check whether the chunks of a sharded collection ``test.contacts``
 is currently in balance, connect to a :binary:`~bin.mongos` instance
@@ -105,5 +105,14 @@ returns an output similar to the following:
       }
    }
 
+.. _balancer-collection-status-defrag-output-method:
+
+Ongoing Defragmentation Process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. |balancer-command| replace:: ``sh.balancerCollectionStatus`` method
+
+.. include:: /includes/sharding/balancer-status-defrag-example.rst
+
 For the description of the output, see :ref:`balancerCollectionStatus
 Output <cmd-balancer-CollectionStatus-output>`.

source/release-notes/5.3.txt

@@ -128,12 +128,20 @@ for active keys.
 Sharding
 --------
 
+Limit Rate of Splits and Merges
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Starting in MongoDB 5.3, you can use the new
 :parameter:`chunkDefragmentationThrottlingMS` parameter to limit the
 rate of split and merge commands run by the :term:`balancer` when the
 :term:`chunks <chunk>` in a :term:`sharded <sharding>` collection are
 defragmented.
 
+Monitor Defragmentation Status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/sharding/balancer-status-defrag-release-notes.rst
+
 .. _5.3-rel-notes-general:
 
 General Improvements

source/release-notes/6.0.txt

@@ -371,6 +371,11 @@ earlier versions of MongoDB, the default chunk size is 64 megabytes.
 Starting in MongoDB 6.0, the :dbcommand:`enableSharding` command is
 no longer required to shard a collection.
 
+Monitor Defragmentation Status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/sharding/balancer-status-defrag-release-notes.rst
+
 .. _6.0-rel-notes-sbe:
 
 Slot-Based Query Execution Engine