Document logging settings

Resolves #1974

Author: andreyaksenov

doc/reference/configuration/cfg_logging.rst

@@ -1,5 +1,9 @@
 .. _cfg_logging:
 
+This section provides information on how to configure options related to logging.
+You can also use the :ref:`log module <log-module>` to configure logging in your
+application.
+
 * :ref:`log_level <cfg_logging-log_level>`
 * :ref:`log <cfg_logging-log>`
 * :ref:`log_nonblock <cfg_logging-log_nonblock>`

doc/reference/reference_lua/log.rst

@@ -10,37 +10,12 @@
                                    Overview
 ===============================================================================
 
-The ``log`` module provides the event logging system for the Tarantool server.
-Tarantool puts all diagnostic messages in a log specified by
-the :ref:`log <cfg_logging-log>` configuration parameter. Diagnostic
-messages may be either system-generated by the server's internal code, or
-user-generated using the dedicated functions: ``log.info()``, ``log.error()``, and so on.
-
-As explained in the description of :ref:`log_format <cfg_logging-log_format>` 
-configuration setting, there are two possible formats for log entries:
-
-* 'plain' (the default), or
-* 'json' (with more detail and with JSON labels).
-
-Here is what a log entry looks like after ``box.cfg{log_format='plain'}``:
-
-.. code-block:: text
-
-    2017-10-16 11:36:01.508 [18081] main/101/interactive I> set 'log_format' configuration option to "plain"
-
-Here is what a log entry looks like after ``box.cfg{log_format='json'}``:
-
-.. code-block:: text
-
-    {"time": "2017-10-16T11:36:17.996-0600",
-    "level": "INFO",
-    "message": "set 'log_format' configuration option to \"json\"",
-    "pid": 18081,|
-    "cord_name": "main",
-    "fiber_id": 101,
-    "fiber_name": "interactive",
-    "file": "builtin\/box\/load_cfg.lua",
-    "line": 317}
+Tarantool provides a set of :ref:`options <cfg_logging>` used to configure logging
+in various ways: you can set a level of logging, specify where to send the log's output,
+configure a log format, and so on.
+The ``log`` module allows you to configure logging in you application and
+provides additional capabilities, for example, logging custom messages and
+rotating log files.
 
 ===============================================================================
                                     Index
@@ -56,12 +31,15 @@ Below is a list of all ``log`` functions.
     +--------------------------------------+---------------------------------+
     | Name                                 | Use                             |
     +======================================+=================================+
+    | :ref:`log.cfg({})                    | Configure a logger              |
+    | <log-cfg>`                           |                                 |
+    +--------------------------------------+---------------------------------+
     | :ref:`log.error()                    |                                 |
     | <log-ug_message>` |br|               |                                 |
     | :ref:`log.warn()                     |                                 |
     | <log-ug_message>` |br|               |                                 |
-    | :ref:`log.info()                     | Write a user-generated message  |
-    | <log-ug_message>` |br|               | to a log file                   |
+    | :ref:`log.info()                     | Log a message with the          |
+    | <log-ug_message>` |br|               | specified level                 |
     | :ref:`log.verbose()                  |                                 |
     | <log-ug_message>` |br|               |                                 |
     | :ref:`log.debug()                    |                                 |
@@ -74,6 +52,39 @@ Below is a list of all ``log`` functions.
     | <log-rotate>`                        |                                 |
     +--------------------------------------+---------------------------------+
 
+.. _log-cfg:
+
+.. function:: log.cfg({})
+
+    Allows you to configure logging options.
+    The following logging options are available:
+
+    * ``level``: Specifies the level of detail the log has.
+      This property has the same effect as :ref:`log_level <cfg_logging-log_level>`.
+
+    * ``log``: Specifies where to to send the log's output, for example,
+      to a file, pipe, or system logger.
+
+      See also: :ref:`log <cfg_logging-log>`
+
+    * ``nonblock``: If **true**, Tarantool does not block during logging when the system
+      is not ready for writing, and drops the message instead.
+
+      See also: :ref:`log_nonblock <cfg_logging-log_nonblock>`
+
+    * ``format``: Specifies the log format: 'plain' or 'json'.
+
+      See also: :ref:`log_format <cfg_logging-log_format>`
+
+    The example below shows how set the log level to 'debug' and how to send the resulting log
+    to the 'tarantool.log' file:
+
+    .. code-block:: lua
+
+        log = require('log')
+        log.cfg{ level='debug', log='tarantool.log'}
+
+
 .. _log-ug_message:
 
 .. function:: error(message)