Document logging configuration #3397

andreyaksenov · 2023-03-09T11:55:03Z

Documented how to configure logging in the log module and improved a bit other logging docs along the way.
Here is the summary of the changes:

Moved the Feedback section outside of Logging as six-level deep nesting looks no good.
Updated the logging example to use a numbered list for better readability.
In the Module log topic, added a log.cfg description with an example and links to corresponding box.cfg properties.

Resolves #1974

Resolves #2242

Resolves #1974

p7nov

Some comments from my side

p7nov · 2023-03-14T07:14:30Z

doc/reference/configuration/cfg_logging.rst

@@ -11,7 +15,7 @@
 .. confval:: log_level

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


Maybe just drop the verb?
"The level of detail..."

I'd keep Specifies here as it shows that the property value can be get and set. What do you think?

p7nov · 2023-03-14T07:15:29Z

doc/reference/configuration/cfg_logging.rst

-    By setting log_level, one can enable logging of all classes below
-    or equal to the given level. Tarantool prints its logs to the standard
+    By setting ``log_level``, you can enable logging of all events with severities above
+    or equal to the given level. Tarantool prints logs to the standard
    error stream by default, but this can be changed with the


Suggested change

error stream by default, but this can be changed with the

error stream by default. This can be changed with the

p7nov · 2023-03-14T07:19:59Z

doc/reference/configuration/cfg_logging.rst

@@ -42,36 +46,41 @@

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


Not sure that the list below improves the text significantly: all the options are just 1-2 words and don't have explanations.

Anyway, in this case there are punctuation issues:

... instead of : before the list

