DOCS-2315: updates log rotate tutorial with new steps && new behaviors

source/includes/steps-log-rotate-rename.yaml

@@ -0,0 +1,55 @@
+stepnum: 1
+ref: start-mongod
+title: "Start a :program:`mongod` instance."
+action:
+  language: sh
+  code: |
+    mongod -v --logpath /var/log/mongodb/server1.log
+post: |
+  You can also explicitly specify :option:`logRotate --rename
+  <--logRotate>`.
+---
+stepnum: 2
+title: List the log files
+ref: list-logfiles
+pre: |
+  In a separate terminal, list the matching files:
+action:
+  language: sh
+  code: |
+     ls /var/log/mongodb/server1.log*
+post: |
+  The results should include one log file, ``server1.log``.
+---
+stepnum: 3
+ref: rotate-log
+title: Rotate the log file.
+pre: |
+  Rotate the log file by issuing the :dbcommand:`logRotate` command
+  from the ``admin`` database in a :program:`mongo` shell:
+action:
+  language: sh
+  code: |
+    use admin
+    db.runCommand( { logRotate : 1 } )
+---
+stepnum: 4
+ref: list-new-logfiles
+title: 'View the new log files'
+pre: |
+  List the new log files to view the newly-created log:
+action:
+  language: sh
+  code: |
+    ls /var/log/mongodb/server1.log*
+post: |
+  There should be two log files listed: ``server1.log``, which is the
+  log file that :program:`mongod` or :program:`mongos` made when it 
+  reopened  the log file, and ``server1.log.<timestamp>``, the renamed
+  original log file.
+
+  Rotating log files does not modify the "old" rotated log files. When
+  you rotate a log, you rename the ``server1.log`` file to include
+  the timestamp, and a new, empty ``server1.log`` file receives all
+  new log input.
+...

source/includes/steps-log-rotate-reopen.yaml

@@ -0,0 +1,24 @@
+stepnum: 1
+ref: rotate-logs-reopen
+title: "Start a :program:`mongod` instance, specifying the ``reopen`` :option:`--logRotate` behavior."
+action:
+  language: sh
+  code: |
+    mongod -v --logpath /var/log/mongodb/server1.log --logRotate reopen --logappend
+post: |
+  You must use the :option:`--logappend` option with
+  :option:`--logRotate reopen <--logRotate>`.
+---
+stepnum: 2
+source:
+  file: steps-log-rotate-rename.yaml
+  ref: list-logfiles
+---
+stepnum: 3
+source:
+  file: steps-log-rotate-rename.yaml
+  ref: rotate-log
+post: |
+  You should rename the log file using an external process, following
+  the typical Linux/Unix log rotate behavior.
+...

source/includes/steps-log-rotate-syslog.yaml

@@ -0,0 +1,23 @@
+stepnum: 1
+ref: start-mongod-syslog
+title: 'Start a :program:`mongod` instance with the :option:`--syslog` option'
+action:
+  language: sh
+  code: |
+    mongod --syslog
+post: |
+  Do not include :option:`--logpath`. Since :option:`--syslog` tells
+  :program:`mongod` to send log data to the syslog, specifying a
+  :option:`--logpath` will causes an error.
+
+   To specify the facility level used when logging messages to the syslog,
+   use the :option:`--syslogFacility` option or 
+   :setting:`systemLog.syslogFacility` configuration setting.
+---
+stepnum: 2
+ref: rotate-log-syslog
+title: Rotate the log.
+pre: |
+  Store and rotate the log output using your systems default log
+  rotation mechanism.
+...

source/tutorial/rotate-log-files.txt

@@ -7,111 +7,74 @@ Rotate Log Files
 Overview
 --------
 
-Log rotation using MongoDB's standard approach archives the current
+When used with the :option:`--logpath` option or :setting:`systemLog.path` setting,
+:program:`mongod` and :program:`mongos` instances report
+a live account of all activity and operations to a log file. 
+When reporting activity data to a log file, by default, MongoDB only rotates logs
+in response to the :dbcommand:`logRotate` command, or when the
+:program:`mongod` or :program:`mongos` process receives a ``SIGUSR1``
+signal from the operating system.
+
+MongoDB's standard log rotation approach archives the current
 log file and starts a new one. To do this, the :program:`mongod` or
 :program:`mongos` instance renames the current log file by appending a
-UTC (GMT) timestamp to the filename, in :term:`ISODate` format. It then
+UTC timestamp to the filename, in :term:`ISODate` format. It then
 opens a new log file, closes the old log file, and sends all new log
 entries to the new log file.
 
