From 1b93bf734035a39920557c659a8f2c5d1a86a02a Mon Sep 17 00:00:00 2001 From: Allison Moore Date: Wed, 11 Feb 2015 11:54:58 -0500 Subject: [PATCH] DOCS-2315: updates log rotate tutorial with new steps && new behaviors DOCS-2315: fixes connection string syntax DOCS-2315: adds blurb about rename to rename tutorial intro --- source/includes/steps-log-rotate-rename.yaml | 55 ++++++++ source/includes/steps-log-rotate-reopen.yaml | 24 ++++ source/includes/steps-log-rotate-syslog.yaml | 23 ++++ source/tutorial/rotate-log-files.txt | 129 +++++++------------ 4 files changed, 148 insertions(+), 83 deletions(-) create mode 100644 source/includes/steps-log-rotate-rename.yaml create mode 100644 source/includes/steps-log-rotate-reopen.yaml create mode 100644 source/includes/steps-log-rotate-syslog.yaml diff --git a/source/includes/steps-log-rotate-rename.yaml b/source/includes/steps-log-rotate-rename.yaml new file mode 100644 index 00000000000..a5daaa677e1 --- /dev/null +++ b/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.``, 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. +... diff --git a/source/includes/steps-log-rotate-reopen.yaml b/source/includes/steps-log-rotate-reopen.yaml new file mode 100644 index 00000000000..2e11cf469aa --- /dev/null +++ b/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. +... \ No newline at end of file diff --git a/source/includes/steps-log-rotate-syslog.yaml b/source/includes/steps-log-rotate-syslog.yaml new file mode 100644 index 00000000000..bda228d481b --- /dev/null +++ b/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. +... \ No newline at end of file diff --git a/source/tutorial/rotate-log-files.txt b/source/tutorial/rotate-log-files.txt index 57a70efe527..d7a34305a0f 100644 --- a/source/tutorial/rotate-log-files.txt +++ b/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 - -#. 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