DOCS-1381 updates to 'change oplog size'

source/tutorial/change-oplog-size.txt

@@ -13,154 +13,167 @@ if your applications perform large numbers of multi-updates or
 deletes in short periods of time.
 
 This tutorial describes how to resize the oplog. For a detailed
-explanation of oplog sizing, see the :ref:`replica-set-oplog-sizing`
-topic in the :doc:`/replication` document. For details on the how
+explanation of oplog sizing, see :ref:`replica-set-oplog-sizing`.
+For details how
 oplog size affects :term:`delayed members <delayed member>` and affects
-:term:`replication lag`, see the :ref:`replica-set-delayed-members`
-topic and :ref:`replica-set-replication-lag`.
+:term:`replication lag`, see :ref:`replica-set-delayed-members`.
 
 Overview
 --------
 
-The following is an overview of the procedure for changing the size of
-the oplog:
+Resize the oplog on each member
+separately, starting with the :term:`secondaries
+<secondary>`. Resize the :term:`primary's <primary>` oplog last. Resizing for a given
+member involves:
 
-.. include:: /includes/procedure-change-oplog-size.rst
+- Restart the member in standalone mode. For the primary, which is
+  done last, step it down first.
+
+- Recreate the oplog with the new size and with an old oplog entry to
+  seed it.
+
+- Restart the member normally.
 
 Procedure
 ---------
 
-The examples in this procedure use the following configuration:
+Perform a rolling update of the oplog size by shutting down a member,
+changing its oplog size, and restarting the member. Start with the
+non-primary members and end with the primary. Starting with the primary
+would trigger a :ref:`failover <replica-set-failover>` situation.
+Another member would become primary. In most cases, it is least
+disruptive to limit the number of primary changes to just the one at the end.
 
-- The active :term:`replica set` is ``rs0``.
+To change the size of the oplog for a replica set, use the following
+procedure for every member of the set that may become primary.
 
-- The replica set is running on port ``27017``.
+Restart a Secondary in Standalone Mode on a Different Port
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- The replica set is running with a :setting:`data directory <dbpath>`
-  of ``/srv/mongodb``.
+Shut down the :program:`mongod` instance for one of the non-primary
+members of your replica set. For example, to shut down, use the
+:method:`db.shutdownServer()` method:
 
-To change the size of the oplog for a replica set, use the following
-procedure for every member of the set that may become primary.
+.. code-block:: sh
 
-1. Shut down the :program:`mongod` instance and restart it in
-   "standalone" mode running on a different port.
+   db.shutdownServer()
 
-   .. note::
+Restart this :program:`mongod` as a standalone instance
+running on a different port and *without*
+the :option:`--replSet <mongod --replSet>` parameter. Use a command
+similar to the following:
 
-      Shutting down the :term:`primary` member of the set will trigger
-      a failover situation and another member in the replica set will
-      become primary. In most cases, it is least disruptive to modify
-      the oplogs of all the secondaries before modifying the primary.
+.. code-block:: sh
 
-   To shut down the current primary instance, use a command that
-   resembles the following:
+   mongod --port 37017 --dbpath /srv/mongodb
 
