(DOCSP-45558)-Mention-altering-load-level-during-a-migration-in-mongosync’s-documentation-v1.9-backport (530) (#546)

elyse-mdb · web-flow · commit e345e2692180 · 2025-01-14T10:05:49.000-08:00
* (DOCSP-45558) [C2C] Mention altering load level during a migration in mongosync’s documentation. (#530) * (DOCSP-45558) Add section to FAQ page. * (DOCSP-45558) Edits. * (DOCSP-45558) Edits. * (DOCSP-45558) Procedure. * (DOCSP-45558) Edit formatting. * (DOCSP-45558) Edits. * (DOCSP-45558) edits. * (DOCSP-45558) Edits. * (DOCSP-45558) Add pause step to FAQ and edit FAQ link. * (DOCSP-45558) Add update section to configuration page. * (DOCSP-45558) Standardize link to update documentation. * (DOCSP-45558) Edit. * (DOCSP-45558) Edits. * (DOCSP-45558) Normalize links. * (DOCSP-45558) Edit introduction to Optionsgst q * (DOCSP-45558) Edit Settings introduction. * (DOCSP-45558) Updates. * (DOCSP-45558) Make consistent intros to command line opts vs config file settings. * (DOCSP-45558) Edit wording. * (DOCSP-45558) Shorten sentence. * (DOCSP-45558) updates. * (DOCSP-45558) Edits. * (DOCSP-45558) Edit. * (DOCSP-45558) Edit important admonition. * (DOCSP-45558) @jwilson-mdb Review changes. * (DOCSP-45558) Add command line options to configuration intro. * (DOCSP-45558) Fix subtitle underline. * (DOCSP-45558) Fix subtitle underline. * (DOCSP-45558) @FGasper Review changes. (cherry picked from commit ccd72ea) * (DOCSP-45558) Fix typo.
diff --git a/source/faq.txt b/source/faq.txt
@@ -17,7 +17,11 @@ This page provides answers to some frequently asked questions we have
 encountered. If you have additional questions please contact MongoDB
 Support.
 
-.. _c2c-faq-read-write-during-sync:
+Can I change the load level while ``mongosync`` is syncing? 
+-----------------------------------------------------------
+
+Yes, you can adjust the cluster workload level during a migration by 
+following the steps in :ref:`c2c-reconfigure-mid-migration`. 
 
 Can I perform reads or writes to my destination cluster while ``mongosync`` is syncing?
 ---------------------------------------------------------------------------------------
diff --git a/source/reference/configuration.txt b/source/reference/configuration.txt
@@ -13,11 +13,17 @@ Configuration
    :class: singlecol
 
 You can configure :ref:`mongosync <c2c-mongosync>` instances at startup 
-using a configuration file.  The configuration file contains settings that are
+by using :ref:`command line options <c2c-cli-options>` or a configuration file.
+The configuration file specifies values for settings that are
 the equivalent of ``mongosync`` command line options.
 
+During a migration, you can reconfigure certain ``mongosync`` settings by following the 
+steps in  :ref:`c2c-reconfigure-mid-migration`. 
+
+.. _c2c-configuration-file: 
+
 Configuration File
-==================
+------------------
 
 You can write most ``mongosync`` 
 :ref:`command line options <c2c-cli-options>` to a YAML file. The 
@@ -37,10 +43,14 @@ To use a configuration file, start ``mongosync`` with the
 
 .. code-block:: console
 
-   $ mongosync --config mongosync.conf
+   mongosync --config <configPath>
+
+Settings
+~~~~~~~~
+
+You can configure the following ``mongosync`` settings using a configuration file. 
 
-Options
-=======
+To configure ``mongosync`` from the command line, see :ref:`c2c-cli-options`. 
 
 .. note::
 
@@ -144,3 +154,78 @@ Options
 
    To set the ``verbosity`` setting from the command line, see the
    :option:`--verbosity` option.
+
+.. _c2c-reconfigure-mid-migration: 
+
+Reconfigure ``mongosync`` During Synchronization
+------------------------------------------------
+
+.. important:: 
+
+   Only the following settings can be adjusted during a migration. 
+   Other settings **must** remain unchanged between ``mongosync`` restarts.
+
+While ``mongosync`` is syncing, you can reconfigure the :option:`--config`, :option:`--disableTelemetry`,
+:option:`--loadLevel`, :option:`--logPath`, :option:`--port`, and :option:`--verbosity` options 
+by performing the following steps: 
+
+.. procedure::
+   :style: normal
+
+   .. step:: (Optional) Pause the ``mongosync`` processes
+   
+      Run :ref:`c2c-api-pause` on each running ``mongosync`` process.
+      
+      You can resume the ``mongosync`` processes later from the paused
+      state, as shown in the final step.
+      
+      .. tip::
+
+         If you don't want to immediately resume data synchronization
+         operations after reconfiguration, consider pausing the
+         ``mongosync`` processes. This is useful if you're coordinating
+         operations from multiple ``mongosync`` processes.
+      
+   .. step:: Stop the ``mongosync`` processes 
+
+      Use your operating system to stop each running ``mongosync`` process. 
+      For the specific steps, see your operating system documentation.
+   
+   .. step:: (Optional) Update your configuration file
+
+      If you used the :option:`--config` option to set the path to a configuration file 
+      when you first initialized ``mongosync``, update this configuration file with the new value for each setting.
+
+   .. step:: Initialize the ``mongosync`` processes
+
+      If you updated a configuration file in the last step, initialize 
+      the ``mongosync`` processes with the :option:`--config` option 
+      set to the path of the updated configuration file:
+      
+      .. code-block:: console
+
+         mongosync --config <configPath>
+
+      If you did  *not*  use the :option:`--config` option when you first initialized ``mongosync``, 
+      initialize the ``mongosync`` processes with the command line options set to their updated values:
+
+      .. code-block:: console
+
+         mongosync \
+               --cluster0 "<cluster0_connection_string>" \
+               --cluster1 "<cluster1_connection_string>" \
+               --loadLevel <newLevel> 
+
+      For more information, see :ref:`Initialize mongosync <c2c-initialize>`.
+
+   .. step:: Start or Resume the ``mongosync`` processes 
+
+      If you paused any ``mongosync`` processes earlier in the optional first step, 
+      run :ref:`c2c-api-resume` on the paused ``mongosync`` processes.
+
+      If you stopped any ``mongosync`` processes without using :ref:`c2c-api-pause`, 
+      run :ref:`c2c-api-start` on the stopped ``mongosync`` processes. 
+      For more detailed instructions, see :ref:`c2c-quickstart-synchronize`. 
+
+      ``mongosync`` resumes the sync roughly where it was before you stopped the earlier proceses.
+      Any partitions that were in progress at the time of termination will restart from the beginning. 
diff --git a/source/reference/mongosync.txt b/source/reference/mongosync.txt
@@ -71,6 +71,10 @@ For more information on how to format your connection strings, see
 Command Line Options
 --------------------
 
+You can configure the following ``mongosync`` options using the command line.
+
+To configure ``mongosync`` from a configuration file, see :ref:`c2c-configuration-file`.
+
 .. |opt-term| replace:: option
 
 Global Options
@@ -107,6 +111,9 @@ Global Options
 
    Sets the path to the configuration file.
 
+   To set the configuration file path during a migration, 
+   see :ref:`c2c-reconfigure-mid-migration`. 
+
    For more information, see :ref:`c2c-mongosync-config`.
 
 .. option:: --disableTelemetry
@@ -116,8 +123,11 @@ Global Options
    .. include:: /includes/opts/disableTelemetry
 
    To set the ``--disableTelemetry`` option from a configuration file,
-   see the :setting:`disableTelemetry` setting.
+   see the :setting:`disableTelemetry` setting. 
 
+   To disable telemetry data collection during a migration, 
+   see :ref:`c2c-reconfigure-mid-migration`.
+   
    For more information, see :ref:`User Data Collection
    <c2c-telemetry>`.
 
@@ -138,9 +148,12 @@ Global Options
 
    .. include:: /includes/opts/loadLevel.rst
 
-   To set the ``--loadLevel`` option from a configuration file, see the
-   :setting:`loadLevel` setting.
+   To set the ``--loadLevel`` option from a configuration file,
+   see the :setting:`loadLevel` setting.
 
+   To change the load level during a migration, 
+   see :ref:`c2c-reconfigure-mid-migration`. 
+   
    .. include:: /includes/opts/loadlevel-warning.rst
 
    .. versionadded:: 1.4
@@ -152,6 +165,9 @@ Global Options
    To set the ``--logPath`` option from a configuration file,
    see the :setting:`logPath` setting.
 
+   To change the path to the log directory during a migration, 
+   see :ref:`c2c-reconfigure-mid-migration`. 
+   
    .. note:: 
 
       .. include:: /includes/fact-log-rotation-usr1-signal
@@ -163,6 +179,9 @@ Global Options
    To set the ``--port`` option from a configuration file,
    see the :setting:`port` setting.
 
+   To change the port during a migration, 
+   see :ref:`c2c-reconfigure-mid-migration`. 
+
 .. option:: --verbosity <level>
 
    .. |verbosity-opt-type| replace:: option
@@ -172,7 +191,10 @@ Global Options
 
    To set the ``--verbosity`` option from a configuration file,
    see the :setting:`verbosity` setting.
-   
+
+   To change the verbosity level during a migration, 
+   see :ref:`c2c-reconfigure-mid-migration`. 
+
 .. option:: --version, -v
 
    Prints ``mongosync`` version information to stdout.
