From c7bc0c0fa6cd561b2346ab6e6bc580ac94e7d955 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 13 Dec 2012 15:35:34 -0500 Subject: [PATCH 1/4] DOCS-691 logging --- source/administration/monitoring.txt | 22 ++++++ source/tutorial/rotate-the-log-file.txt | 92 +++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 source/tutorial/rotate-the-log-file.txt diff --git a/source/administration/monitoring.txt b/source/administration/monitoring.txt index b9c0bc4e363..399de6e935a 100644 --- a/source/administration/monitoring.txt +++ b/source/administration/monitoring.txt @@ -144,6 +144,28 @@ this includes a count of the objects in the collection, the size of the collection, the amount of disk space used by the collection, and information about the indexes. +Stdout +~~~~~~ + +MongoDB outputs important information to stdout while its running. The +following command line options provide ways to access and control this +output: + +- :option:`--quiet `. Limits the amount of output. + +- ``-v``. Produces more verbose output. Use more ``v``'s (such as + ``-vvvvvv``) for higher levels of verbosity. To change the logging + verbosity on a running instance, you can use the + :dbcommand:`setParameter` command. + +- :option:`--logpath [file] `. Outputs to a log file + instead of stdout. + +- :dbcommand:`getLog`. Returns a document with a ``log`` array that + contains recent messages from the :program:`mongod` process log. + +To rotate logs, see :doc:`/tutorial/rotate-the-log-file`. + Third Party Tools ~~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/rotate-the-log-file.txt b/source/tutorial/rotate-the-log-file.txt new file mode 100644 index 00000000000..d90a18b1eb7 --- /dev/null +++ b/source/tutorial/rotate-the-log-file.txt @@ -0,0 +1,92 @@ +=================== +Rotate the Log File +=================== + +.. default-domain:: mongodb + +Log file rotation renames the current log file by appending its name +with a timestamp and stops logging to that file. Log file rotation +continues logging to a *new* log file that uses the original name of the +previous log file. The timestamp is the time that the :dbcommand:`logRotate` +command was executed, expressed in UTC (GMT) and formatted as ISO but +with dashes instead of colons for the time portion. + +To view this in action: + +1. Start a :program:`mongod` with verbose logging and with log-file + appending. Use the ``/var/log/mongodb/server1.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 following two commands: + + .. code-block:: javascript + + use admin + db.runCommand("logRotate"); + + - From the UNIX shell, rotate logs for a single process by issuing + the following command: + + .. code-block:: javascript + + kill -SIGUSR1 + + - 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 + + .. versionchanged:: 2.0.3 + + - 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:: javascript + + 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:: javascript + + 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. From 3c0822707c4772319bd5016ae9f5153ce33aecda Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 13 Dec 2012 15:41:08 -0500 Subject: [PATCH 2/4] DOCS-691 moved a section higher with monitoring doc --- source/administration/monitoring.txt | 44 ++++++++++++++-------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/source/administration/monitoring.txt b/source/administration/monitoring.txt index 399de6e935a..5fde7243316 100644 --- a/source/administration/monitoring.txt +++ b/source/administration/monitoring.txt @@ -25,6 +25,28 @@ sharded clusters. `MMS documentation `_ for more information. +Stdout +------ + +MongoDB outputs important information to stdout while its running. The +following command line options provide ways to access and control this +output: + +- :option:`--quiet `. Limits the amount of output. + +- ``-v``. Produces more verbose output. Use more ``v``'s (such as + ``-vvvvvv``) for higher levels of verbosity. To change the logging + verbosity on a running instance, you can use the + :dbcommand:`setParameter` command. + +- :option:`--logpath [file] `. Outputs to a log file + instead of stdout. + +- :dbcommand:`getLog`. Returns a document with a ``log`` array that + contains recent messages from the :program:`mongod` process log. + +To rotate logs, see :doc:`/tutorial/rotate-the-log-file`. + Monitoring Tools ---------------- @@ -144,28 +166,6 @@ this includes a count of the objects in the collection, the size of the collection, the amount of disk space used by the collection, and information about the indexes. -Stdout -~~~~~~ - -MongoDB outputs important information to stdout while its running. The -following command line options provide ways to access and control this -output: - -- :option:`--quiet `. Limits the amount of output. - -- ``-v``. Produces more verbose output. Use more ``v``'s (such as - ``-vvvvvv``) for higher levels of verbosity. To change the logging - verbosity on a running instance, you can use the - :dbcommand:`setParameter` command. - -- :option:`--logpath [file] `. Outputs to a log file - instead of stdout. - -- :dbcommand:`getLog`. Returns a document with a ``log`` array that - contains recent messages from the :program:`mongod` process log. - -To rotate logs, see :doc:`/tutorial/rotate-the-log-file`. - Third Party Tools ~~~~~~~~~~~~~~~~~ From 7e183f4242226d86c5dddd0e3006060a2fa0bf4b Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 14 Dec 2012 13:19:51 -0500 Subject: [PATCH 3/4] DOCS-691 review edits --- source/administration/monitoring.txt | 28 ++++++++++++---------- source/tutorial/rotate-the-log-file.txt | 32 ++++++++++++------------- 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/source/administration/monitoring.txt b/source/administration/monitoring.txt index 5fde7243316..f6b54f0b1bd 100644 --- a/source/administration/monitoring.txt +++ b/source/administration/monitoring.txt @@ -25,27 +25,31 @@ sharded clusters. `MMS documentation `_ for more information. -Stdout ------- +.. _monitoring-standard-loggging: -MongoDB outputs important information to stdout while its running. The -following command line options provide ways to access and control this -output: +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 `. Limits the amount of output. -- ``-v``. Produces more verbose output. Use more ``v``'s (such as - ``-vvvvvv``) for higher levels of verbosity. To change the logging +- :option:`-v `. Produces more verbose output. Use more ``v``'s (such as + :option:`-vvvvv `) for higher levels of verbosity. To change the logging verbosity on a running instance, you can use the :dbcommand:`setParameter` command. -- :option:`--logpath [file] `. Outputs to a log file - instead of stdout. +- :option:`--logpath `. Outputs to a log file instead + of standard output. You must specify the file. + +- :option:`--logappend `. Adds information to a log + file instead of overwriting the file. -- :dbcommand:`getLog`. Returns a document with a ``log`` array that - contains recent messages from the :program:`mongod` process log. +- :dbcommand:`getLog`. Displays recent messages from the :program:`mongod` process log. -To rotate logs, see :doc:`/tutorial/rotate-the-log-file`. +- :dbcommand:`logRotate`. Rotates the log files. See :doc:`/tutorial/rotate-the-log-file`. Monitoring Tools ---------------- diff --git a/source/tutorial/rotate-the-log-file.txt b/source/tutorial/rotate-the-log-file.txt index d90a18b1eb7..d436a618594 100644 --- a/source/tutorial/rotate-the-log-file.txt +++ b/source/tutorial/rotate-the-log-file.txt @@ -4,17 +4,18 @@ Rotate the Log File .. default-domain:: mongodb -Log file rotation renames the current log file by appending its name -with a timestamp and stops logging to that file. Log file rotation -continues logging to a *new* log file that uses the original name of the -previous log file. The timestamp is the time that the :dbcommand:`logRotate` -command was executed, expressed in UTC (GMT) and formatted as ISO but -with dashes instead of colons for the time portion. +Log rotation archives the current log file and starts a new log. Log +rotation archives the current log and appends the file name with a +timestamp. The timestamp is expressed in UTC (GMT) and formatted as ISO, +using dashes instead of colons. MongoDB continues logging in a *new* +file that uses the original name of the archived file. Log rotation +occurs when the :program:`mongod` ends or explicitly by command. For +more information on logging, see :ref:`monitoring-standard-loggging`. -To view this in action: +As an example, the following steps will create and rotate a log file: -1. Start a :program:`mongod` with verbose logging and with log-file - appending. Use the ``/var/log/mongodb/server1.log`` file: +1. Start a :program:`mongod` with verbose logging, with appending + enabled, and with the following log file: .. code-block:: javascript @@ -34,12 +35,13 @@ To view this in action: #. Rotate the log file using *one* of the following methods. - - From the :program:`mongo` shell, issue the following two commands: + - From the :program:`mongo` shell, issue the :dbcommand:`logRotate` + command from the ``admin`` database: .. code-block:: javascript use admin - db.runCommand("logRotate"); + db.runCommand( { logRotate : 1 } ) - From the UNIX shell, rotate logs for a single process by issuing the following command: @@ -55,8 +57,6 @@ To view this in action: killall -SIGUSR1 mongod - .. versionchanged:: 2.0.3 - - On Windows, use the :program:`mongo` shell from the Windows command line by using a JavaScript command file to issue the :dbcommand:`logRotate` command. @@ -70,19 +70,19 @@ To view this in action: For results you get something similar to the following. The timestamps will be different. - .. code-block:: javascript + .. 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. + 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:: javascript + .. code-block:: none server1.log server1.log.2011-11-24T23-30-00 server1.log.2011-11-25T00-30-00 From c3b2c78450364627ddeb8089be4bf4014fdc437b Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 18 Dec 2012 12:14:38 -0500 Subject: [PATCH 4/4] DOCS-691 review edits --- source/tutorial/rotate-the-log-file.txt | 112 ++++++++++++------------ 1 file changed, 58 insertions(+), 54 deletions(-) diff --git a/source/tutorial/rotate-the-log-file.txt b/source/tutorial/rotate-the-log-file.txt index d436a618594..ddfd269ceba 100644 --- a/source/tutorial/rotate-the-log-file.txt +++ b/source/tutorial/rotate-the-log-file.txt @@ -4,89 +4,93 @@ Rotate the Log File .. default-domain:: mongodb -Log rotation archives the current log file and starts a new log. Log -rotation archives the current log and appends the file name with a -timestamp. The timestamp is expressed in UTC (GMT) and formatted as ISO, -using dashes instead of colons. MongoDB continues logging in a *new* -file that uses the original name of the archived file. Log rotation -occurs when the :program:`mongod` ends or explicitly by command. For -more information on logging, see :ref:`monitoring-standard-loggging`. +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`. -As an example, the following steps will create and rotate a log file: +Log rotation occurs when you issue :dbcommand:`logRotate` or when the +:program:`mongod` process ends. -1. Start a :program:`mongod` with verbose logging, with appending - enabled, and with the following log file: +For information on logging, see :ref:`monitoring-standard-loggging`. - .. code-block:: javascript +.. example:: The following steps create and rotate a log file: - mongod -v --logpath /var/log/mongodb/server1.log --logappend + 1. Start a :program:`mongod` with verbose logging, with appending + enabled, and with the following log file: -#. In a separate terminal, list the matching files: + .. code-block:: javascript - .. code-block:: javascript + mongod -v --logpath /var/log/mongodb/server1.log --logappend - ls /var/log/mongodb/server1.log* + #. In a separate terminal, list the matching files: - For results, you get: + .. code-block:: javascript - .. code-block:: javascript + ls /var/log/mongodb/server1.log* - server1.log + For results, you get: -#. Rotate the log file using *one* of the following methods. + .. code-block:: javascript - - From the :program:`mongo` shell, issue the :dbcommand:`logRotate` - command from the ``admin`` database: + server1.log - .. code-block:: javascript + #. Rotate the log file using *one* of the following methods. - use admin - db.runCommand( { logRotate : 1 } ) + - From the :program:`mongo` shell, issue the :dbcommand:`logRotate` + command from the ``admin`` database: - - From the UNIX shell, rotate logs for a single process by issuing - the following command: + .. code-block:: javascript - .. code-block:: javascript + use admin + db.runCommand( { logRotate : 1 } ) - kill -SIGUSR1 + - From the UNIX shell, rotate logs for a single process by issuing + the following command: - - From the UNIX shell, rotate logs for all :program:`mongod` - processes on a machine by issuing the following command: + .. code-block:: javascript - .. code-block:: javascript + kill -SIGUSR1 - killall -SIGUSR1 mongod + - From the UNIX shell, rotate logs for all :program:`mongod` + processes on a machine by issuing the following command: - - On Windows, use the :program:`mongo` shell from the Windows command - line by using a JavaScript command file to issue the - :dbcommand:`logRotate` command. + .. code-block:: javascript -#. List the matching files again: + killall -SIGUSR1 mongod - .. code-block:: javascript + - On Windows, use the :program:`mongo` shell from the Windows command + line by using a JavaScript command file to issue the + :dbcommand:`logRotate` command. - ls /var/log/mongodb/server1.log* + #. List the matching files again: - For results you get something similar to the following. The - timestamps will be different. + .. code-block:: javascript - .. code-block:: none + ls /var/log/mongodb/server1.log* - server1.log server1.log.2011-11-24T23-30-00 + For results you get something similar to the following. The + timestamps will be different. - 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. + .. code-block:: none - If another logRotate command were given an hour later, then an additional - file would appear when listing matching files, as in the following example: + server1.log server1.log.2011-11-24T23-30-00 - .. code-block:: none + 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. - server1.log server1.log.2011-11-24T23-30-00 server1.log.2011-11-25T00-30-00 + If another logRotate command were given an hour later, then an additional + file would appear when listing matching files, as in the following example: - 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. + .. 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. + \ No newline at end of file