DOCS-691 logging

source/administration/monitoring.txt

@@ -25,6 +25,32 @@ sharded clusters.
    `MMS documentation <http://mms.10gen.com/help/>`_ for more
    information.
 
+.. _monitoring-standard-loggging:
+
+Standard Logging
+----------------
+
+While runnning, a :program:`mongod` instance outputs information to
+standard output. The following command line options provide ways to access and
+control this output:
+
+- :option:`--quiet <mongod --quiet>`. Limits the amount of output.
+
+- :option:`-v <mongod --verbose>`. Produces more verbose output. Use more ``v``'s (such as
+  :option:`-vvvvv <mongod --verbose>`) for higher levels of verbosity. To change the logging
+  verbosity on a running instance, you can use the
+  :dbcommand:`setParameter` command.
+
+- :option:`--logpath <mongod --logpath>`. Outputs to a log file instead
+  of standard output. You must specify the file.
+
+- :option:`--logappend <mongod --logappend>`. Adds information to a log
+  file instead of overwriting the file.
+
+- :dbcommand:`getLog`. Displays recent messages from the :program:`mongod` process log.
+
+- :dbcommand:`logRotate`. Rotates the log files. See :doc:`/tutorial/rotate-the-log-file`.
+
 Monitoring Tools
 ----------------
 

source/tutorial/rotate-the-log-file.txt

@@ -0,0 +1,96 @@
+===================
+Rotate the Log File
+===================
+
+.. default-domain:: mongodb
+
+Log rotation archives the current log file and starts a new one.
+Specifically, log rotation renames the current log file by appending the
+filename with a timestamp, then opens a new log file, and then closes
+the old log. The timestamp is expressed in UTC (GMT) and formatted as
+:term:`ISODate`.
+
+Log rotation occurs when you issue :dbcommand:`logRotate` or when the
+:program:`mongod` process ends.
+
+For information on logging, see :ref:`monitoring-standard-loggging`.
+
+.. example:: 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
+
+         server1.log
+
+   #. Rotate the log file using *one* of the following methods.
+
+      - From the :program:`mongo` shell, issue the :dbcommand:`logRotate`
+        command from the ``admin`` database:
+
+        .. code-block:: javascript
+
+           use admin
+           db.runCommand( { logRotate : 1 } )
+
+      - From the UNIX shell, rotate logs for a single process by issuing
+        the following command:
+
+        .. code-block:: javascript
+
+           kill -SIGUSR1 <mongod process id>
+
+      - From the UNIX shell, rotate logs for all :program:`mongod`
+        processes on a machine by issuing the following command:
+
+        .. code-block:: javascript
+
+           killall -SIGUSR1 mongod
+
+      - On Windows, use the :program:`mongo` shell from the Windows command
+        line by using a JavaScript command file to issue the
+        :dbcommand:`logRotate` command.
+
+   #. 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 another logRotate command were given 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
+
+      The ``server1.log.2011-11-24T23-30-00`` file is unchanged from
+      before, while ``server1.log.2011-11-25T00-30-00`` is the previous
+      ``server1.log`` file, renamed. The ``server1.log`` is the new empty
+      file that will receive new log output.
+