Skip to content

Commit 6dc2447

Browse files
andreyaksenovandreyaksenov
committed
Document logging configuration
Resolves #1974
1 parent 2acf88e commit 6dc2447

File tree

3 files changed

+87
-83
lines changed

3 files changed

+87
-83
lines changed

‎doc/reference/configuration/cfg_feedback.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. _cfg_feedback:
2+
3+
* :ref:`feedback_enabled <cfg_logging-feedback_enabled>`
4+
* :ref:`feedback_host <cfg_logging-feedback_host>`
5+
* :ref:`feedback_interval <cfg_logging-feedback_interval>`
6+
7+
By default, a Tarantool daemon sends a small packet
8+
once per hour, to ``https://feedback.tarantool.io``.
9+
The packet contains three values from :ref:`box.info <box_introspection-box_info>`:
10+
``box.info.version``, ``box.info.uuid``, and ``box.info.cluster_uuid``.
11+
By changing the feedback configuration parameters, users can
12+
adjust or turn off this feature.
13+
14+
.. _cfg_logging-feedback_enabled:
15+
16+
.. confval:: feedback_enabled
17+
18+
Since version 1.10.1. Whether to send feedback.
19+
20+
If this is set to ``true``, feedback will be sent as described above.
21+
If this is set to ``false``, no feedback will be sent.
22+
23+
| Type: boolean
24+
| Default: true
25+
| Environment variable: TT_FEEDBACK_ENABLED
26+
| Dynamic: **yes**
27+
28+
.. _cfg_logging-feedback_host:
29+
30+
.. confval:: feedback_host
31+
32+
Since version 1.10.1. The address to which the packet is sent.
33+
Usually the recipient is Tarantool, but it can be any URL.
34+
35+
| Type: string
36+
| Default: ``https://feedback.tarantool.io``
37+
| Environment variable: TT_FEEDBACK_HOST
38+
| Dynamic: **yes**
39+
40+
.. _cfg_logging-feedback_interval:
41+
42+
.. confval:: feedback_interval
43+
44+
Since version 1.10.1. The number of seconds between sendings, usually 3600 (1 hour).
45+
46+
| Type: float
47+
| Default: 3600
48+
| Environment variable: TT_FEEDBACK_INTERVAL
49+
| Dynamic: **yes**

‎doc/reference/configuration/cfg_logging.rst

Lines changed: 33 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
.. confval:: log_level
1212

1313
Since version 1.6.2.
14-
What level of detail the :ref:`log <admin-logs>` will have. There are seven levels:
14+
Specifies the level of detail the :ref:`log <admin-logs>` has. There are seven levels:
1515

1616
* 1 – ``SYSERROR``
1717
* 2 – ``ERROR``
@@ -21,7 +21,7 @@
2121
* 6 – ``VERBOSE``
2222
* 7 – ``DEBUG``
2323

24-
By setting log_level, one can enable logging of all classes below
24+
By setting ``log_level``, you can enable logging of all classes below
2525
or equal to the given level. Tarantool prints its logs to the standard
2626
error stream by default, but this can be changed with the
2727
:ref:`log <cfg_logging-log>` configuration parameter.
@@ -32,7 +32,7 @@
3232
| Dynamic: **yes**
3333
3434
Warning: prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was
35-
level 6. Starting with Tarantool 1.7.5 ``VERBOSE`` is level 6 and ``DEBUG`` is level 7.
35+
level 6. Starting with Tarantool 1.7.5, ``VERBOSE`` is level 6 and ``DEBUG`` is level 7.
3636
``VERBOSE`` is a new level for monitoring repetitive events which would cause
3737
too much log writing if ``INFO`` were used instead.
3838

@@ -42,36 +42,41 @@
4242

4343
Since version 1.7.4.
4444
By default, Tarantool sends the log to the standard error stream
45-
(``stderr``). If ``log`` is specified, Tarantool sends the log to a file,
46-
or to a pipe, or to the system logger.
45+
(``stderr``). If ``log`` is specified, Tarantool can send the log to ...
4746

