DOCS-242: Updated for style and content.

Author: Bob Grabar

source/core/replication-internals.txt

@@ -7,11 +7,10 @@ Replication Internals
 Synopsis
 --------
 
-This document provides a more in-depth explanation of the internals
-and operation of replica set features. This material is not necessary
-for normal operation or application development, but may be
-useful for troubleshooting, helpful understanding MongoDB's behavior,
-or interesting for learning about MongoDB's approach.
+This document provides a more in-depth explanation of the internals and
+operation of :term:`replica set` features. This material is not necessary for
+normal operation or application development but may be useful for
+troubleshooting and for further understanding MongoDB's behavior and approach.
 
 .. index:: replica set; oplog
 .. _replica-set-oplog:
@@ -21,19 +20,17 @@ Oplog
 
 Replication itself works by way of a special :term:`capped collection`
 called the :term:`oplog`. This collection keeps a rolling record of
-all operations applied to the primary node. Secondary nodes then
+all operations applied to the :term:`primary`. Secondary members then
 replicate this log by applying the operations to themselves in an
-asynchronous process.  Under normal operation, secondary nodes will
+asynchronous process.  Under normal operation, :term:`secondary` members
 reflect writes within one second of the primary. However, various
-exceptional situations may cause secondaries lag behind further. See
+exceptional situations may cause secondaries to lag behind further. See
 :term:`replication lag` for details.
 
-Also consider :ref:`oplog sizing <replica-set-oplog-sizing>` for more
-information about the oplog.
+All members send heartbeats (pings) to all other members in the set and can
+import operations to the local oplog from any other member in the set.
 
-All members send heartbeats to all other members, and can import
-operations to into its oplog from any other member in the
-set.
+For more information about the oplog, see :ref:`oplog sizing <replica-set-oplog-sizing>`.
 
 .. In 2.0, replicas would import entries from the member lowest
 .. "ping," This wasn't true in 1.8 and will likely change in 2.2.
@@ -47,65 +44,64 @@ MongoDB uses :term:`single-master replication` to ensure that the
 database remains consistent. However, clients may modify the
 :ref:`read preferences <replica-set-read-preference>` on a
 per-connection basis in order to distribute read operations to the
-secondary members of a replica set. Read-heavy deployments may achieve
-greater query volumes by distributing reads to secondary nodes. But
+:term:`secondary` members of a :term:`replica set`. Read-heavy deployments may achieve
+greater query volumes by distributing reads to secondary members. But
 keep in mind that replication is asynchronous; therefore, reads from
 secondaries may not always reflect the latest writes to the
-primary. See the ":ref:`consistency <replica-set-consistency>`"
-section for more about ":ref:`read preference
-<replica-set-read-preference>`" and ":ref:`write concern
-<replica-set-write-concern>`."
+:term:`primary`. See the :ref:`consistency <replica-set-consistency>`
+section for more about :ref:`read preference
+<replica-set-read-preference>` and :ref:`write concern
+<replica-set-write-concern>`.
 
 .. note::
 
-   Use :func:`db.getReplicationInfo()` from a secondary node
-   and the ":doc:`replication status </reference/replication-info>`
-   output to asses the current state of replication, and determine if
+   Use :func:`db.getReplicationInfo()` from a secondary member
+   and the :doc:`replication status </reference/replication-info>`
+   output to asses the current state of replication and determine if
    there is any unintended replication delay.
 
-In the default configuration, all have nodes an equal chance of
-becoming primary; however, it's possible to set "priorities" that
+In the default configuration, all members have an equal chance of
+becoming primary; however, it's possible to set :data:`priority <members[n].priority>` values that
 weight the election. In some architectures, there may be operational
 reasons for increasing the likelihood of a specific replica set member
-becoming primary. For instance, a node located in a remote data
-center should become primary . See: ":ref:`node
-priority <replica-set-node-priority>`" for more background on this
+becoming primary. For instance, a member located in a remote data
+center should *not* become primary. See: :ref:`node
+priority <replica-set-node-priority>` for more background on this
 concept.
 
-Replica sets can also include nodes with four special
-configurations which affect membership behavior in a replica
-set. Consider the following node types:
+Replica sets can also include members with the following four special
+configurations that affect membership behavior:
 
-- :ref:`Secondary-only <replica-set-secondary-only-members>` members
-  have their "priority" set to 0 and thus not eligible for election as
-  primary nodes.
+- :ref:`Secondary-only <replica-set-secondary-only-members>` members have
+  their :data:`priority <members[n].priority>` values set to ``0`` and thus
+  are not eligible for election as primaries.
 
 - :ref:`Hidden <replica-set-hidden-members>` members do not appear in the
-  output of :func:`db.isMaster()`. This setting prevents clients
-  from discovering, and thus potentially queries, the node in question.
+  output of :func:`db.isMaster()`. This prevents clients
+  from discovering and potentially querying the member in question.
 
 - :ref:`Delayed <replica-set-delayed-members>` members lag a fixed period
-  of time behind the the primary node. These nodes are typically used
+  of time behind the primary. These members are typically used
   for disaster recovery scenarios. For example, if an administrator
   mistakenly truncates a collection, and you discover the mistake within
-  the lag window, then you can manually fail over to the delayed node.
+  the lag window, then you can manually fail over to the delayed member.
 
 - :ref:`Arbiters <replica-set-arbiters>` exist solely to participate
   in elections. They do not replicate data from the primary.
 
 In almost every case, replica sets simplify the process of
-administering database replication; however, replica sets still have a
+administering database replication. However, replica sets still have a
 unique set of administrative requirements and concerns. Choosing the
 right :doc:`system architecture </administration/replication-architectures>`
 for your data set is crucial.
 
 Administrators of replica sets also have unique :ref:`monitoring
