Skip to content

Commit 17b2973

Browse files
schmallisoschmalliso
committed
DOCS-2315: updates log rotate tutorial with new steps && new behaviors
1 parent 819999e commit 17b2973

File tree

4 files changed

+140
-78
lines changed

4 files changed

+140
-78
lines changed

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
stepnum: 1
2+
ref: start-mongod
3+
title: "Start a :program:`mongod` instance, specifying the {{logrotateOption}} :option:`--logRotate` behavior."
4+
replacement:
5+
logrotateOption: "``rename``"
6+
action:
7+
language: sh
8+
code: |
9+
mongod -v --logpath /var/log/mongodb/server1.log --logRotate reopen
10+
---
11+
stepnum: 2
12+
title: List the log files
13+
ref: list-logfiles
14+
pre: |
15+
In a separate terminal, list the matching files:
16+
action:
17+
language: sh
18+
code: |
19+
ls /var/log/mongodb/server1.log*
20+
post: |
21+
The results should include one log file, ``server1.log``.
22+
---
23+
stepnum: 3
24+
ref: rotate-log
25+
title: Rotate the log file.
26+
pre: |
27+
Rotate the log file by issuing the :dbcommand:`logRotate` command
28+
from the ``admin`` database in a :program:`mongo` shell:
29+
action:
30+
language: sh
31+
code: |
32+
use admin
33+
db.runCommand( { logRotate : 1 } )
34+
---
35+
stepnum: 4
36+
ref: list-new-logfiles
37+
title: 'View the new log files'
38+
pre: |
39+
List the new log files to view the newly-created log:
40+
action:
41+
language: sh
42+
code: |
43+
ls /var/log/mongodb/server1.log*
44+
post: |
45+
There should be two log files listed: ``server1.log``, which is the
46+
log file that :program:`mongod` or :program:`mongos` made when it
47+
reopened the log file, and ``server1.log.<timestamp>``, the renamed
48+
original log file.
49+
50+
Rotating log files does not modify the "old" rotated log files. When
51+
you rotate a log, you rename the ``server1.log`` file to include
52+
the timestamp, and a new, empty ``server1.log`` file receives all
53+
new log input.
54+
...

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
stepnum: 1
2+
source:
3+
file: steps-log-rotate-rename.yaml
4+
ref: start-mongod
5+
replacement:
6+
logrotateOption: "``reopen``"
7+
action:
8+
language: sh
9+
code: |
10+
mongod -v --logpath /var/log/mongodb/server1.log --logRotate reopen --logappend
11+
post: |
12+
You must use the :option:`--logappend` option with
13+
:option:`--logRotate` ``reopen``.
14+
---
15+
stepnum: 2
16+
source:
17+
file: steps-log-rotate-rename.yaml
18+
ref: list-logfiles
19+
---
20+
stepnum: 3
21+
source:
22+
file: steps-log-rotate-rename.yaml
23+
ref: rotate-log
24+
post: |
25+
You should rename the log file using an external process, following
26+
the typical Linux/Unix log rotate behavior.
27+
...

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
stepnum: 1
2+
ref: start-mongod-syslog
3+
title: 'Start a :program:`mongod` instance with the :option:`--syslog` option'
4+
action:
5+
language: sh
6+
code: |
7+
mongod --syslog
8+
post: |
9+
Do not include :option:`--logpath`. Since :option:`--syslog` tells
10+
:program:`mongod` to send log data to the syslog, specifying a
11+
:option:`--logpath` will causes an error.
12+
13+
To specify the facility level used when logging messages to the syslog,
14+
use the :option:`--syslogFacility` option or
15+
:setting:`systemLog.syslogFacility` configuration setting.
16+
---
17+
stepnum: 2
18+
ref: rotate-log-syslog
19+
title: Rotate the log.
20+
pre: |
21+
Store and rotate the log output using your systems default log
22+
rotation mechanism.
23+
...

‎source/tutorial/rotate-log-files.txt

Lines changed: 36 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -7,111 +7,69 @@ Rotate Log Files
77
Overview
88
--------
99

10-
Log rotation using MongoDB's standard approach archives the current
10+
During normal operation :program:`mongod` and :program:`mongos` report
11+
a live account of all activity and operations to a log file.
12+
When the log file reaches its limits, the system must replace or
13+
rotate the log file.
14+
15+
MongoDB's standard log rotation approach archives the current
1116
log file and starts a new one. To do this, the :program:`mongod` or
1217
:program:`mongos` instance renames the current log file by appending a
13-
UTC (GMT) timestamp to the filename, in :term:`ISODate` format. It then
18+
UTC timestamp to the filename, in :term:`ISODate` format. It then
1419
opens a new log file, closes the old log file, and sends all new log
1520
entries to the new log file.
1621

