comments on replication docs

Author: kchodorow

source/administration/replica-sets.rst

@@ -40,23 +40,32 @@ From to time, you may need to add an additional member to an existing
   replication process before the member can exit ":term:`recovering`"
   status, and become a :term:`secondary` member.
 
+TODO: might be worth mentioning that "you" don't have to copy this data, it's done automatically.
+
 - copy the data directory from an existing member to limit the amount
   of time that the recovery process takes.
 
+TODO: if you copy from an existing member, the new member will immediately be a secondary (not recovering).
+
   If the difference in the amount of time between the most recent
   operation and the most recent operation to the database exceeds the
   length of the :term:`oplog` on the existing members, then the new
   instance will have to completely re-synchronize. Ensure that you can
   copy the data to the new system and begin replication within the
   window allowed by the :term:`oplog`.
 
+TODO: maybe mention you can do this with the db.printReplicationInfo() function.
+
 To add a member to an existing :term:`replica set`, deploy a new
 :program:`mongod` instance, specifying the name of the replica set
 (i.e. "setname" or ``replSet``) on the command line with the
 :option:`--replSet <mongod --replSet>` option or in the configuration
 with the :setting:`replSet`. Take note of the host name and
 port information for the new :program:`mongod` instance.
 
+TODO: "the configuration
+with" -> the configuration file with
+
 Then, log in to the current primary using the :program:`mongo`
 shell. Issue the :func:`db.isMaster()` command when connected to *any*
 member of the set to determine the current :term:`primary`. Issue the
@@ -73,6 +82,8 @@ of the fields in a :data:`members` document, for example:
 
    rs.add({host: "mongo2.example.net:27017", priority: 0, hidden: true})
 
+TODO: is the _id field automatically populated?
+
 This configures a :term:`hidden member` that is accessible at
 ``mongo2.example.net:27018``. See ":data:`host <members[n].host>`,"
 ":data:`priority <members[n].priority>`," and ":data:`hidden
@@ -123,6 +134,8 @@ in the :program:`mongo` shell:
    rs.remove("mongo2.example.net:27018")
    rs.add({host: "mongo2.example.net:27019", priority: 0, hidden: true})
 
+TODO: prior to 2.2, this will almost never work because the _id will change.
+
 Second, you may consider using the following procedure to use
 :func:`rs.reconfig()` to change the value of the
 :data:`members[n].host` field to reflect the new hostname or port
@@ -284,6 +297,8 @@ the :program:`mongo` shell to modify node priorities:
    cfg.members[3].priority = 2
    rs.reconfig(cfg)
 
+TODO: this is actually 4 nodes...
+
 This operation sets the member ``0`` to ``0`` and cannot become
 primary. Member ``3`` has a priority of ``2`` and will become primary,
 if eligible, under most circumstances. Member ``2`` has a priority of
@@ -320,6 +335,10 @@ operations in the :program:`mongo` shell:
    cfg.members[0].hidden = true
    rs.reconfig(cfg)
 
+TODO: it might be worth noting that, currently, you must send the reconfig command to
+a member that can become primary in the new configuration.  So, if members[0] is the
+current primary, this reconfig won't work.
+
 After re-configuring the set, the node with the "``_id``" of ``0``,
 has a priority of ``0`` so that it cannot become master, while the
 other nodes in the set will not advertise the hidden node in the
@@ -519,4 +538,6 @@ data to a :term:`BSON`.
 You can prevent Rollbacks prevented by ensuring safe writes by using
 the appropriate :term:`write concern`.
 
+TODO: "rollback" is not a proper noun.
+
 .. seealso:: ":ref:`Replica Set Elections <replica-set-elections>`"

source/administration/replication-architectures.rst

@@ -10,6 +10,8 @@ of replica sets may be its greatest strenght. This document outlines
 and describes the most prevalent deployment patterns for replica set
 administrators.
 
+TODO: strenght?
+
 .. seealso:: ":doc:`/administration/replica-sets`" and
    ":doc:`/reference/replica-configuration`."
 
@@ -65,6 +67,8 @@ architectural conditions are true:
 
 - A majority *of the set's* members exist in the main data center.
 
