From 01d889ca7eb5a911870f7e0e0080c5660f05709a Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 7 Jan 2013 17:02:21 -0500 Subject: [PATCH 1/6] DOCS-154 DOCS-816 2.2 replica set behaviors --- source/administration/replica-sets.txt | 15 +++++++++++ source/core/replication-internals.txt | 37 ++++++++++++++++++++++---- source/release-notes/2.2.txt | 6 +++++ 3 files changed, 53 insertions(+), 5 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 549896860a0..fc3444c7f68 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -556,6 +556,21 @@ resource requirements and do not require dedicated hardware. rs.addArb("m1.example.net:30000") +.. _replica-set-configure-sync-target: + +Manually Configure a Secondary's Sync Target +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To override the default selection logic, if needed, and manually +configure a :term:`secondary` member's sync target for polling +:term:`oplog` entries, use either of the following: + +- :dbcommand:`replSetSyncFrom` command + +- :method:`rs.syncFrom()` helper in the :program:`mongo` shell + +Always exercise caution when overriding the default behavior. + .. _replica-set-procedure-change-oplog-size: Changing Oplog Size diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 94d986e314c..7ffce04cb8a 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -261,17 +261,17 @@ set members sync, or copy, :term:`oplog` entries from other members. When a new member joins a set or an existing member restarts, the member waits to receive heartbeats from other members. By default, the member syncs from the *the closest* member of the -set that is either the primary or another secondary with more recent -oplog entries. This prevents two secondaries from syncing from each other. +set that is either the primary or another :term:`secondary` with more recent +oplog entries. In version 2.0, secondaries only change sync targets if the connection -between secondaries drops or produces an error. +to the sync target drops or produces an error. For example: #. If you have two secondary members in one data center and a primary in a second facility, and if you start all three instances at roughly - the same time (i.e. with no existing data sets or oplog,) both + the same time (i.e. with no existing data sets or oplog), both secondaries will likely sync from the primary, as neither secondary has more recent oplog entries. @@ -283,4 +283,31 @@ For example: facility, the new secondary will likely sync from the existing secondary because it is closer than the primary. -.. seealso:: :ref:`replica-set-resync-stale-member` +In version 2.0, secondaries also use the following additional sync +behaviors: + +- Secondaries will sync from :ref:`delayed members + ` *only* if no other member is available. + +- Secondaries will *not* sync from :ref:`hidden members + `. + +- Secondaries will *not* start syncing from a member that has become + stale and is in recovering state. For more information on stale + members, see :ref:`replica-set-resync-stale-member`. + +- A secondary will not sync from a member that has no indexes, *unless* + the secondary's :data:`members[n].buildIndexes` field is set to + ``false``. For one member to sync from another, both must have the + same value, either ``true`` or ``false``, for + :data:`members[n].buildIndexes`. + +Indexes +------- + +By default, secondaries will in most cases pre-fetch :ref:`indexes` +associated with a query to improve replication throughput. If needed, +you can disable this feature using the :setting:`replIndexPrefetch` +setting or the :option:`--replIndexPrefetch ` option. Optionally you also can allow the +:program:`mongod` to pre-fetch only the index on the ``_id`` field. diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index f1b6f48e3da..ff4c91225ff 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -665,6 +665,8 @@ identify what process may produce errors or halt replication. See Replica Set Members can Sync from Specific Members `````````````````````````````````````````````````` +.. the following has been copied to source/administration/replica-sets.txt + The new :dbcommand:`replSetSyncFrom` command and new :method:`rs.syncFrom()` helper in the :program:`mongo` shell make it possible for you to manually configure from which member of the set a @@ -676,6 +678,8 @@ behavior. Replica Set Members will not Sync from Members Without Indexes Unless ``buildIndexes: false`` ````````````````````````````````````````````````````````````````````````````````````````````` +.. the following has been copied to source/core/replication-internals.txt + To prevent inconsistency between members of replica sets, if the member of a replica set has :data:`members[n].buildIndexes` set to ``true``, other members of the replica set will *not* sync from this @@ -685,6 +689,8 @@ member, unless they also have :data:`members[n].buildIndexes` set to New Option To Configure Index Pre-Fetching during Replication ````````````````````````````````````````````````````````````` +.. the following has been copied to source/core/replication-internals.txt + By default, when replicating options, :term:`secondaries ` will pre-fetch :ref:`indexes` associated with a query to improve replication throughput in most cases. The :setting:`replIndexPrefetch` setting and From 63fc0ca8dc7eb3fa39589d6de31deee8392381d3 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 8 Jan 2013 17:01:00 -0500 Subject: [PATCH 2/6] DOCS-154 review edits --- source/administration/replica-sets.txt | 9 ++++++--- source/core/replication-internals.txt | 26 ++++++++++++-------------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index fc3444c7f68..ba8665c9780 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -561,15 +561,18 @@ resource requirements and do not require dedicated hardware. Manually Configure a Secondary's Sync Target ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To override the default selection logic, if needed, and manually +To override the default selection logic, if needed, and to manually configure a :term:`secondary` member's sync target for polling -:term:`oplog` entries, use either of the following: +:term:`oplog` entries, use either of the following *before* initial sync: - :dbcommand:`replSetSyncFrom` command - :method:`rs.syncFrom()` helper in the :program:`mongo` shell -Always exercise caution when overriding the default behavior. +These commands do not work *during* initial sync. To specify a target +you must do so *before* initial sync starts. + +.. note:: Always exercise caution when overriding the default behavior. .. _replica-set-procedure-change-oplog-size: diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 7ffce04cb8a..d469b9f9e13 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -283,7 +283,7 @@ For example: facility, the new secondary will likely sync from the existing secondary because it is closer than the primary. -In version 2.0, secondaries also use the following additional sync +In version 2.2, secondaries also use the following additional sync behaviors: - Secondaries will sync from :ref:`delayed members @@ -292,22 +292,20 @@ behaviors: - Secondaries will *not* sync from :ref:`hidden members `. -- Secondaries will *not* start syncing from a member that has become - stale and is in recovering state. For more information on stale - members, see :ref:`replica-set-resync-stale-member`. +- Secondaries will *not* start syncing from a member in a + :term:`recovering` state. -- A secondary will not sync from a member that has no indexes, *unless* - the secondary's :data:`members[n].buildIndexes` field is set to - ``false``. For one member to sync from another, both must have the - same value, either ``true`` or ``false``, for - :data:`members[n].buildIndexes`. +- For one member to sync from another, both members must have the same + value, either ``true`` or ``false``, for the + :data:`members[n].buildIndexes` field. Indexes ------- By default, secondaries will in most cases pre-fetch :ref:`indexes` -associated with a query to improve replication throughput. If needed, -you can disable this feature using the :setting:`replIndexPrefetch` -setting or the :option:`--replIndexPrefetch ` option. Optionally you also can allow the -:program:`mongod` to pre-fetch only the index on the ``_id`` field. +associated with a query to improve replication throughput. Pre-fetching +loads in index into memory in anticipation of its need. + +You can limit this feature to pre-fetch only the index on the ``_id`` +field, or you can disable this feature entirely. For more information, +see :setting:`replIndexPrefetch`. From e71ba0d6610e21d4647e26a5a6ddcc6cd6c55ac4 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 8 Jan 2013 17:09:40 -0500 Subject: [PATCH 3/6] DOCS-154 typo --- source/core/replication-internals.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index d469b9f9e13..a9b38696ff5 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -304,7 +304,7 @@ Indexes By default, secondaries will in most cases pre-fetch :ref:`indexes` associated with a query to improve replication throughput. Pre-fetching -loads in index into memory in anticipation of its need. +loads an index into memory in anticipation of its need. You can limit this feature to pre-fetch only the index on the ``_id`` field, or you can disable this feature entirely. For more information, From c572bea1d24124bfce8499c79d717515771666e3 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 10 Jan 2013 15:05:19 -0500 Subject: [PATCH 4/6] DOCS-154 review edits --- source/administration/replica-sets.txt | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index ba8665c9780..4710723ad41 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -562,17 +562,21 @@ Manually Configure a Secondary's Sync Target ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To override the default selection logic, if needed, and to manually -configure a :term:`secondary` member's sync target for polling -:term:`oplog` entries, use either of the following *before* initial sync: +configure a :term:`secondary` member's sync target for pulling +:term:`oplog` entries, use either of the following commands. If you want +your choice to affect the initial sync, run the command *before* initial +sync. Always exercise caution when overriding the default behavior: - :dbcommand:`replSetSyncFrom` command - :method:`rs.syncFrom()` helper in the :program:`mongo` shell -These commands do not work *during* initial sync. To specify a target -you must do so *before* initial sync starts. +These commands do not work *during* initial sync. To affect initial +sync, you must specify a target *before* initial sync starts. -.. note:: Always exercise caution when overriding the default behavior. +The commands provide a temporary override of default behavior. The +change does not persist if the :program:`mongod` instance or the sync +socket closes. .. _replica-set-procedure-change-oplog-size: From c07d0916145f5bd601d5bf950526107f964f4af4 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 10 Jan 2013 16:27:32 -0500 Subject: [PATCH 5/6] DOCS-154 review edits --- source/administration/replica-sets.txt | 4 +++- source/core/replication-internals.txt | 7 +++---- source/reference/command/replSetSyncFrom.txt | 5 +++++ 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 4710723ad41..7645ee0f018 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -573,8 +573,10 @@ sync. Always exercise caution when overriding the default behavior: These commands do not work *during* initial sync. To affect initial sync, you must specify a target *before* initial sync starts. +If you run one of the commands during initial sync, no error message +appears, but the sync target does not change until initial sync completes. -The commands provide a temporary override of default behavior. The +These commands provide a temporary override of default behavior. The change does not persist if the :program:`mongod` instance or the sync socket closes. diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index a9b38696ff5..f1489b5b9e4 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -299,12 +299,11 @@ behaviors: value, either ``true`` or ``false``, for the :data:`members[n].buildIndexes` field. -Indexes -------- +Pre-Fetching Indexes to Improve Replication Throughput +------------------------------------------------------ By default, secondaries will in most cases pre-fetch :ref:`indexes` -associated with a query to improve replication throughput. Pre-fetching -loads an index into memory in anticipation of its need. +associated with a query to improve replication throughput. You can limit this feature to pre-fetch only the index on the ``_id`` field, or you can disable this feature entirely. For more information, diff --git a/source/reference/command/replSetSyncFrom.txt b/source/reference/command/replSetSyncFrom.txt index 66fa7542e9b..6dade01cd5f 100644 --- a/source/reference/command/replSetSyncFrom.txt +++ b/source/reference/command/replSetSyncFrom.txt @@ -30,6 +30,11 @@ replSetSyncFrom behind the current member, :program:`mongod` will return and log a warning, but *will* sync from such members. + If you attempt to change a member's sync target *during* initial + sync, the change will not take effect until initial sync completes. + No error message appears, but the sync target does not change until + after initial sync. + The command has the following prototype form: .. code-block:: javascript From f6841953032758d08ec20ce05ffc3230180b4693 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 11 Jan 2013 12:45:08 -0500 Subject: [PATCH 6/6] DOCS-154 final review edits --- source/core/replication-internals.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index f1489b5b9e4..5086091274c 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -303,7 +303,7 @@ Pre-Fetching Indexes to Improve Replication Throughput ------------------------------------------------------ By default, secondaries will in most cases pre-fetch :ref:`indexes` -associated with a query to improve replication throughput. +associated with the affected document to improve replication throughput. You can limit this feature to pre-fetch only the index on the ``_id`` field, or you can disable this feature entirely. For more information,