(DOCSP-45558)-Mention-altering-load-level-during-a-migration-in-mongosync’s-documentation #530

elyse-mdb · 2024-12-16T21:24:59Z

DESCRIPTION

Per this Slack thread, mongosync’s docs should specifically address mid-migration load level adjustments.

Suggested text:

You can adjust mongosync’s load level during a migration. To do this, terminate all mongosync processes, then restart them with the needed load level. Mongosync will resume roughly where it was before you ended the earlier processes.

This same procedure can be used to update any configuration setting other than --cluster0, --cluster1, and --id. To document this, I added a new section to the Configuration reference page with directions on how to update configuration settings during an active sync.
Linked to the above section on each adjustable configuration setting on the mongosync reference page.
Added an FAQ entry that links users to the above section.

STAGING

Configuration
mongosync
FAQ

JIRA

DOCSP-45558

SELF-REVIEW CHECKLIST

Does each file have 3-5 taxonomy facet tags?
See the taxonomy tagging instructions and this example PR
Is this free of any warnings or errors in the RST?
Is this free of spelling errors?
Is this free of grammatical errors?
Is this free of staging / rendering issues?
Are all the links working?

EXTERNAL REVIEW REQUIREMENTS

What's expected of an external reviewer?

netlify · 2024-12-16T21:25:17Z

✅ Deploy Preview for docs-cluster-to-cluster-sync ready!

Name	Link
🔨 Latest commit	`7f8ea57`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-cluster-to-cluster-sync/deploys/67816e01c3ef1f0008529537
😎 Deploy Preview	https://deploy-preview-530--docs-cluster-to-cluster-sync.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

q

…ile settings.

jwilson-mdb

I think this came out great!! The configuration page looks to be a good home for reconfiguring, and the crosslinking seems pretty intuitive to me. Nice job.

I left a couple of small suggestions for you to review/update before requesting an ext review, but overall LGTM!

jwilson-mdb · 2025-01-07T22:44:02Z

source/reference/configuration.txt

 using a configuration file.  The configuration file contains settings that are
 the equivalent of ``mongosync`` command line options.

+During a migration, you can reconfigure certain ``mongosync`` options by following the 


[Consistency/clarity]
I realize that the current content uses both "settings" and "options" (from command line options), but i think it may be best to stick with "settings" on this page for consistency.

Suggested change

During a migration, you can reconfigure certain ``mongosync`` options by following the

During a migration, you can reconfigure certain ``mongosync`` settings by following the

jwilson-mdb · 2025-01-07T22:51:19Z

source/reference/configuration.txt

+Settings
+~~~~~~~~
+
+The following settings can be set from a configuration file to configure ``mongosync`` at startup.


[Active Voice]

Rephrase to eliminate passive voice ("can be set") style guide

Suggested change

The following settings can be set from a configuration file to configure ``mongosync`` at startup.

You can configure the following ``mongosync`` settings at startup by using a configuration file.

jwilson-mdb · 2025-01-07T22:52:06Z

source/reference/configuration.txt


-Options
-=======
+To set these settings from the command line, see :ref:`c2c-cli-options`. 


[optional / nit]

Optional rephrasing to avoid the set/setting repetition

Suggested change

To set these settings from the command line, see :ref:`c2c-cli-options`.

To configure ``mongosync`` from the command line, see :ref:`c2c-cli-options`.

jwilson-mdb · 2025-01-07T23:09:12Z

source/reference/configuration.txt

+               --cluster1 "<cluster1_connection_string>" \
+               --loadLevel <newLevel> 
+
+      To learn more, see :ref:`Initialize mongosync <c2c-initialize>`.


[nit / optional 😄 ]

Nothing wrong with "To learn more", but I think we tend to lean towards "For more information" in the server docs.

jwilson-mdb · 2025-01-07T23:16:11Z

source/reference/mongosync.txt


   .. include:: /includes/opts/disableTelemetry

+   To disable telemetry data collection during a migration, 


[question / optional]

Would it make more sense to change the order slightly here and put the configuration file link before the link to reconfigure during a migration?

Maybe an SME can chime in, but my initial thought is someone viewing this page may find the configuration file link more relevant/useful than the reconfiguration instructions.

I'm not too sure how often someone might need to reconfigure so this is a weakly held opinion.

I was going back and forth with the ordering, so I appreciate the feedback. I agree with your reasoning here, so I moved the reconfig link below the config file link!

FGasper

This looks good overall. I have a couple small-ish points; see what you think.

FGasper · 2025-01-08T17:20:40Z

source/reference/configuration.txt

+
+.. important:: 
+
+   You can't adjust the :setting:`cluster0`, :setting:`cluster1`, or :setting:`id` settings during a migration. 


Is this list going to need further updates as further settings are added?

Something like this might be more maintainable:

Only the following settings are adjustable during a migration. Others MUST remain unchanged between mongosync restarts.

FGasper · 2025-01-08T17:26:19Z

source/reference/configuration.txt

+.. procedure::
+   :style: normal
+
+   .. step:: (Optional) Pause the ``mongosync`` processes


What is the benefit of doing this versus just terminating the mongosync processes?

The tip in this step (borrowed from the mongosync Live Upgrade tutorial) describes a reason why users might want to pause before terminating:

If you don't want to immediately resume data synchronization operations after live upgrade, consider pausing the mongosync processes. This is useful if you're coordinating operations from multiple mongosync processes.

Please let me know if you think this tip is not true or helpful! If that's the case, then I can remove this step and update the final step.

@jwilson-mdb

