diff --git a/doc/reference/configuration/cfg_feedback.rst b/doc/reference/configuration/cfg_feedback.rst new file mode 100644 index 0000000000..e91b5de398 --- /dev/null +++ b/doc/reference/configuration/cfg_feedback.rst @@ -0,0 +1,49 @@ +.. _cfg_feedback: + +* :ref:`feedback_enabled ` +* :ref:`feedback_host ` +* :ref:`feedback_interval ` + +By default, a Tarantool daemon sends a small packet +once per hour, to ``https://feedback.tarantool.io``. +The packet contains three values from :ref:`box.info `: +``box.info.version``, ``box.info.uuid``, and ``box.info.cluster_uuid``. +By changing the feedback configuration parameters, users can +adjust or turn off this feature. + +.. _cfg_logging-feedback_enabled: + +.. confval:: feedback_enabled + + Since version 1.10.1. Whether to send feedback. + + If this is set to ``true``, feedback will be sent as described above. + If this is set to ``false``, no feedback will be sent. + + | Type: boolean + | Default: true + | Environment variable: TT_FEEDBACK_ENABLED + | Dynamic: **yes** + +.. _cfg_logging-feedback_host: + +.. confval:: feedback_host + + Since version 1.10.1. The address to which the packet is sent. + Usually the recipient is Tarantool, but it can be any URL. + + | Type: string + | Default: ``https://feedback.tarantool.io`` + | Environment variable: TT_FEEDBACK_HOST + | Dynamic: **yes** + +.. _cfg_logging-feedback_interval: + +.. confval:: feedback_interval + + Since version 1.10.1. The number of seconds between sendings, usually 3600 (1 hour). + + | Type: float + | Default: 3600 + | Environment variable: TT_FEEDBACK_INTERVAL + | Dynamic: **yes** diff --git a/doc/reference/configuration/cfg_logging.rst b/doc/reference/configuration/cfg_logging.rst index 2b8a9fc4b4..03466692c5 100644 --- a/doc/reference/configuration/cfg_logging.rst +++ b/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 ` to configure logging in your +application. + * :ref:`log_level ` * :ref:`log ` * :ref:`log_nonblock ` @@ -11,7 +15,7 @@ .. confval:: log_level Since version 1.6.2. - What level of detail the :ref:`log ` will have. There are seven levels: + Specifies the level of detail the :ref:`log ` has. There are seven levels: * 1 – ``SYSERROR`` * 2 – ``ERROR`` @@ -21,9 +25,9 @@ * 6 – ``VERBOSE`` * 7 – ``DEBUG`` - 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 - error stream by default, but this can be changed with the + 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. This can be changed with the :ref:`log ` configuration parameter. | Type: integer @@ -31,10 +35,11 @@ | Environment variable: TT_LOG_LEVEL | Dynamic: **yes** - Warning: prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was - level 6. Starting with Tarantool 1.7.5 ``VERBOSE`` is level 6 and ``DEBUG`` is level 7. - ``VERBOSE`` is a new level for monitoring repetitive events which would cause - too much log writing if ``INFO`` were used instead. + .. note:: + Prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was + level 6. Starting with Tarantool 1.7.5, ``VERBOSE`` is level 6 and ``DEBUG`` is level 7. + ``VERBOSE`` is a new level for monitoring repetitive events which would cause + too much log writing if ``INFO`` were used instead. .. _cfg_logging-log: @@ -42,10 +47,15 @@ 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: + + * file + + * pipe + + * system logger - Example setting for sending the log to a file: + Example 1: sending the log to the ``tarantool.log`` file. .. code-block:: lua @@ -53,25 +63,25 @@ -- or box.cfg{log = 'file:tarantool.log'} - This will open the file ``tarantool.log`` for output on the server’s default + This opens the file ``tarantool.log`` for output on the server's default 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: + Example 2: sending the log to a pipe. .. code-block:: lua box.cfg{log = '| cronolog tarantool.log'} -- or - box.cfg{log = 'pipe: cronolog tarantool.log'}' + box.cfg{log = 'pipe: cronolog tarantool.log'} - This will start the program `cronolog `_ when the server starts, and - will send all log messages to the standard input (``stdin``) of cronolog. + This starts the program `cronolog `_ when the server starts, and + sends all log messages to the standard input (``stdin``) of ``cronolog``. If the ``log`` string begins with '|' or has the prefix "pipe:", then the string is interpreted as a Unix `pipeline `_. - Example setting for sending the log to syslog: + Example 3: sending the log to syslog. .. code-block:: lua @@ -85,29 +95,28 @@ If the ``log`` string begins with "syslog:", then it is interpreted as a message for the - `syslogd `_ program which normally - is running in the background of any Unix-like platform. - The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...', - 'syslog:server=...', or a combination. - - The ``syslog:identity`` setting is an arbitrary string which will be placed at - the beginning of all messages. The default value is: tarantool. - - The ``syslog:facility`` setting is currently ignored but will be used in the future. - The value must be one of the `syslog `_ - keywords, which tell syslogd where the message should go. - The possible values are: auth, authpriv, cron, daemon, ftp, - kern, lpr, mail, news, security, syslog, user, uucp, local0, local1, local2, - local3, local4, local5, local6, local7. The default value is: local7. - - The ``syslog:server`` setting is the locator for the syslog server. - It can be a Unix socket path beginning with "unix:", or an ipv4 port number. - The default socket value is: dev/log (on Linux) or /var/run/syslog (on Mac OS). - The default port value is: 514, the UDP port. + `syslogd `_ program, which normally + is running in the background on any Unix-like platform. + The setting can be ``syslog:``, ``syslog:facility=...``, ``syslog:identity=...``, + ``syslog:server=...``, or a combination. + + * The ``syslog:identity`` setting is an arbitrary string, which is placed at + the beginning of all messages. The default value is "tarantool". + + * The ``syslog:facility`` setting is currently ignored but will be used in the future. + The value must be one of the `syslog `_ + keywords, which tell syslogd where the message should go. + The possible values are: auth, authpriv, cron, daemon, ftp, + kern, lpr, mail, news, security, syslog, user, uucp, local0, local1, local2, + local3, local4, local5, local6, local7. The default value is: local7. + + * The ``syslog:server`` setting is the locator for the syslog server. + It can be a Unix socket path beginning with "unix:", or an ipv4 port number. + The default socket value is: ``dev/log`` (on Linux) or ``/var/run/syslog`` (on macOS). + The default port value is: 514, the UDP port. When logging to a file, Tarantool reopens the log on `SIGHUP `_. - When log is - a program, its pid is saved in the :ref:`log.logger_pid ` + When log is a program, its PID is saved in the :ref:`log.pid ` variable. You need to send it a signal to rotate logs. | Type: string @@ -120,21 +129,23 @@ .. confval:: log_nonblock Since version 1.7.4. - If ``log_nonblock`` equals true, Tarantool does not block during logging + If ``log_nonblock`` equals **true**, Tarantool does not block during logging when the system is not ready for writing, and drops the message instead. If :ref:`log_level ` is high, and many - messages go to the log, setting ``log_nonblock`` to true may improve + messages go to the log, setting ``log_nonblock`` to **true** may improve logging performance at the cost of some log messages getting lost. - This parameter has effect only if the output is going to "syslog:" or - "pipe:". - Setting ``log_nonblock`` to true is illegal if the output is going to - a file. + This parameter has effect only if :ref:`log ` is + configured to send logs to a pipe or system logger. + The default ``log_nonblock`` value is **nil**, which means that + blocking behavior corresponds to the logger type: + + * **false** for ``stderr`` and file loggers. + + * **true** for a pipe and system logger. - The default ``log_nonblock`` value is nil, which means that - blocking behavior corresponds to the type of logger. This is a behavior change: in earlier versions of the Tarantool - server, the default value was true. + server, the default value was **true**. | Type: boolean | Default: nil @@ -148,7 +159,7 @@ Since version 1.6.2. If processing a request takes longer than the given value (in seconds), warn about it in the log. Has effect only if :ref:`log_level - ` is more than or equal to 4 (WARNING). + ` is greater than or equal to 4 (WARNING). | Type: float | Default: 0.5 @@ -164,13 +175,13 @@ * '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'}``: + Here is what a log entry looks like if ``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'}``: + Here is what a log entry looks like if ``box.cfg{log_format='json'}``: .. code-block:: text @@ -184,12 +195,12 @@ "file": "builtin\/box\/load_cfg.lua", "line": 317} - The ``log_format='plain'`` entry has time, process id, + The ``log_format='plain'`` entry has a time value, process ID, cord name, :ref:`fiber_id `, :ref:`fiber_name `, :ref:`log level `, and message. - The ``log_format='json'`` entry has the same things along with their labels, + The ``log_format='json'`` entry has the same fields along with their labels, and in addition has the file name and line number of the Tarantool source. Setting ``log_format`` to 'json' is illegal if the output is going to "syslog:". @@ -205,122 +216,72 @@ Logging example ********************* -This will illustrate how "rotation" works, that is, what happens when the server +This example illustrates how "rotation" works, that is, what happens when the server instance is writing to a log and signals are used when archiving it. -Start with two terminal shells, Terminal #1 and Terminal #2. - -On Terminal #1: start an interactive Tarantool session, then say the logging -will go to `Log_file`, then put a message "Log Line #1" in the log file: - -.. code-block:: lua - - box.cfg{log='Log_file'} - log = require('log') - log.info('Log Line #1') - -On Terminal #2: use ``mv`` so the log file is now named `Log_file.bak`. -The result of this is: the next log message will go to `Log_file.bak`. - -.. cssclass:: highlight -.. parsed-literal:: - - mv Log_file Log_file.bak - -On Terminal #1: put a message "Log Line #2" in the log file. +1. Start with two terminal shells: Terminal #1 and Terminal #2. -.. code-block:: lua +2. In Terminal #1, start an interactive Tarantool session. + Then, use the ``log`` property to send logs to `Log_file` and + call ``log.info`` to put a message in the log file. - log.info('Log Line #2') + .. code-block:: lua -On Terminal #2: use ``ps`` to find the process ID of the Tarantool instance. + box.cfg{log='Log_file'} + log = require('log') + log.info('Log Line #1') -.. cssclass:: highlight -.. parsed-literal:: +3. In Terminal #2, use the ``mv`` command to rename the log file to `Log_file.bak`. - ps -A | grep tarantool + .. cssclass:: highlight + .. parsed-literal:: -On Terminal #2: use ``kill -HUP`` to send a SIGHUP signal to the Tarantool instance. -The result of this is: Tarantool will open `Log_file` again, and -the next log message will go to `Log_file`. -(The same effect could be accomplished by executing log.rotate() on the instance.) + mv Log_file Log_file.bak -.. cssclass:: highlight -.. parsed-literal:: + As a result, the next log message will go to `Log_file.bak`. - kill -HUP *process_id* +4. Go back to Terminal #1 and put a message "Log Line #2" in the log file. -On Terminal #1: put a message "Log Line #3" in the log file. + .. code-block:: lua -.. code-block:: lua + log.info('Log Line #2') - log.info('Log Line #3') +5. In Terminal #2, use ``ps`` to find the process ID of the Tarantool instance. -On Terminal #2: use ``less`` to examine files. `Log_file.bak` will have these lines, -except that the date and time will depend on when the example is done: + .. cssclass:: highlight + .. parsed-literal:: -.. cssclass:: highlight -.. parsed-literal:: + ps -A | grep tarantool - 2015-11-30 15:13:06.373 [27469] main/101/interactive I> Log Line #1` - 2015-11-30 15:14:25.973 [27469] main/101/interactive I> Log Line #2` +6. In Terminal #2, execute ``kill -HUP`` to send a SIGHUP signal to the Tarantool instance. + Tarantool will open `Log_file` again, and the next log message will go to `Log_file`. -and `Log_file` will have + .. cssclass:: highlight + .. parsed-literal:: -.. cssclass:: highlight -.. parsed-literal:: + kill -HUP *process_id* - log file has been reopened - 2015-11-30 15:15:32.629 [27469] main/101/interactive I> Log Line #3 + The same effect could be accomplished by calling :ref:`log.rotate `. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Feedback -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +7. In Terminal #1, put a message "Log Line #3" in the log file. -* :ref:`feedback_enabled ` -* :ref:`feedback_host ` -* :ref:`feedback_interval ` + .. code-block:: lua -By default a Tarantool daemon sends a small packet -once per hour, to ``https://feedback.tarantool.io``. -The packet contains three values from :ref:`box.info `: -``box.info.version``, ``box.info.uuid``, and ``box.info.cluster_uuid``. -By changing the feedback configuration parameters, users can -adjust or turn off this feature. + log.info('Log Line #3') -.. _cfg_logging-feedback_enabled: +8. In Terminal #2, use ``less`` to examine files. + `Log_file.bak` will have the following lines ... -.. confval:: feedback_enabled + .. cssclass:: highlight + .. parsed-literal:: - Since version 1.10.1. Whether to send feedback. + 2015-11-30 15:13:06.373 [27469] main/101/interactive I> Log Line #1` + 2015-11-30 15:14:25.973 [27469] main/101/interactive I> Log Line #2` - If this is set to ``true``, feedback will be sent as described above. - If this is set to ``false``, no feedback will be sent. + ... and `Log_file` will look like this: - | Type: boolean - | Default: true - | Environment variable: TT_FEEDBACK_ENABLED - | Dynamic: **yes** - -.. _cfg_logging-feedback_host: - -.. confval:: feedback_host + .. cssclass:: highlight + .. parsed-literal:: - Since version 1.10.1. The address to which the packet is sent. - Usually the recipient is Tarantool, but it can be any URL. - - | Type: string - | Default: ``https://feedback.tarantool.io`` - | Environment variable: TT_FEEDBACK_HOST - | Dynamic: **yes** - -.. _cfg_logging-feedback_interval: - -.. confval:: feedback_interval - - Since version 1.10.1. The number of seconds between sendings, usually 3600 (1 hour). - - | Type: float - | Default: 3600 - | Environment variable: TT_FEEDBACK_INTERVAL - | Dynamic: **yes** + log file has been reopened + 2015-11-30 15:15:32.629 [27469] main/101/interactive I> Log Line #3 \ No newline at end of file diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index aa1455e77f..13ecb933c0 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -399,6 +399,11 @@ Logging .. include:: cfg_logging.rst +Feedback +^^^^^^^^ + +.. include:: cfg_feedback.rst + Deprecated parameters ^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/reference/reference_lua/log.rst b/doc/reference/reference_lua/log.rst index 441979c3a4..dbce1e5f7e 100644 --- a/doc/reference/reference_lua/log.rst +++ b/doc/reference/reference_lua/log.rst @@ -10,36 +10,12 @@ Overview =============================================================================== -The Tarantool server puts all diagnostic messages in a log file specified by -the :ref:`log ` configuration parameter. Diagnostic -messages may be either system-generated by the server's internal code, or -user-generated with the :samp:`log.{log_level_function_name}` function. - -As explained in the description of :ref:`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 ` 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 your application and +provides additional capabilities, for example, logging custom messages and +rotating log files. =============================================================================== Index @@ -55,24 +31,61 @@ Below is a list of all ``log`` functions. +--------------------------------------+---------------------------------+ | Name | Use | +======================================+=================================+ + | :ref:`log.cfg({}) | Configures a logger | + | ` | | + +--------------------------------------+---------------------------------+ | :ref:`log.error() | | | ` |br| | | | :ref:`log.warn() | | | ` |br| | | - | :ref:`log.info() | Write a user-generated message | - | ` |br| | to a log file | + | :ref:`log.info() | Logs a message with the | + | ` |br| | specified level | | :ref:`log.verbose() | | | ` |br| | | | :ref:`log.debug() | | | ` | | +--------------------------------------+---------------------------------+ - | :ref:`log.logger_pid() | Get the PID of a logger | - | ` | | + | :ref:`log.pid() | Gets the PID of a logger | + | ` | | +--------------------------------------+---------------------------------+ - | :ref:`log.rotate() | Rotate a log file | + | :ref:`log.rotate() | Rotates a log file | | ` | | +--------------------------------------+---------------------------------+ +.. _log-cfg: + +.. function:: log.cfg({}) + + Allows you to configure logging options. + The following options are available: + + * ``level``: Specifies the level of detail the log has. + + Learn more: :ref:`log_level `. + + * ``log``: Specifies where to send the log's output, for example, + to a file, pipe, or system logger. + + Learn more: :ref:`log `. + + * ``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 `. + + * ``format``: Specifies the log format: 'plain' or 'json'. + + Learn more: :ref:`log_format `. + + The example below shows how to 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) @@ -81,84 +94,60 @@ Below is a list of all ``log`` functions. verbose(message) debug(message) - Output a user-generated message to the :ref:`log file `, - given log_level_function_name = ``error`` or ``warn`` or ``info`` or - ``verbose`` or ``debug``. - - As explained in the description of the configuration setting for - :ref:`log_level `, there are seven levels of detail: + Logs a message with the specified logging level. + You can learn more about the available levels from the + :ref:`log_level ` property description. - * 1 – ``SYSERROR`` - * 2 – ``ERROR`` -- this corresponds to ``log.error(...)`` - * 3 – ``CRITICAL`` - * 4 – ``WARNING`` -- this corresponds to ``log.warn(...)`` - * 5 – ``INFO`` -- this corresponds to ``log.info(...)`` - * 6 – ``VERBOSE`` -- this corresponds to ``log.verbose(...)`` - * 7 – ``DEBUG`` -- this corresponds to ``log.debug(...)`` + The example below shows how to log a message with the ``info`` level: - For example, if ``box.cfg.log_level`` is currently 5 (the default value), - then ``log.error(...)``, ``log.warn(...)`` and ``log.info(...)`` messages - will go to the log file. However, ``log.verbose(...)`` and - ``log.debug(...)`` messages will not go to the log file, because they - correspond to higher levels of detail. + .. code-block:: lua - :param any message: Usually a string. + log = require('log') + log.info('Hello, world!') - Messages may contain C-style format specifiers %d or - %s, so :samp:`log.error('...%d...%s', {x}, {y})` - will work if ``x`` is a number and ``y`` is a string. + :param any message: A log message. - Less commonly, messages may be other scalar data types, - or even tables. So :code:`log.error({'x',18.7,true})` - will work. - - :return: nil + * A message can be a string. - The actual output will be a line in the log, containing: + * A message may contain C-style format specifiers ``%d`` or ``%s``. Example: - * the current timestamp, - * a module name, - * 'E', 'W', 'I', 'V' or 'D' depending on ``log_level_function_name``, and - * ``message``. + .. code-block:: lua - Output will not occur if ``log_level_function_name`` - is for a type greater than :ref:`log_level - `. + box.cfg{} + log = require('log') + log.info('Info %s', box.info.version) -.. _log-logger_pid: + * A message may be a scalar data type or a table. Example: -.. function:: logger_pid() + .. code-block:: lua - :return: PID of a logger + log = require('log') + log.error({500,'Internal error'}) -.. _log-rotate: + :return: nil -.. function:: rotate() + The actual output will be a line in the log, containing: - Rotate the log. + * the current timestamp + * a module name + * 'E', 'W', 'I', 'V' or 'D' depending on the called function + * ``message`` - :return: nil + Note that the message will not be logged if the severity level corresponding to + the called function is less than :ref:`log_level `. -================================================= - Example -================================================= +.. _log-pid: -.. code-block:: tarantoolsession +.. function:: pid() - $ tarantool - tarantool> box.cfg{log_level=3, log='tarantool.txt'} - tarantool> log = require('log') - tarantool> log.error('Error') - tarantool> log.info('Info %s', box.info.version) - tarantool> os.exit() + :return: A PID of a logger. You can use this PID to send a signal to a log rotation program, so it can rotate logs. -.. code-block:: console +.. _log-rotate: - $ less tarantool.txt - 2017-09-20 ... [68617] main/101/interactive C> version 1.7.5-31-ge939c6ea6 - 2017-09-20 ... [68617] main/101/interactive C> log level 3 - 2017-09-20 ... [68617] main/101/interactive [C]:-1 E> Error +.. function:: rotate() -The 'Error' line is visible in ``tarantool.txt`` preceded by the letter E. + Rotates the log. + For example, you need to call this function to continue logging after a log rotation program + renames or moves a file with the latest logs. -The 'Info' line is not present because the ``log_level`` is 3. + :return: nil