; in the end of list items (see our style guide.

Not sure that the list below improves the text significantly: all the options are just 1-2 words and don't have explanations.

Generally, I agree but still think it's better than three or in a row :)

p7nov · 2023-03-14T07:23:25Z

doc/reference/configuration/cfg_logging.rst

@@ -32,7 +36,7 @@
    | Dynamic: **yes**

    Warning: prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was


Maybe turn this into a real warning?

Converted to a note

p7nov · 2023-03-14T07:24:57Z

doc/reference/configuration/cfg_logging.rst


-    Example setting for sending the log to a file:
+    The example below shows how to send logs to the ``tarantool.log`` file:


Idea: make examples less "narrative" but more structured:

Suggested change

The example below shows how to send logs to the ``tarantool.log`` file:

Example 1: sending the log to the ``tarantool.log`` file.

Yep, I like it.

p7nov · 2023-03-14T07:25:21Z

doc/reference/configuration/cfg_logging.rst

    directory. If the ``log`` string has no prefix or has the prefix "file:",
    then the string is interpreted as a file path.

-    Example setting for sending the log to a pipe:
+    This example shows how to send the log to a pipe:


Suggested change

This example shows how to send the log to a pipe:

Example 2: sending the log to a pipe.

p7nov · 2023-03-14T07:27:33Z

doc/reference/configuration/cfg_logging.rst

    If the ``log`` string begins with '|' or has the prefix "pipe:",
    then the string is interpreted as a Unix
    `pipeline <https://en.wikipedia.org/wiki/Pipeline_%28Unix%29>`_.

-    Example setting for sending the log to syslog:
+    The example below shows how to send the log to syslog:


Suggested change

The example below shows how to send the log to syslog:

Example 3: sending the log to syslog.

p7nov · 2023-03-14T07:29:02Z

doc/reference/configuration/cfg_logging.rst

-    `syslogd <http://www.rfc-base.org/txt/rfc-5424.txt>`_ program which normally
-    is running in the background of any Unix-like platform.
+    `syslogd <https://linux.die.net/man/8/syslogd>`_ program, which normally
+    is running in the background on any Unix-like platform.
    The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...',


Suggested change

The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...',

The setting can be ``syslog:``, ``syslog:facility=...``, ``syslog:identity=...``,

p7nov · 2023-03-14T07:37:39Z

doc/reference/reference_lua/log.rst

+
+.. function:: log.cfg({})
+
+    Allows you to configure logging options.


Maybe drop "Allows you to"?

I'd keep it as is - I think, Allows you to... or Provides the ability to ... suits good for complex configuration options that don't do a specific thing but provide access to a bunch of related properties.

p7nov · 2023-03-14T07:40:31Z

doc/reference/reference_lua/log.rst


    :return: nil

    The actual output will be a line in the log, containing:

    * the current timestamp,
    * a module name,
-    * 'E', 'W', 'I', 'V' or 'D' depending on ``log_level_function_name``, and
+    * 'E', 'W', 'I', 'V' or 'D' depending on the called function, and


"and" seems awkward to me here

agree, didn't catch it when reviewing old docs. AFAIU, commas aren't required here, according to the style guide.

Resolves #1974

p7nov

LGTM 👍

* Document logging configuration * Document default log_nonblock values for different loggers Resolves #1974 Resolves #2242

Document logging configuration

6dc2447

Resolves #1974

andreyaksenov linked an issue Mar 9, 2023 that may be closed by this pull request

[2pt] feedback: Configuration reference #2242

Closed

andreyaksenov added 10 commits March 9, 2023 17:19

Document default log_nonblock values for different loggers

0772a0e

Resolves #2242

Document logging settings

327ac30

Resolves #1974

Document logging settings

ffeaf77

Resolves #1974

Document logging settings - fix formatting

1b8445d

Resolves #1974

Document logging settings

9befdd0

Resolves #1974

Document logging settings - cosmetics

c40c95e

Resolves #1974

Document logging settings - log rotation

b76008d

Resolves #1974

Document logging settings - fix a link

ea1dd09

Resolves #1974

Document logging settings - use the numbered list in example

d2bcc98

Resolves #1974

Document logging settings - cosmetics

49d6ef4

Resolves #1974

andreyaksenov marked this pull request as ready for review March 13, 2023 07:49

andreyaksenov requested a review from Gumix March 13, 2023 07:50

Document logging settings - cosmetics

a62644c

Resolves #1974

Gumix approved these changes Mar 13, 2023

View reviewed changes

andreyaksenov requested a review from p7nov March 13, 2023 13:12

p7nov reviewed Mar 14, 2023

View reviewed changes

Document logging settings - update per review

c824092

Resolves #1974

andreyaksenov requested a review from p7nov March 14, 2023 08:43

p7nov approved these changes Mar 14, 2023

View reviewed changes

andreyaksenov merged commit e88488d into latest Mar 14, 2023

andreyaksenov deleted the logging branch March 14, 2023 09:59

p7nov pushed a commit that referenced this pull request Mar 24, 2023

Document logging configuration (#3397)

3142aae

* Document logging configuration * Document default log_nonblock values for different loggers Resolves #1974 Resolves #2242

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document logging configuration #3397

Document logging configuration #3397

andreyaksenov commented Mar 9, 2023 •

edited

Loading

p7nov left a comment

p7nov Mar 14, 2023

andreyaksenov Mar 14, 2023 •

edited

Loading

p7nov Mar 14, 2023

p7nov Mar 14, 2023

p7nov Mar 14, 2023

andreyaksenov Mar 14, 2023

p7nov Mar 14, 2023

andreyaksenov Mar 14, 2023

p7nov Mar 14, 2023

andreyaksenov Mar 14, 2023

p7nov Mar 14, 2023

p7nov Mar 14, 2023

p7nov Mar 14, 2023

p7nov Mar 14, 2023

andreyaksenov Mar 14, 2023 •

edited

Loading

p7nov Mar 14, 2023

andreyaksenov Mar 14, 2023 •

edited

Loading

p7nov left a comment

	error stream by default, but this can be changed with the
	error stream by default. This can be changed with the

		@@ -32,7 +36,7 @@
		\| Dynamic: yes

		Warning: prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was


		Example setting for sending the log to a file:
		The example below shows how to send logs to the ``tarantool.log`` file:

	The example below shows how to send logs to the ``tarantool.log`` file:
	Example 1: sending the log to the ``tarantool.log`` file.

	This example shows how to send the log to a pipe:
	Example 2: sending the log to a pipe.

	The example below shows how to send the log to syslog:
	Example 3: sending the log to syslog.

	The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...',
	The setting can be ``syslog:``, ``syslog:facility=...``, ``syslog:identity=...``,


		.. function:: log.cfg({})

		Allows you to configure logging options.

Document logging configuration #3397

Document logging configuration #3397

Conversation

andreyaksenov commented Mar 9, 2023 • edited Loading

p7nov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Mar 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Mar 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreyaksenov Mar 14, 2023 • edited Loading

Choose a reason for hiding this comment

p7nov left a comment

Choose a reason for hiding this comment

andreyaksenov commented Mar 9, 2023 •

edited

Loading

andreyaksenov Mar 14, 2023 •

edited

Loading

andreyaksenov Mar 14, 2023 •

edited

Loading

andreyaksenov Mar 14, 2023 •

edited

Loading