DOCS-461 review edits

Author: Bob Grabar

source/tutorial/configure-sharded-cluster-balancer.txt

@@ -7,14 +7,17 @@ Configure Behavior of Balancer Process in Sharded Clusters
 
 .. default-domain:: mongodb
 
-This section describes the settings you can configure on the balancer.
+The balancer runs on a single :program:`mongos` instance and distributes
+chunks evenly throughout a sharded cluster. In most deployments, you do
+not need to configure the balancer. The balancer automatically
+distributes chunks in an optimal manner. However, administrators might
+need to modify balancer behavior depending on application or operational
+requirements. Should a situation arise where modifying balancer behavior
+is necessary, this page describes settings that can be changed.
+
 For conceptual information about the balancer, see
 :ref:`sharding-balancing` and :ref:`sharding-balancing-internals`.
 
-You configure balancer settings through parameters in database commands
-or through fields in the :data:`~config.settings` collection in the
-:ref:`config database <config-database>`.
-
 .. index:: balancing; secondary throttle
 .. index:: secondary throttle
 .. _sharded-cluster-config-secondary-throttle:
@@ -25,146 +28,114 @@ Require Replication before Chunk Migration (Secondary Throttle)
 .. versionadded:: 2.2.1
 
 You can configure the balancer to wait for replication to secondaries
-before migrating chunks. You do so by enabling the balancer's
-``_secondaryThrottle`` parameter.
-
-Secondary throttle can speed performance in cases where you have
-migration-caused I/O peaks that do not cooperate with other workloads.
-
-.. above para is paraphrased from SERVER-7686
+during migrations. You do so by enabling the balancer's
+``_secondaryThrottle`` parameter, which reduces throughput (i.e.,
+"throttles") in order to decrease the load on secondaries. You might do
+this, for example, if you have migration-caused I/O peaks that impact
+other workloads
 
 When enabled, secondary throttle puts a ``{ w : 2 }`` write concern on
-deletes and on bulk clones, which means the balancer waits for those
+deletes and on copies, which means the balancer waits for those
 operations to replicate to at least one secondary before migrating
 chunks.
 
 .. BACKGROUND NOTES
    Specifically, secondary throttle affects the first and fourth
    phases (informal phases) of chunk migration. Migration can happen during
    the second and third phases (the "steady state"):
-   1) bulk clone data from shardA to shardB in the chunk range
-   2) continue to copy over ongoing changes that occurred during the initial clone step
+   1) copies the documents in the chunk from shardA to shardB
+   2) continues to copy over ongoing changes that occurred during the initial copy step,
       as well as current changes to that chunk range
    3) Stop writes, allow shardB to get final changes, commit migration to config server
    4) cleanup now-inactive data on shardA in chunk range (once all cursors are done)
 
-To enable secondary throttle, set ``_secondaryThrottle``
-to ``true`` by doing either of the following:
-
-- Issue the :dbcommand:`moveChunk` command with the
-  ``_secondaryThrottle`` parameter set to ``true``.
-
-- Enable the ``_secondaryThrottle`` setting directly in the
-  :data:`~config.settings` collection in the :ref:`config database
-  <config-database>`. To do so, run the following commands from the
-  :program:`mongo` shell:
-
-  .. code-block:: javascript
-
-     use config
-     db.settings.update( { "_id" : "balancer" } , { $set : { "_secondaryThrottle" : true } } )
-
-.. _sharded-cluster-config-no-auto-split:
-
-Prevent Auto-Splitting of Chunks
---------------------------------
-
-.. versionadded:: 2.0.7
-
-By default, :program:`mongos` instances automatically split chunks
-during inserts or updates if the chunks exceed the default chunk size.
-When chunk distribution becomes uneven, the balancer automatically
-migrates chunks among shards. Automatic chunk migrations are crucial for
-distributing data, but for deployments with large numbers of
-:program:`mongos` instances, the automatic migration might affect the
-performance of the cluster.
+You enable ``_secondaryThrottle`` directly in the
+:data:`settings <~config.settings>` collection in the :ref:`config database
+<config-database>` by running the following commands from the
+:program:`mongo` shell:
 
-You can turn off the auto-splitting of chunks by enabling
-:setting:`noAutoSplit` for individual :program:`mongos` instances.
-
-.. note:: Turning off auto-splitting can lead to an imbalanced
-          distribution of data in the sharded cluster.
-
-To turn off auto-splitting, do one of the following:
-
-- When staring a :program:`mongos`, include the :option:`--noAutoSplit
-  <mongos>` command-line option.
-
-- In the configuration file for a given :program:`mongos`, include the
-  :setting:`noAutoSplit` setting.
-
-Because any :program:`mongos` in a cluster can create a split, to
-totally disable splitting in a cluster you must set
-:setting:`noAutoSplit` on all :program:`mongos`.
+.. code-block:: javascript
 