-   .. code-block:: sh
+Create a Backup of the Oplog (Optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-      mongod --dbpath /srv/mongodb --shutdown
+Optionally, backup the existing oplog on the standalone instance. For example:
 
-   To restart the instance on a different port and in "standalone"
-   mode (i.e. without :setting:`replSet` or
-   :option:`--replSet <mongod --replSet>`), use a command that
-   resembles the following:
+.. code-block:: sh
 
-   .. code-block:: sh
+   mongodump --db local --collection 'oplog.rs' --port 37017
 
-      mongod --port 37017 --dbpath /srv/mongodb
 
-#. Backup the existing oplog on the standalone instance. Use the
-   following sequence of commands:
+Recreate the Oplog with a New Size and a Seed Entry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   .. code-block:: sh
+Save the last entry from the oplog. For example, connect to the instance
+using the :program:`mongo` shell, and enter the following command to
+switch to the ``local`` database:
 
-      mongodump --db local --collection 'oplog.rs' --port 37017
+.. code-block:: javascript
 
-   .. note::
+   use local
 
-      You can restore the backup using the :program:`mongorestore`
-      utility.
+Use the :method:`db.collection.save()` operation and a sort on
+reverse :term:`natural order` to find the last entry and save it
+to a temporary collection:
 
-   Connect to the instance using the :program:`mongo` shell:
+.. _last-oplog-entry:
 
-   .. code-block:: sh
+.. code-block:: javascript
 
-      mongo --port 37017
+   db.temp.save( db.oplog.rs.find( { }, { ts: 1, h: 1 } ).sort( {$natural : -1} ).limit(1).next() )
 
-#. Save the last entry from the old (current) oplog.
+To see this oplog entry, issue the following command:
 
-   a. In the :program:`mongo` shell, enter the following command to use the
-      ``local`` database to interact with the oplog:
+.. code-block:: javascript
 
-      .. code-block:: javascript
+   db.temp.find()
 
-         use local
+Drop the Oplog
+~~~~~~~~~~~~~~
 
-   #. Use the :method:`db.collection.save()` operation to save the last
-      entry in the oplog to a temporary collection:
+Drop the old ``oplog.rs`` collection in the ``local`` database. Use
+the following command:
 
-      .. code-block:: javascript
+.. code-block:: javascript
 
-         db.temp.save( db.oplog.rs.find( { }, { ts: 1, h: 1 } ).sort( {$natural : -1} ).limit(1).next() )
+   db.oplog.rs.drop()
 
-      You can see this oplog entry in the ``temp`` collection by issuing
-      the following command:
+This returns ``true`` on the shell.
 
-      .. code-block:: javascript
+Create a New Oplog
+~~~~~~~~~~~~~~~~~~
 
-         db.temp.find()
+Use the :dbcommand:`create` command to create a new oplog of a
+different size. Specify the ``size`` argument in bytes. A value of
+``2 * 1024 * 1024 * 1024`` will create a new oplog that's 2 gigabytes:
 
-#. Drop the old ``oplog.rs`` collection in the ``local`` database. Use
-   the following command:
+.. code-block:: javascript
 
-   .. code-block:: javascript
+   db.runCommand( { create: "oplog.rs", capped: true, size: (2 * 1024 * 1024 * 1024) } )
 
-      db.oplog.rs.drop()
+Upon success, this command returns the following status:
 
-   This will return ``true`` on the shell.
+.. code-block:: javascript
 
-#. Use the :dbcommand:`create` command to create a new oplog of a
-   different size. Specify the ``size`` argument in bytes. A value of
-   ``2 * 1024 * 1024 * 1024`` will create a new oplog that's 2 gigabytes:
+   { "ok" : 1 }
 
-   .. code-block:: javascript
+Insert the Last Entry of the Old Oplog into the New Oplog
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-      db.runCommand( { create : "oplog.rs", capped : true, size : (2 * 1024 * 1024 * 1024) } )
+Insert the previously saved last entry from the old oplog into the
+new oplog. For example:
 
-   Upon success, this command returns the following status:
+.. code-block:: javascript
 
-   .. code-block:: javascript
+   db.oplog.rs.save( db.temp.findOne() )
 
-      { "ok" : 1 }
+To confirm the entry is in the new oplog, issue the following command:
 
-#. Insert the previously saved last entry from the old oplog into the
-   new oplog:
+.. code-block:: javascript
 
-   .. code-block:: javascript
+   db.oplog.rs.find()
 
-      db.oplog.rs.save( db.temp.findOne() )
+Restart the Member
+~~~~~~~~~~~~~~~~~~
 
-   To confirm the entry is in the new oplog, issue the following command:
+Restart the server as a member of the replica set on its usual
+port. For example:
 
-   .. code-block:: javascript
+.. code-block:: javascript
 
-      db.oplog.rs.find()
+   db.shutdownServer()
+   mongod --replSet rs0 --dbpath /srv/mongodb
 
-#. Restart the server as a member of the replica set on its usual
-   port:
+The replica member will recover and "catch up" and then will be
+eligible for election to primary.
 
-   .. code-block:: javascript
+Repeat Process for all Members that may become Primary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-      mongod --dbpath /srv/mongodb --shutdown
-      mongod --replSet rs0 --dbpath /srv/mongodb
+Repeat this procedure for all members for which to change the oplog
+size. We suggest you do this for all members that can become primary
+(i.e., members with a "non-zero" priority). Do not *yet* apply the
+procedure to the primary itself.
 
-   The replica member will recover and "catch up" and then will be
-   eligible for election to :term:`primary`. To step down the
-   "temporary" primary that took over when you initially shut down the
-   server, use the :method:`rs.stepDown()` method. This will force an
-   election for primary. If the server's
-   :data:`~local.system.replset.members[n].priority` is higher than all
-   other members in the set *and* if it has successfully "caught up,"
-   then it will likely become primary.
+Apply the Procedure to the Primary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-#. Repeat this procedure for all other members of the replica set that
-   are or could become primary.
+To finish the rolling upgrade, step down the primary with the
+:method:`rs.stepDown()` method and repeat the oplog resizing procedure
+above.