+TODO: I don't understand why "of the set's" is emphasized.
+
 .. seealso:: ":doc:`/tutorial/expand-replica-set`."
 
 .. _replica-set-geographical-distribution:
@@ -138,6 +142,8 @@ settings relevant for these kinds of nodes:
   of votes, if you need to have more than 7 members of a replica
   set. (:ref:`see also <replica-set-non-voting-members>`.)
 
+TODO: and the potential... for royally screwing yourself.
+
 Backups
 ~~~~~~~
 
@@ -149,6 +155,9 @@ perspective, to the primary node or likely primary, and that the
 create a dedicated :ref:`hidden node <replica-set-hidden-members>` for
 the purpose of creating backups.
 
+TODO: Glitch in the matrix: "a replica set member for dedicated
+backup for dedicated backup purposes"
+
 If this node have journaling enabled, you can safely use standard
 :ref:`block level backup methods <block-level-backup>` to create a
 backup of this node. Otherwise, if your underlying system does not

source/applications/replication.rst

@@ -68,6 +68,10 @@ replica set configuration. For instance:
    cfg.settings.getLastErrorDefaults = "w: majority, fsync: false, j: true"
    rs.reconfig(cfg)
 
+TODO: Incorrect getLastErrorDefaults setting:
+   cfg.settings.getLastErrorDefaults = {w: "majority", fsync: false, j: true}
+
+
 When the new configuration is active, the effect of the
 :dbcommand:`getLastError` operation will wait until the write
 operation has succeeded on a majority of the nodes before writing. By

source/core/replication-internals.rst

@@ -30,6 +30,8 @@ exceptional situations may cause secondaries lag behind further. See
 All nodes send heartbeats to all other nodes, and will import
 operations into its oplog from the node with the lowest "ping" time.
 
+TODO: the lowest "ping" time thing is very specific to 2.0, it wasn't true in 1.8 and probably will be different again in 2.2.  Not sure if you care or not.
+
 .. _replica-set-implementation:
 
 Implementation