… mongosync’s documentation. (mongodb#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)

@jwilson-mdb

… mongosync’s documentation. (mongodb#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)

elyse-mdb · 2025-01-14T14:56:32Z

💚 All backports created successfully

Status	Branch	Result
✅	v1.9
✅	v1.8

Questions ?

Please refer to the Backport tool documentation

@jwilson-mdb

…sync’s-documentation-v1.8-backport (530) (#547) * (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.

@jwilson-mdb

…sync’s-documentation-v1.9-backport (530) (#546) * (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.

elyse-mdb force-pushed the DOCSP-45558-midMigrationLoadChange branch from ded05a2 to a828c63 Compare January 7, 2025 00:31

elyse-mdb added 13 commits January 7, 2025 10:29

(DOCSP-45558) Add section to FAQ page.

5ddd55e

(DOCSP-45558) Edits.

19cebe4

(DOCSP-45558) Edits.

7f37ca0

(DOCSP-45558) Procedure.

406508b

(DOCSP-45558) Edit formatting.

d80b0b0

(DOCSP-45558) Edits.

1410832

(DOCSP-45558) edits.

a850515

(DOCSP-45558) Edits.

30f4c3f

(DOCSP-45558) Add pause step to FAQ and edit FAQ link.

0e8b406

(DOCSP-45558) Add update section to configuration page.

b7b5373

(DOCSP-45558) Standardize link to update documentation.

a154b24

(DOCSP-45558) Edit.

e66c78e

(DOCSP-45558) Edits.

c93dc3d

elyse-mdb force-pushed the DOCSP-45558-midMigrationLoadChange branch from 294fa28 to c93dc3d Compare January 7, 2025 18:54

elyse-mdb added 11 commits January 7, 2025 12:15

(DOCSP-45558) Normalize links.

29bc7bb

(DOCSP-45558) Edit introduction to Optionsgst

f788814

q

(DOCSP-45558) Edit Settings introduction.

002ede1

(DOCSP-45558) Updates.

037dbc3

(DOCSP-45558) Make consistent intros to command line opts vs config f…

63816b6

…ile settings.

(DOCSP-45558) Edit wording.

59878c1

(DOCSP-45558) Shorten sentence.

c2ca328

(DOCSP-45558) updates.

fa4626b

(DOCSP-45558) Edits.

32b580a

(DOCSP-45558) Edit.

83a6717

(DOCSP-45558) Edit important admonition.

9df28f2

jwilson-mdb self-requested a review January 7, 2025 22:31

jwilson-mdb approved these changes Jan 7, 2025

View reviewed changes

(DOCSP-45558) @jwilson-mdb Review changes.

8cf96ed

(DOCSP-45558) Add command line options to configuration intro.

a2d3993

FGasper suggested changes Jan 8, 2025

View reviewed changes

elyse-mdb added 3 commits January 8, 2025 12:52

(DOCSP-45558) Fix subtitle underline.

5d64f55

(DOCSP-45558) Fix subtitle underline.

9382d4a

(DOCSP-45558) @FGasper Review changes.

7f8ea57

elyse-mdb requested review from FGasper and removed request for FGasper January 10, 2025 23:52

elyse-mdb merged commit ccd72ea into mongodb:master Jan 14, 2025
4 checks passed

elyse-mdb deleted the DOCSP-45558-midMigrationLoadChange branch January 14, 2025 14:54

elyse-mdb changed the title ~~(DOCSP-45558) [C2C] Mention altering load level during a migration in mongosync’s documentation.~~ (DOCSP-45558)-Mention-altering-load-level-during-a-migration-in-mongosync’s-documentation. Jan 14, 2025

elyse-mdb changed the title ~~(DOCSP-45558)-Mention-altering-load-level-during-a-migration-in-mongosync’s-documentation.~~ (DOCSP-45558)-Mention-altering-load-level-during-a-migration-in-mongosync’s-documentation Jan 14, 2025

elyse-mdb mentioned this pull request Jan 14, 2025

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

Merged

elyse-mdb mentioned this pull request Jan 14, 2025

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

Merged

	During a migration, you can reconfigure certain ``mongosync`` options by following the
	During a migration, you can reconfigure certain ``mongosync`` settings by following the

	The following settings can be set from a configuration file to configure ``mongosync`` at startup.
	You can configure the following ``mongosync`` settings at startup by using a configuration file.

	To set these settings from the command line, see :ref:`c2c-cli-options`.
	To configure ``mongosync`` from the command line, see :ref:`c2c-cli-options`.


		.. include:: /includes/opts/disableTelemetry

		To disable telemetry data collection during a migration,


		.. important::

		You can't adjust the :setting:`cluster0`, :setting:`cluster1`, or :setting:`id` settings during a migration.

(DOCSP-45558)-Mention-altering-load-level-during-a-migration-in-mongosync’s-documentation #530

(DOCSP-45558)-Mention-altering-load-level-during-a-migration-in-mongosync’s-documentation #530

Uh oh!

Conversation

elyse-mdb commented Dec 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIPTION

STAGING

JIRA

SELF-REVIEW CHECKLIST

EXTERNAL REVIEW REQUIREMENTS

Uh oh!

netlify bot commented Dec 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-cluster-to-cluster-sync ready!

Uh oh!

jwilson-mdb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FGasper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

elyse-mdb commented Jan 14, 2025

💚 All backports created successfully

Questions ?

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

elyse-mdb commented Dec 16, 2024 •

edited

Loading

netlify bot commented Dec 16, 2024 •

edited

Loading