48-
Example setting for sending the log to a file:
47+
* a file;
48+
49+
* a pipe;
50+
51+
* the system logger.
52+
53+
The example below shows how to send the log to the ``tarantool.log`` file:
4954

5055
.. code-block:: lua
5156
5257
box.cfg{log = 'tarantool.log'}
5358
-- or
5459
box.cfg{log = 'file:tarantool.log'}
5560
56-
This will open the file ``tarantool.log`` for output on the server’s default
61+
This opens the file ``tarantool.log`` for output on the server's default
5762
directory. If the ``log`` string has no prefix or has the prefix "file:",
5863
then the string is interpreted as a file path.
5964

60-
Example setting for sending the log to a pipe:
65+
The example below shows how to send the log to a pipe:
6166

6267
.. code-block:: lua
6368
6469
box.cfg{log = '| cronolog tarantool.log'}
6570
-- or
66-
box.cfg{log = 'pipe: cronolog tarantool.log'}'
71+
box.cfg{log = 'pipe: cronolog tarantool.log'}
6772
68-
This will start the program `cronolog <https://linux.die.net/man/1/cronolog>`_ when the server starts, and
69-
will send all log messages to the standard input (``stdin``) of cronolog.
73+
This starts the program `cronolog <https://linux.die.net/man/1/cronolog>`_ when the server starts, and
74+
sends all log messages to the standard input (``stdin``) of ``cronolog``.
7075
If the ``log`` string begins with '|' or has the prefix "pipe:",
7176
then the string is interpreted as a Unix
7277
`pipeline <https://en.wikipedia.org/wiki/Pipeline_%28Unix%29>`_.
7378
74-
Example setting for sending the log to syslog:
79+
The example below shows how to send the log to syslog:
7580

7681
.. code-block:: lua
7782
@@ -85,29 +90,28 @@
8590
8691
If the ``log`` string begins with "syslog:", then it is
8792
interpreted as a message for the
88-
`syslogd <http://www.rfc-base.org/txt/rfc-5424.txt>`_ program which normally
89-
is running in the background of any Unix-like platform.
93+
`syslogd <https://linux.die.net/man/8/syslogd>`_ program, which normally
94+
is running in the background on any Unix-like platform.
9095
The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...',
9196
'syslog:server=...', or a combination.
9297

93-
The ``syslog:identity`` setting is an arbitrary string which will be placed at
94-
the beginning of all messages. The default value is: tarantool.
98+
* The ``syslog:identity`` setting is an arbitrary string which will be placed at
99+
the beginning of all messages. The default value is: tarantool.
95100

96-
The ``syslog:facility`` setting is currently ignored but will be used in the future.
97-
The value must be one of the `syslog <https://en.wikipedia.org/wiki/Syslog>`_
98-
keywords, which tell syslogd where the message should go.
99-
The possible values are: auth, authpriv, cron, daemon, ftp,
100-
kern, lpr, mail, news, security, syslog, user, uucp, local0, local1, local2,
101-
local3, local4, local5, local6, local7. The default value is: local7.
101+
* The ``syslog:facility`` setting is currently ignored but will be used in the future.
102+
The value must be one of the `syslog <https://en.wikipedia.org/wiki/Syslog>`_
103+
keywords, which tell syslogd where the message should go.
104+
The possible values are: auth, authpriv, cron, daemon, ftp,
105+
kern, lpr, mail, news, security, syslog, user, uucp, local0, local1, local2,
106+
local3, local4, local5, local6, local7. The default value is: local7.
102107

103-
The ``syslog:server`` setting is the locator for the syslog server.
104-
It can be a Unix socket path beginning with "unix:", or an ipv4 port number.
105-
The default socket value is: dev/log (on Linux) or /var/run/syslog (on Mac OS).
106-
The default port value is: 514, the UDP port.
108+
* The ``syslog:server`` setting is the locator for the syslog server.
109+
It can be a Unix socket path beginning with "unix:", or an ipv4 port number.
110+
The default socket value is: dev/log (on Linux) or /var/run/syslog (on Mac OS).
111+
The default port value is: 514, the UDP port.
107112