-MongoDB's standard approach to log rotation only rotates logs
-in response to the :dbcommand:`logRotate` command, or when the
-:program:`mongod` or :program:`mongos` process receives a ``SIGUSR1``
-signal from the operating system.
+You can also configure MongoDB to support the Linux/Unix
+logrotate utility
+by setting :setting:`systemLog.logRotate` or
+:option:`--logRotate` to ``reopen``. With ``reopen``, :program:`mongod`
+or :program:`mongos` closes the log file, and
+then reopens a log file with the same name, expecting that another
+process renamed the file prior to rotation.
 
-Alternately, you may configure mongod to send log data to ``syslog``. In
-this case, you can take advantage of alternate logrotation tools.
+Finally, you can configure :program:`mongod` to send log data to the
+``syslog``. using the :option:`--syslog` option. In this case, you can
+take advantage of alternate logrotation tools.
 
 .. seealso:: For information on logging, see the
    :ref:`monitoring-standard-loggging` section.
 
-Log Rotation With MongoDB
--------------------------
-
-The following steps create and rotate a log file:
-
-1. Start a :program:`mongod` with verbose logging, with appending
-   enabled, and with the following log file:
-
-   .. code-block:: javascript
-
-      mongod -v --logpath /var/log/mongodb/server1.log --logappend
-
-#. In a separate terminal, list the matching files:
-
-   .. code-block:: javascript
-
-      ls /var/log/mongodb/server1.log*
-
-   For results, you get:
-
-   .. code-block:: javascript
+Default Log Rotation Behavior
+-----------------------------
 
-      server1.log
+By default, MongoDB uses the
+:option:`--logRotate rename <--logRotate>` behavior. 
+With ``rename``, :program:`mongod` or
+:program:`mongos` renames the current log file by appending a UTC 
+timestamp to the filename, opens a new log file, closes the old log file,
+and sends all new log entries to the new log file.
 
-#. Rotate the log file using *one* of the following methods.
+.. include:: /includes/steps/log-rotate-rename.rst
 
-   - From the :program:`mongo` shell, issue the :dbcommand:`logRotate`
-     command from the ``admin`` database:
+Log Rotation with ``--logRotate reopen``
+----------------------------------------
 
-     .. code-block:: javascript
+.. versionadded:: 3.0.0
 
-        use admin
-        db.runCommand( { logRotate : 1 } )
+Log rotation with :option:`--logRotate reopen <--logRotate>` closes and opens
+the log file following the typical Linux/Unix log rotate behavior.
 
-     This is the only available method to rotate log files on
-     Windows systems.
-
-   - For Linux systems, rotate logs for a single process by issuing
-     the following command:
-
-     .. code-block:: javascript
-
-        kill -SIGUSR1 <mongod process id>
-
-#. List the matching files again:
-
-   .. code-block:: javascript
-
-      ls /var/log/mongodb/server1.log*
-
-   For results you get something similar to the following. The
-   timestamps will be different.
-
-   .. code-block:: none
-
-      server1.log  server1.log.2011-11-24T23-30-00
-
-   The example results indicate a log rotation performed at exactly
-   ``11:30 pm`` on ``November 24th, 2011 UTC``, which is the local time
-   offset by the local time zone. The original log file is the one with
-   the timestamp. The new log is ``server1.log`` file.
-
-   If you issue a second :dbcommand:`logRotate` command an hour later,
-   then an additional file would appear when listing matching files,
-   as in the following example:
-
-   .. code-block:: none
-
-      server1.log  server1.log.2011-11-24T23-30-00  server1.log.2011-11-25T00-30-00
-
-   This operation does not modify the
-   ``server1.log.2011-11-24T23-30-00`` file created earlier, while
-   ``server1.log.2011-11-25T00-30-00`` is the previous ``server1.log``
-   file, renamed. ``server1.log`` is a new, empty file that receives
-   all new log output.
+.. include:: /includes/steps/log-rotate-reopen.rst
 
 Syslog Log Rotation
 -------------------
 
 .. versionadded:: 2.2
 
-To configure mongod to send log data to syslog rather than writing log
-data to a file, use the following procedure.
+With syslog log rotation, :program:`mongod` sends log data to the syslog
+rather than writing it to a file.
+
+.. include:: /includes/steps/log-rotate-syslog.rst
+
+Forcing a Log Rotation with ``SIGUSR1``
+---------------------------------------
 
-1. Start a :program:`mongod` with the :setting:`~systemLog.syslogFacility` option.
+For Linux and Unix-based systems, you can use the ``SIGURS1`` signal
+to rotate the logs for a single process, as in the following:
 
-#. Store and rotate the log output using your system's default log
-   rotation mechanism.
+.. code-block:: sh
 
-.. important:: You cannot use :setting:`~systemLog.syslogFacility` with :setting:`systemLog.path`.
+   kill -SIGUSR1 <mongod process id>