@@ -48,6 +50,8 @@ section for more about ":ref:`read preference
 <replica-set-read-preference>`" and ":ref:`write concern
 <replica-set-write-concern>`."
 
+TODO: "However, clients possible..."
+
 .. note::
 
    Use :func:`db.getReplicationInfo()` from a secondary node
@@ -115,6 +119,8 @@ looses contact with a :term:`primary` node. All members have one vote
 in an election, and every :program:`mongod` can veto an election. A
 single member's veto will invalidate the election.
 
+TODO: sp: looses
+
 An existing primary will step down in response to the
 :dbcommand:`replSetStepDown` command, or if it sees that one of
 the current secondaries is eligible for election *and* has a higher

source/core/replication.rst

@@ -18,6 +18,8 @@ ensure high availability, simplifies certain administrative tasks
 such as backups, and may increase read capacity. Most production
 deployments are or should use replication.
 
+TODO: "are or should use replication."  are use replication?
+
 If you're familiar with other database systems, you may think about
 replica sets as a more sophisticated form of traditional master-slave replication. [#master-slave]_
 In master-slave replication, a ":term:`master`" node accepts writes while one or more
@@ -196,6 +198,8 @@ remain a secondary.
    all client connections. This ensures that the clients maintain an accurate
    view of the :term:`replica set` and helps prevent :term:`rollbacks <rollback>`.
 
+TODO: it's actually just when a primary steps down that connections are closed.
+
 .. seealso:: ":ref:`Replica Set Election Internals <replica-set-election-internals>`"
 
 .. _replica-set-node-priority:
@@ -261,6 +265,14 @@ secondary those operations the former primary must revert these
 operations or "rolled back" these operations to maintain database
 consistency across the replica set.
 
+TODO: ":term:`primary` nodes will have
+accepted write operations that have replicated to the
+:term:`secondaries <secondary>`" -> have not replicated to the secondary
+
+TODO: "as a
+secondary those operations the former primary must revert these
+operations or" those operations...these operations
+
 MongoDB writes the rollback data to a :term:`BSON` file in the
 database's :setting:`dbpath` directory. Use :doc:`bsondump
 </reference/bsondump>` to read the contents of these rollback files
@@ -271,6 +283,9 @@ administrator's direct intervention, users should strive to avoid
 rollbacks as much as possible. Until an administrator applies this
 rollback data, the former primary remains in a "rollback" status.
 
+TODO: "Until an administrator applies this
+rollback data, the former primary remains in a "rollback" status." Untrue!  ROLLBACK state should automatically correct itself and the server will end up in SECONDARY state.
+
 The best strategy for avoiding all rollbacks is to ensure :ref:`write
 propagation <replica-set-write-concern>` to all or some of the
 nodes in the set. Using these kinds of policies prevents situations
@@ -289,6 +304,8 @@ that might create rollbacks.
    data and restarts the :program:`mongod` instance. Only then can the
    node becomes a normal :term:`secondary` terms.
 
+TODO: not true...
+
 Application Concerns
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -442,6 +459,8 @@ the existing members.
    and the database may remain in an inconsistent state and
    unrecoverable state.
 
+TODO: this isn't true.  If you are running w/out journaling and mongod terminates "ungracefully" you can lose _all_ data.  Also, you should assume, after a crash w/out journaling, that the db is in an inconsistent (i.e., corrupt) state.
+
    **Use journaling**, however, do not forego proper replication
    because of journaling.
 

source/reference/replica-configuration.rst

@@ -57,6 +57,8 @@ Configuration Variables
       :data:`members[n].host` cannot hold a value that
       resolves to ``localhost`` or the local interface.
 
+TODO: unless all of the members in the set do.  You can have all-or-none localhost.
+
 .. data:: members[n].arbiterOnly
 
    *Optional*.
@@ -81,6 +83,9 @@ Configuration Variables
    become a master, or if any clients ever issue queries against this
    instance.
 
+TODO: whether, not weather
+Probably "Do not set to false if a member *can* become a master..."
+
    Omitting index creation, and thus this setting, may be useful,
    **if**:
 

source/reference/replica-status.rst

@@ -18,6 +18,8 @@ in heartbeats sent to the current instance by other members of the
 replica set: because of the frequency of heartbeats, these data can be
 at most 2 seconds out of date.
 
+TODO: not sure I'd commit to 2 seconds, as the timeout before heartbeat fails is ~20 seconds. So maybe "this data can be a few seconds out-of-date"?
+
 .. note::
 
    The :program:`mongod` that you issue the :dbcommand:`replSetGetStatus`
@@ -38,6 +40,8 @@ Statuses
    The ``set`` value is the name of the replica set, configured in the
    :setting:`replSet` setting.
 
+TODO: might want to mention it's the same as the _id in rs.conf(), but no one's ever expressed confusion about that, so minor point.
+
 .. status:: rs.status.date
 
    The value of the ``date`` field is an :term:`ISODate` of the
@@ -53,6 +57,8 @@ Statuses
    the state of the member. These integers map to states, as described
    in the following table:
 
+TODO: an integer between 0 and 10, now.
+
    ==========  ==========================================================
    **Number**  **State**
    ----------  ----------------------------------------------------------
@@ -76,6 +82,8 @@ Statuses
    <repl-set-member-statuses>`" for an overview of the values included
    in these documents.
 
+TODO: this is missing the syncedTo field, only present on secondaries (and recovering nodes) that shows who they're syncing from.
+
 .. _repl-set-member-statuses:
 
 Member Statuses
@@ -121,12 +129,16 @@ Member Statuses
       A 64-bit timestamp of the last operation applied to this member
       of the replica set from the :term:`oplog`.
 
+TODO: 32-bit (t+i=64-bit)
+
    .. status:: members.optime.i
 
       An incremented field, which reflects the number of operations in
       since the last time stamp. This value only increases if there
       are more than one operation per second.
 
+TODO: ...if there is more
+
 .. status:: members[n].optimeDate
 
    An :term:`ISODate` formatted date string that reflects the last

source/reference/replication-info.rst

@@ -73,6 +73,9 @@ The following fields appear in the output of
    Returns a time stamp for the first (i.e. earliest) operation in the
    :term:`oplog`. Compare this value to :status:`now`.
 
+TODO: copypasta with tFirst
+Also, please don't encourage people to compare this with "now", they should compare it to the last time they did a write.  tLast could be days ago, but if there haven't been any writes since, lag is 0.
+
 .. status:: now
 
    Returns a time stamp reflecting the current time. The shell process