-<replica-set-monitoring>`, and :ref:`security <replica-set-security>`
+<replica-set-monitoring>` and :ref:`security <replica-set-security>`
 concerns. The :ref:`replica set functions <replica-set-functions>` in
 the :program:`mongo` shell, provide the tools necessary for replica set
 administration. In particular use the :func:`rs.conf()` to return a
 :term:`document` that holds the :doc:`replica set configuration
-</reference/replica-configuration>`, and :func:`rs.reconfig()` to
+</reference/replica-configuration>` and use :func:`rs.reconfig()` to
 modify the configuration of an existing replica set.
 
 .. index:: replica set; elections
@@ -118,30 +114,30 @@ Elections
 When you initialize a :term:`replica set` for the first time, or when any
 failover occurs, an election takes place to decide which member should
 become :term:`primary`. A primary is the only member in the replica
-set that can accept write operations including :func:`insert()
+set that can accept write operations, including :func:`insert()
 <db.collection.insert()>`, :func:`update() <db.collection.update()>`,
 and :func:`remove() <db.collection.remove()>`.
 
 Elections are the process replica set members use to
-select the primary in a set. Elections follow after one of two events:
-a primary that "steps down" or a :term:`secondary` that
-loses contact with a :term:`primary` member. All members have one vote
+select the primary in a set. Two types of events can trigger an election:
+a primary steps down or a :term:`secondary` member
+loses contact with a primary. All members have one vote
 in an election, and any :program:`mongod` can veto an election. A
-single veto will invalidate the election.
+single veto invalidates the election.
 
 An existing primary will step down in response to the
-:dbcommand:`replSetStepDown` command, or if it sees that one of
+:dbcommand:`replSetStepDown` command or if it sees that one of
 the current secondaries is eligible for election *and* has a higher
 priority. A secondary will call for an election if it cannot