-.. warning::
+   use config
+   db.settings.update( { "_id" : "balancer" } , { $set : { "_secondaryThrottle" : true } } )
 
-   With :setting:`noAutoSplit` enabled, the data in your sharded cluster
-   may become imbalanced over time. Enable with caution.
+You also can enable secondary throttle when issuing the
+:dbcommand:`moveChunk` command by setting ``_secondaryThrottle`` to
+``true``. For more information, see :dbcommand:`moveChunk`.
 
 .. _sharded-cluster-config-balancing-window:
 
 Schedule a Window of Time for Balancing to Occur
 ------------------------------------------------
 
 You can schedule a window of time during which the balancer is allowed
-to migrate chunks. See :ref:`sharding-schedule-balancing-window` and
-:ref:`sharding-balancing-remove-window`.
+to migrate chunks, as described in the following procedures:
+
+- :ref:`sharding-schedule-balancing-window`
+
+- :ref:`sharding-balancing-remove-window`.
+
+The configured time is evaluated relative to the time zone of each
+individual :program:`mongos` instance in the sharded cluster.
 
 .. _sharded-cluster-config-default-chunk-size:
 
-Change the Default Chunk Size
------------------------------
+Configure Default Chunk Size
+----------------------------
 
-The default chunk size for a sharded cluster affects how often chunks
-are split and migrated. For details, see :ref:`sharding-chunk-size`.
+The default chunk size for a sharded cluster is 64 megabytes. In most
+situations, the default size is optimal for splitting and migrating
+chunks. For information on how chunk size affects deployments, see
+details, see :ref:`sharding-chunk-size`.
 
-To modify the default chunk size for a sharded cluster, see
-:ref:`sharding-balancing-modify-chunk-size`.
+Changing the default chunk size affects chunks that are processes during
+migrations and auto-splits but does not retroactively affect all chunks.
+
+To configure default chunk size, see :ref:`sharding-balancing-modify-chunk-size`.
 
 .. _sharded-cluster-config-max-shard-size:
 
-Change the Maximum Size for a Given Shard
------------------------------------------
+Change the Maximum Storage Size for a Given Shard
+-------------------------------------------------
 
 The ``maxSize`` field in the :data:`~config.shards` collection in the
 :ref:`config database <config-database>` sets the maximum size for a
-shard, allowing you to control disk use and affect whether the balancer
-will migrate chunks to a shard. By default, ``maxSize`` is not
-specified, allowing shards to consume the total amount of available
-space on their machines if necessary. You can set ``maxSize`` both when
-adding a shard and once a shard is running.
+shard, allowing you to control whether the balancer will migrate chunks
+to a shard. If :data:`dataSize <~dbStats.dataSize>` is above a shard's
+``maxSize``, the balancer will not move chunks to the shard. The
+balancer also will not move chunks off the shard. The ``maxSize`` value
+only affects the balancer's selection of destination shards.
 
-.. seealso:: :ref:`sharding-shard-size`
+By default, ``maxSize`` is not specified, allowing shards to consume the
+total amount of available space on their machines if necessary.
 
-Set Maximum Size When Adding a Shard
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can set ``maxSize`` both when adding a shard and once a shard is
+running.
 
-When adding a shard using the :dbcommand:`addShard` command, set the
-``maxSize`` parameter to the maximum size in megabytes. For example, the
-following command run in the :program:`mongo` shell adds a shard with a
-maximum size of 125 megabytes:
+To set ``maxSize`` when adding a shard, set the :dbcommand:`addShard`
+command's ``maxSize`` parameter to the maximum size in megabytes. For
+example, the following command run in the :program:`mongo` shell adds a
+shard with a maximum size of 125 megabytes:
 
 .. code-block:: javascript
 
    db.runCommand( { addshard : "example.net:34008", maxSize : 125 } )
 
-Set Maximum Size on a Running Shard
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 To set ``maxSize`` on an existing shard, insert or update the
 ``maxSize`` field in the :data:`~config.shards` collection in the
 :ref:`config database <config-database>`. Set the ``maxSize`` in
 megabytes.
 
-.. example:: Assume you have the following shard without a ``maxSize`` field:
+.. example::
+
+   Assume you have the following shard without a ``maxSize`` field:
 
    .. code-block:: javascript
 
       { "_id" : "shard0000", "host" : "example.net:34001" }
 
    Run the following sequence of commands in the :program:`mongo` shell
-   to insert a ``maxSize`` of 125 megabytes::
+   to insert a ``maxSize`` of 125 megabytes:
 
    .. code-block:: javascript