Logging module API

Author: andreyaksenov

doc/reference/reference_lua/log.rst

@@ -64,7 +64,7 @@ Below is a list of all ``log`` functions.
 
     * ``level``: Specifies the level of detail the log has.
 
-      Learn more: :ref:`log_level <cfg_logging-log_level>`.
+      Learn more: :ref:`log.level <configuration_reference_log_level>`.
 
     * ``log``: Specifies where to send the log's output, for example,
       to a file, pipe, or system logger.
@@ -74,29 +74,26 @@ Below is a list of all ``log`` functions.
     * ``nonblock``: If **true**, Tarantool does not block during logging when the system
       is not ready for writing, and drops the message instead.
 
-      Learn more: :ref:`log_nonblock <cfg_logging-log_nonblock>`.
+      Learn more: :ref:`log.nonblock <configuration_reference_log_nonblock>`.
 
     * ``format``: Specifies the log format: 'plain' or 'json'.
 
-      Learn more: :ref:`log_format <cfg_logging-log_format>`.
+      Learn more: :ref:`log.format <configuration_reference_log_format>`.
 
     * ``modules``: Configures the specified log levels for different modules.
 
-      Learn more: :ref:`log_modules <cfg_logging-log_modules>`.
+      Learn more: :ref:`log.modules <configuration_reference_log_modules>`.
 
-    The example below shows how to set the log level to 'debug' and how to send the resulting log
-    to the 'tarantool.log' file:
+    **Example**
 
-    .. code-block:: lua
+    The example below shows how to set the log level to ``verbose``:
 
-        log = require('log')
-        log.cfg{ level='debug', log='tarantool.log'}
-
-    .. NOTE::
+    ..  literalinclude:: /code_snippets/test/logging/log_test.lua
+        :language: lua
+        :start-at: local log = require
+        :end-at: log.cfg
+        :dedent:
 
-        Note that calling ``log.cfg()`` before ``box.cfg()`` takes into account
-        logging options specified using :ref:`environment variables <box-cfg-params-env>`,
-        such as ``TT_LOG`` and ``TT_LOG_LEVEL``.
 
 .. _log-ug_message:
 
@@ -108,13 +105,16 @@ Below is a list of all ``log`` functions.
 
     Log a message with the specified logging level.
     You can learn more about the available levels from the
-    :ref:`log_level <cfg_logging-log_level>` property description.
+    :ref:`log.level <configuration_reference_log_level>` option description.
+
+    **Example**
 
-    The example below shows how to log a message with the ``info`` level:
+    The example below shows how to log a message with the ``warn`` level:
 
     ..  literalinclude:: /code_snippets/test/logging/log_test.lua
         :language: lua
-        :lines: 13-21
+        :start-at: log.warn
+        :end-at: log.warn
         :dedent:
 
     :param any message:    A log message.
@@ -123,18 +123,19 @@ Below is a list of all ``log`` functions.
 
                            * A message may contain C-style format specifiers ``%d`` or ``%s``. Example:
 
-                             .. code-block:: lua
-
-                                 box.cfg{}
-                                 log = require('log')
-                                 log.info('Info %s', box.info.version)
+                             ..  literalinclude:: /code_snippets/test/logging/log_test.lua
+                                 :language: lua
+                                 :start-at: log.info
+                                 :end-at: log.info
+                                 :dedent:
 
                            * A message may be a scalar data type or a table. Example:
 
-                             .. code-block:: lua
-
-                                 log = require('log')
-                                 log.error({500,'Internal error'})
+                             ..  literalinclude:: /code_snippets/test/logging/log_test.lua
+                                 :language: lua
+                                 :start-at: log.error
+                                 :end-at: log.error
+                                 :dedent:
 
     :return: nil
 
@@ -146,7 +147,7 @@ Below is a list of all ``log`` functions.
     * ``message``
 
     Note that the message will not be logged if the severity level corresponding to
-    the called function is less than :ref:`log_level <cfg_logging-log_level>`.
+    the called function is less than :ref:`log.level <configuration_reference_log_level>`.
 
 .. _log-pid:
 
@@ -176,28 +177,32 @@ Below is a list of all ``log`` functions.
     :param string name: a logger name
     :return: a logger instance
 
-    **Example:**
+    **Example**
 
-    The code snippet below shows how to set the ``verbose`` level for ``module1`` and the ``error`` level for ``module2``:
+    This example shows how to set the ``verbose`` level for ``module1`` and the ``error`` level for ``module2`` in a configuration file:
 
-    ..  literalinclude:: /code_snippets/test/logging/log_new_modules_test.lua
-        :language: lua
-        :lines: 9-13
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml
+        :language: yaml
+        :start-at: log:
+        :end-at: app.lua
         :dedent:
 
-    To create the ``module1`` and ``module2`` loggers, call the ``new()`` function:
+    To create the ``module1`` and ``module2`` loggers in your application (``app.lua``), call the ``new()`` function:
 
-    ..  literalinclude:: /code_snippets/test/logging/log_new_modules_test.lua
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua
         :language: lua
-        :lines: 17-19
+        :start-at: Creates new loggers
+        :end-at: module2_log = require
         :dedent:
 
     Then, you can call functions corresponding to different logging levels to make sure
     that events with severities above or equal to the given levels are shown:
 
-    ..  literalinclude:: /code_snippets/test/logging/log_new_modules_test.lua
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua
         :language: lua
-        :lines: 21-41
+        :start-after: module2_log = require
         :dedent:
 
     At the same time, the events with severities below the specified levels are swallowed.
+
+    Example on GitHub: `log_new_modules <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/log_new_modules>`_.