-establish a connection to a primary member. A primary will also step
-down when they cannot contact a majority of the members of the replica
-set. When the current primary member steps down, it closes all open client
+establish a connection to a primary. A primary will also step
+down when it cannot contact a majority of the members of the replica
+set. When the current primary steps down, it closes all open client
 connections to prevent clients from unknowingly writing data to a
 non-primary member.
 
 In an election, every member, including :ref:`hidden
 <replica-set-hidden-members>` members, :ref:`arbiters
-<replica-set-arbiters>`, and even recovering members get a single
+<replica-set-arbiters>`, and even recovering members, get a single
 vote. Members will give votes to every eligible member that calls an
 election.
 
@@ -150,24 +146,24 @@ conditions:
 
 - If the member seeking an election is not a member of the voter's set.
 
-- If the member seeking an election is not up to date with the most
+- If the member seeking an election is not up-to_date with the most
   recent operation accessible in the replica set.
 
 - If the member seeking an election has a lower priority than another member
   in the set that is also eligible for election.
 
-- If the current :term:`primary` member has more recent operations
+- If the current primary member has more recent operations
   (i.e. a higher "optime") than the member seeking election, from the
   perspective of the voting member.
 
 - The current primary will also veto an election if it has the same or
   more recent operations (i.e. a "higher or equal optime") than the
-  node seeking election.
+  member seeking election.
 
 .. note::
 
-   Any member of a replica set *can* veto an election, even if they
-   are :ref:`non-voting members <replica-set-non-voting-members>`.
+   Any member of a replica set *can* veto an election, even if the
+   member is a :ref:`non-voting member <replica-set-non-voting-members>`.
 
 The first member to receive votes from a majority of members in a set
 becomes the next primary until the next election. Be
@@ -177,61 +173,58 @@ aware of the following conditions and possible situations:
   seconds. If a heartbeat does not return for more than 10 seconds,
   the other members mark the delinquent member as inaccessible.
 
-- Replica set members only compare priorities with other members of
+- Replica set members compare priorities only with other members of
   the set. The absolute value of priorities does not have any impact on
   the outcome of replica set elections.
 
   .. note::
 
-     The only exception is that members with a priority of ``0``
-     cannot become :term:`primary` and will not seek election. See
+     The only exception is that members with :data:`priority <members[n].priority>` values of ``0``
+     cannot become primary and will not seek election. See
      :ref:`replica-set-node-priority-configuration` for more
      information.
 
-- Replica set members cannot become primary *unless* they have the
-  highest "optime" of any visible members in the set.
+- A replica set member cannot become primary *unless* it has the
+  highest "optime" of any visible member in the set.
 
 - If the member of the set with the highest priority is within 10
-  seconds of the latest oplog entry, then the set will *not* elect a
-  :term:`primary` until the member with the highest priority catches up
+  seconds of the latest :term:`oplog` entry, then the set will *not* elect a
+  primary until the member with the highest priority catches up
   to the latest operation.
 
 
-.. seealso:: ":ref:`Non-voting members in a replica
-             set<replica-set-non-voting-members>`",
-             ":ref:`replica-set-node-priority-configuration`", and
-             ":data:`replica configuration <members[n].votes>`
+.. seealso:: :ref:`Non-voting members in a replica
+             set<replica-set-non-voting-members>`,
+             :ref:`replica-set-node-priority-configuration`, and
+             :data:`replica configuration <members[n].votes>`
 
 Syncing
 -------
 
-Replica set members sync, or copy :term:`oplog` entries, from the
-:term:`primary` or another :term:`secondary` member of the set in
-order to remain up to date with the current state of the set.
+In order to remain up-to-date with the current state of the :term:`replica set`,
+set members sync, or copy, :term:`oplog` entries from other members.
 
-When a new member joins a set, or an existing member restarts, the new
-member waits to receive heartbeats from other members. Then, by
-default, a new member will sync 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.
+When a new member joins a set or when 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.
 
 In version 2.0, secondaries only change sync targets if the connection
 between secondaries drops or produces an error.
 
 For example:
 
-#. If you have two secondary members in one data center, a primary in
-   a second facility, *and* you start all three instances at roughly
+#. 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
    secondaries will likely sync from the primary, as neither secondary
    has more recent oplog entries.
 
-   If you restart one of the secondaries, when it rejoins the set it
-   will likely begin syncing from the other secondary.
+   If you restart one of the secondaries, then when it rejoins the set it
+   will likely begin syncing from the other secondary, because of proximity.
 
-#. If, you have a primary in one facility, and a secondary in an
-   alternate facility, and you add another secondary to the alternate
-   facility, the new secondary will likely sync from the older
-   secondary because this member is closer and has more recent oplog
-   entries.
+#. If you have a primary in one facility and a secondary in an
+   alternate facility, and if you add another secondary to the alternate
+   facility, the new secondary will likely sync from the existing
+   secondary because it is closer than the primary.