108113
When logging to a file, Tarantool reopens the log on `SIGHUP <https://en.wikipedia.org/wiki/SIGHUP>`_.
109-
When log is
110-
a program, its pid is saved in the :ref:`log.logger_pid <log-logger_pid>`
114+
When log is a program, its PID is saved in the :ref:`log.logger_pid <log-logger_pid>`
111115
variable. You need to send it a signal to rotate logs.
112116

113117
| Type: string
@@ -128,8 +132,6 @@
128132

129133
This parameter has effect only if the output is going to "syslog:" or
130134
"pipe:".
131-
Setting ``log_nonblock`` to true is illegal if the output is going to
132-
a file.
133135

134136
The default ``log_nonblock`` value is nil, which means that
135137
blocking behavior corresponds to the type of logger.
@@ -205,7 +207,7 @@
205207
Logging example
206208
*********************
207209

208-
This will illustrate how "rotation" works, that is, what happens when the server
210+
This example illustrates how "rotation" works, that is, what happens when the server
209211
instance is writing to a log and signals are used when archiving it.
210212

211213
Start with two terminal shells, Terminal #1 and Terminal #2.
@@ -272,55 +274,3 @@ and `Log_file` will have
272274
273275
log file has been reopened
274276
2015-11-30 15:15:32.629 [27469] main/101/interactive I> Log Line #3
275-
276-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
277-
Feedback
278-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
279-
280-
* :ref:`feedback_enabled <cfg_logging-feedback_enabled>`
281-
* :ref:`feedback_host <cfg_logging-feedback_host>`
282-
* :ref:`feedback_interval <cfg_logging-feedback_interval>`
283-
284-
By default a Tarantool daemon sends a small packet
285-
once per hour, to ``https://feedback.tarantool.io``.
286-
The packet contains three values from :ref:`box.info <box_introspection-box_info>`:
287-
``box.info.version``, ``box.info.uuid``, and ``box.info.cluster_uuid``.
288-
By changing the feedback configuration parameters, users can
289-
adjust or turn off this feature.
290-
291-
.. _cfg_logging-feedback_enabled:
292-
293-
.. confval:: feedback_enabled
294-
295-
Since version 1.10.1. Whether to send feedback.
296-
297-
If this is set to ``true``, feedback will be sent as described above.
298-
If this is set to ``false``, no feedback will be sent.
299-
300-
| Type: boolean
301-
| Default: true
302-
| Environment variable: TT_FEEDBACK_ENABLED
303-
| Dynamic: **yes**
304-
305-
.. _cfg_logging-feedback_host:
306-
307-
.. confval:: feedback_host
308-
309-
Since version 1.10.1. The address to which the packet is sent.
310-
Usually the recipient is Tarantool, but it can be any URL.
311-
312-
| Type: string
313-
| Default: ``https://feedback.tarantool.io``
314-
| Environment variable: TT_FEEDBACK_HOST
315-
| Dynamic: **yes**
316-
317-
.. _cfg_logging-feedback_interval:
318-
319-
.. confval:: feedback_interval
320-
321-
Since version 1.10.1. The number of seconds between sendings, usually 3600 (1 hour).
322-
323-
| Type: float
324-
| Default: 3600
325-
| Environment variable: TT_FEEDBACK_INTERVAL
326-
| Dynamic: **yes**

‎doc/reference/configuration/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -399,6 +399,11 @@ Logging
399399

400400
.. include:: cfg_logging.rst
401401

402+
Feedback
403+
^^^^^^^^
404+
405+
.. include:: cfg_feedback.rst
406+
402407
Deprecated parameters
403408
^^^^^^^^^^^^^^^^^^^^^
404409

0 commit comments

Comments
 (0)