Skip to content

Commit f2d44b2

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 04d0d9c commit f2d44b2

File tree

4 files changed

+148
-82
lines changed

4 files changed

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

‎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: 47 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -7,111 +7,76 @@ 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+
With the :option:`--syslog` option, :program:`mongod` and :program:`mongos`
26+
report all activity to the ``syslog`` rather than a log file.
2127

22-
Alternately, you may configure mongod to send log data to ``syslog``. In
28+
You can also configure MongoDB to support the Linux/Unix
29+
logrotate utility
30+
by setting :setting:`systemLog.logRotate` or
31+
:option:`--logRotate` to ``reopen``. With ``reopen``, :program:`mongod`
32+
or :program:`mongos` closes the log file, and
33+
then reopens a log file with the same name, expecting that another
34+
process renamed the file prior to rotation.
35+
36+
Finally, you can configure :program:`mongod` to send log data to the ``syslog``. In
2337
this case, you can take advantage of alternate logrotation tools.
2438

2539
.. seealso:: For information on logging, see the
2640
:ref:`monitoring-standard-loggging` section.
2741

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
42+
Default Log Rotation Behavior
43+
-----------------------------
4944

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

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

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

57-
.. code-block:: javascript
57+
.. versionadded:: 3.0.0
5858

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

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.
62+
.. include:: /includes/steps/log-rotate-reopen.rst
10363

10464
Syslog Log Rotation
10565
-------------------
10666

10767
.. versionadded:: 2.2
10868

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

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

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

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

0 commit comments

Comments
 (0)