Skip to content

Commit cddbf5a

Browse files
schmallisoschmalliso
committed
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
1 parent cc75963 commit cddbf5a

File tree

4 files changed

+148
-83
lines changed

4 files changed

+148
-83
lines changed

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

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

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

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

‎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: 46 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -7,111 +7,74 @@ Rotate Log Files
77
Overview
88
--------
99

10-
Log rotation using MongoDB's standard approach archives the current
10+
When used with the :option:`--logpath` option or :setting:`systemLog.logPath` setting,
11+
:program:`mongod` and :program:`mongos` instances report
12+
a live account of all activity and operations to a log file.
13+
When reporting activity data to a log file, by default, MongoDB only rotates logs
14+
in response to the :dbcommand:`logRotate` command, or when the
15+
:program:`mongod` or :program:`mongos` process receives a ``SIGUSR1``
16+
signal from the operating system.
17+
18+
MongoDB's standard log rotation approach archives the current
1119
log file and starts a new one. To do this, the :program:`mongod` or
1220
:program:`mongos` instance renames the current log file by appending a
13-
UTC (GMT) timestamp to the filename, in :term:`ISODate` format. It then
21+
UTC timestamp to the filename, in :term:`ISODate` format. It then
1422
opens a new log file, closes the old log file, and sends all new log
1523
entries to the new log file.
1624

17-
MongoDB's standard approach to log rotation only rotates logs
18-
in response to the :dbcommand:`logRotate` command, or when the
19-
:program:`mongod` or :program:`mongos` process receives a ``SIGUSR1``
20-
signal from the operating system.
25+
You can also configure MongoDB to support the Linux/Unix
26+
logrotate utility
27+
by setting :setting:`systemLog.logRotate` or
28+
:option:`--logRotate` to ``reopen``. With ``reopen``, :program:`mongod`
29+
or :program:`mongos` closes the log file, and
30+
then reopens a log file with the same name, expecting that another
31+
process renamed the file prior to rotation.
2132

22-
Alternately, you may configure mongod to send log data to ``syslog``. In
23-
this case, you can take advantage of alternate logrotation tools.
33+
Finally, you can configure :program:`mongod` to send log data to the
34+
``syslog``. using the :option:`--syslog` option. In this case, you can
35+
take advantage of alternate logrotation tools.
2436

2537
.. seealso:: For information on logging, see the
2638
:ref:`monitoring-standard-loggging` section.
2739

28-
Log Rotation With MongoDB
29-
-------------------------
30-
31-
The following steps create and rotate a log file:
32-
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
40+
Default Log Rotation Behavior
41+
-----------------------------
4942

50-
server1.log
43+
By default, MongoDB uses the
44+
:option:`--logRotate rename <--logRotate>` behavior.
45+
With ``rename``, :program:`mongod` or
46+
:program:`mongos` renames the current log file by appending a UTC
47+
timestamp to the filename, opens a new log file, closes the old log file,
48+
and sends all new log entries to the new log file.
5149

52-
#. Rotate the log file using *one* of the following methods.
50+
.. include:: /includes/steps/log-rotate-rename.rst
5351

54-
- From the :program:`mongo` shell, issue the :dbcommand:`logRotate`
55-
command from the ``admin`` database:
52+
Log Rotation with ``--logRotate reopen``
53+
----------------------------------------
5654

57-
.. code-block:: javascript
55+
.. versionadded:: 3.0.0
5856

59-
use admin
60-
db.runCommand( { logRotate : 1 } )
57+
Log rotation with :option:`--logRotate reopen <--logRotate>` closes and opens
58+
the log file following the typical Linux/Unix log rotate behavior.
6159

62-
This is the only available method to rotate log files on
63-
Windows systems.
64-
65-
- For Linux systems, rotate logs for a single process by issuing
66-
the following command:
67-
68-
.. code-block:: javascript
69-
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.
60+
.. include:: /includes/steps/log-rotate-reopen.rst
10361

10462
Syslog Log Rotation
10563
-------------------
10664

10765
.. versionadded:: 2.2
10866

109-
To configure mongod to send log data to syslog rather than writing log
110-
data to a file, use the following procedure.
67+
With syslog log rotation, :program:`mongod` sends log data to the syslog
68+
rather than writing it to a file.
69+
70+
.. include:: /includes/steps/log-rotate-syslog.rst
71+
72+
Forcing a Log Rotation with ``SIGUSR1``
73+
---------------------------------------
11174

112-
1. Start a :program:`mongod` with the :setting:`~systemLog.syslogFacility` option.
75+
For Linux and Unix-based systems, you can use the ``SIGURS1`` signal
76+
to rotate the logs for a single process, as in the following:
11377

114-
#. Store and rotate the log output using your system's default log
115-
rotation mechanism.
78+
.. code-block:: sh
11679

117-
.. important:: You cannot use :setting:`~systemLog.syslogFacility` with :setting:`systemLog.path`.
80+
kill -SIGUSR1 <mongod process id>

0 commit comments

Comments
 (0)