17-
MongoDB's standard approach to log rotation only rotates logs
22+
Alternatively, you can configure MongoDB to use the standard Linux/Unix
23+
log rotate behavior by setting :setting:`systemLog.logRotate` or
24+
:option:`--logRotate` to ``reopen``. With ``reopen``, :program:`mongod`
25+
or :program:`mongos` closes the log file, and
26+
then reopens a log file with the same name, expecting that another
27+
process renamed the file prior to rotation.
28+
29+
Finally, you can configure :program:`mongod` to send log data to the ``syslog``. In
30+
this case, you can take advantage of alternate logrotation tools.
31+
32+
By default, MongoDB only rotates logs
1833
in response to the :dbcommand:`logRotate` command, or when the
1934
:program:`mongod` or :program:`mongos` process receives a ``SIGUSR1``
2035
signal from the operating system.
2136

22-
Alternately, you may configure mongod to send log data to ``syslog``. In
23-
this case, you can take advantage of alternate logrotation tools.
24-
2537
.. seealso:: For information on logging, see the
2638
:ref:`monitoring-standard-loggging` section.
2739

28-
Log Rotation With MongoDB
29-
-------------------------
40+
Log Rotation with ``--logRotate rename``
41+
----------------------------------------
3042

3143
The following steps create and rotate a log file:
3244

33-
1. Start a :program:`mongod` with verbose logging, with appending
34-
enabled, and with the following log file:
35-
36-
.. code-block:: javascript
37-
38-
mongod -v --logpath /var/log/mongodb/server1.log --logappend
39-
40-
#. In a separate terminal, list the matching files:
41-
42-
.. code-block:: javascript
43-
44-
ls /var/log/mongodb/server1.log*
45-
46-
For results, you get:
47-
48-
.. code-block:: javascript
49-
50-
server1.log
45+
.. include:: /includes/steps/log-rotate-rename.rst
5146

52-
#. Rotate the log file using *one* of the following methods.
47+
Log Rotation with ``--logRotate reopen``
48+
----------------------------------------
5349

54-
- From the :program:`mongo` shell, issue the :dbcommand:`logRotate`
55-
command from the ``admin`` database:
50+
.. versionadded:: 3.0.0
5651

57-
.. code-block:: javascript
52+
Log rotation with :option:`--logRotate` ``reopen`` closes and opens
53+
the log file following the typical Linux/Unix log rotate behavior.
5854

59-
use admin
60-
db.runCommand( { logRotate : 1 } )
55+
.. include:: /includes/steps/log-rotate-reopen.rst
6156

62-
This is the only available method to rotate log files on
63-
Windows systems.
57+
Log Rotation with ``SIGUSR1``
58+
-----------------------------
6459

65-
- For Linux systems, rotate logs for a single process by issuing
66-
the following command:
60+
For Linux and Unix-based systems, you can use the ``SIGURS1`` signal
61+
to rotate the logs for a single process, as in the following:
6762

68-
.. code-block:: javascript
63+
.. code-block:: sh
6964

70-
kill -SIGUSR1 <mongod process id>
71-
72-
#. List the matching files again:
73-
74-
.. code-block:: javascript
75-
76-
ls /var/log/mongodb/server1.log*
77-
78-
For results you get something similar to the following. The
79-
timestamps will be different.
80-
81-
.. code-block:: none
82-
83-
server1.log server1.log.2011-11-24T23-30-00
84-
85-
The example results indicate a log rotation performed at exactly
86-
``11:30 pm`` on ``November 24th, 2011 UTC``, which is the local time
87-
offset by the local time zone. The original log file is the one with
88-
the timestamp. The new log is ``server1.log`` file.
89-
90-
If you issue a second :dbcommand:`logRotate` command an hour later,
91-
then an additional file would appear when listing matching files,
92-
as in the following example:
93-
94-
.. code-block:: none
95-
96-
server1.log server1.log.2011-11-24T23-30-00 server1.log.2011-11-25T00-30-00
97-
98-
This operation does not modify the
99-
``server1.log.2011-11-24T23-30-00`` file created earlier, while
100-
``server1.log.2011-11-25T00-30-00`` is the previous ``server1.log``
101-
file, renamed. ``server1.log`` is a new, empty file that receives
102-
all new log output.
65+
kill -SIGUSR1 <mongod process id>
10366

10467
Syslog Log Rotation
10568
-------------------
10669

10770
.. versionadded:: 2.2
10871

109-
To configure mongod to send log data to syslog rather than writing log
110-
data to a file, use the following procedure.
111-
112-
1. Start a :program:`mongod` with the :setting:`~systemLog.syslogFacility` option.
113-
114-
#. Store and rotate the log output using your system's default log
115-
rotation mechanism.
72+
With syslog log rotation, :program:`mongod` sends log data to the syslog
73+
rather than writing it to a file.
11674

117-
.. important:: You cannot use :setting:`~systemLog.syslogFacility` with :setting:`systemLog.path`.
75+
.. include:: /includes/steps/log-rotate-syslog.rst

0 commit comments

Comments
 (0)