diff --git a/doc/book/admin/logs.rst b/doc/book/admin/logs.rst index 397f1e3af2..0274ebf043 100644 --- a/doc/book/admin/logs.rst +++ b/doc/book/admin/logs.rst @@ -3,7 +3,7 @@ Logs ==== -Each Tarantool instance logs important events to its own log file ``.log``. +Each Tarantool instance logs important events to its own log file. For instances started with :ref:`tt `, the log location is defined by the ``log_dir`` parameter in the :ref:`tt configuration `. By default, it's ``/var/log/tarantool`` in the ``tt`` :ref:`system mode `, @@ -14,34 +14,36 @@ To check how logging works, write something to the log using the :ref:`log require('log').info("Hello for the manual readers") + application> require('log').info("Hello for the manual readers") + --- + ... Then check the logs: .. code-block:: console - $ tail /var/log/tarantool/my_app.log - 2023-09-12 18:13:00.396 [67173] main/111/guard of feedback_daemon/box.feedback_daemon V> metrics_collector restarted - 2023-09-12 18:13:00.396 [67173] main/103/-/box.feedback_daemon V> feedback_daemon started - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(14) = 0x1090077b4 - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(26) = 0x1090077ec - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(39) = 0x109007824 - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(24) = 0x10900785c - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(39) = 0x109007894 - 2023-09-12 18:13:00.396 [67173] main/106/checkpoint_daemon I> scheduled next checkpoint for Tue Sep 12 19:44:34 2023 - 2023-09-12 18:13:00.396 [67173] main I> entering the event loop - 2023-09-12 18:13:11.656 [67173] main/114/console/unix/:/tarantool I> Hello for the manual readers + $ tail instances.enabled/application/var/log/instance001/tt.log + 2024-04-09 17:34:29.489 [49502] main/106/gc I> wal/engine cleanup is resumed + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'instance_name' configuration option to "instance001" + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'custom_proc_title' configuration option to "tarantool - instance001" + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'log_nonblock' configuration option to false + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'replicaset_name' configuration option to "replicaset001" + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'listen' configuration option to [{"uri":"127.0.0.1:3301"}] + 2024-04-09 17:34:29.489 [49502] main/107/checkpoint_daemon I> scheduled next checkpoint for Tue Apr 9 19:08:04 2024 + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'metrics' configuration option to {"labels":{"alias":"instance001"},"include":["all"],"exclude":[]} + 2024-04-09 17:34:29.489 [49502] main I> entering the event loop + 2024-04-09 17:34:38.905 [49502] main/116/console/unix/:/tarantool I> Hello for the manual readers .. _admin-logs-rotation: Log rotation ------------ -When :ref:`logging to a file `, the system administrator must ensure +When :ref:`logging to a file `, the system administrator must ensure logs are rotated timely and do not take up all the available disk space. The recommended way to prevent log files from growing infinitely is using an external log rotation program, for example, ``logrotate``, which is pre-installed on most @@ -76,22 +78,16 @@ To learn about log rotation in the deprecated ``tarantoolctl`` utility, check its :ref:`documentation `. -.. _admin-logs-formats: +.. _admin-logs-destination: -Log formats ------------ +Log destination +--------------- -Tarantool can write its logs to a log file, to ``syslog``, or to a specified program -through a pipe. +Tarantool can write its logs to a log file, to ``syslog``, or to a specified program through a pipe. +For example, to send logs to ``syslog``, specify the :ref:`log.to ` parameter as follows: -File is the default log format for ``tt``. To send logs to a pipe or ``syslog``, -specify the :ref:`box.cfg.log ` parameter, for example: - -.. code-block:: lua - - box.cfg{log = '| cronolog tarantool.log'} - -- or - box.cfg{log = 'syslog:identity=tarantool,facility=user'} - -In such configurations, log rotation is usually handled by the external program -used for logging. +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml + :language: yaml + :start-at: log: + :end-at: 127.0.0.1:514 + :dedent: diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml index 1cb999804f..5dd84fefc6 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml @@ -1,6 +1,6 @@ audit_log: to: pipe - pipe: '| cronolog audit_tarantool.log' + pipe: 'cronolog audit_tarantool.log' groups: group001: @@ -10,4 +10,4 @@ groups: instance001: iproto: listen: - - uri: '127.0.0.1:3301' \ No newline at end of file + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml index 7ead91f70b..5858d514bd 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml @@ -4,18 +4,15 @@ audit_log: server: 'unix:/dev/log' facility: 'user' identity: 'tarantool_audit' - filter: 'audit,auth,priv,password_change,access_denied' + filter: [ audit, auth, priv, password_change, access_denied ] extract_key: false groups: group001: - iproto: - listen: - - uri: '127.0.0.1:3301' replicasets: replicaset001: instances: instance001: iproto: listen: - - uri: '127.0.0.1:3301' \ No newline at end of file + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua new file mode 100644 index 0000000000..5b8745ed3b --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua @@ -0,0 +1,16 @@ +ffi = require('ffi') + +-- Prints 'info' messages -- +ffi.C._say(ffi.C.S_INFO, nil, 0, nil, 'Info message from C module') +--[[ +[6024] main/103/interactive I> Info message from C module +--- +... +--]] + +-- Swallows 'debug' messages -- +ffi.C._say(ffi.C.S_DEBUG, nil, 0, nil, 'Debug message from C module') +--[[ +--- +... +--]] diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml new file mode 100644 index 0000000000..746232c06e --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml @@ -0,0 +1,15 @@ +log: + modules: + tarantool: 'info' +app: + file: 'app.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua new file mode 100644 index 0000000000..fec680ad97 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua @@ -0,0 +1,17 @@ +module1 = require('test.module1') +module2 = require('test.module2') + +-- Prints 'info' messages -- +module1.say_hello() +--[[ +[92617] main/103/interactive/test.logging.module1 I> Info message from module1 +--- +... +--]] + +-- Swallows 'info' messages -- +module2.say_hello() +--[[ +--- +... +--]] diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml new file mode 100644 index 0000000000..525bf902c2 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml @@ -0,0 +1,16 @@ +log: + modules: + test.module1: 'verbose' + test.module2: 'error' +app: + file: 'app.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua new file mode 100644 index 0000000000..008a03b099 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua @@ -0,0 +1,6 @@ +return { + say_hello = function() + local log = require('log') + log.info('Info message from module1') + end +} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module2.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module2.lua new file mode 100644 index 0000000000..6f36de4e47 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module2.lua @@ -0,0 +1,6 @@ +return { + say_hello = function() + local log = require('log') + log.info('Info message from module2') + end +} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_file/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_file/config.yaml new file mode 100644 index 0000000000..d16fb8fd1a --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_file/config.yaml @@ -0,0 +1,13 @@ +log: + to: file + file: var/log/{{ instance_name }}/instance.log + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_file/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_file/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_file/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_level/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_level/config.yaml new file mode 100644 index 0000000000..dcc4f37926 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_level/config.yaml @@ -0,0 +1,12 @@ +log: + level: 'verbose' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_level/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_level/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_level/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua new file mode 100644 index 0000000000..d58f85c8a8 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua @@ -0,0 +1,25 @@ +-- Creates new loggers -- +module1_log = require('log').new('module1') +module2_log = require('log').new('module2') + +-- Prints 'info' messages -- +module1_log.info('Info message from module1') +--[[ +[16300] main/103/interactive/module1 I> Info message from module1 +--- +... +--]] + +-- Swallows 'debug' messages -- +module1_log.debug('Debug message from module1') +--[[ +--- +... +--]] + +-- Swallows 'info' messages -- +module2_log.info('Info message from module2') +--[[ +--- +... +--]] diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml new file mode 100644 index 0000000000..302ae2364e --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml @@ -0,0 +1,16 @@ +log: + modules: + module1: 'verbose' + module2: 'error' +app: + file: 'app.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml new file mode 100644 index 0000000000..4e53e27c03 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml @@ -0,0 +1,13 @@ +log: + to: pipe + pipe: 'cronolog tarantool.log' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_pipe/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml new file mode 100644 index 0000000000..904342fa52 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml @@ -0,0 +1,15 @@ +log: + to: syslog + syslog: + server: '127.0.0.1:514' +# server: 'unix:/dev/log' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_syslog/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/test/logging/log_test.lua b/doc/code_snippets/test/logging/log_test.lua index ddc031d0b8..278cd43986 100644 --- a/doc/code_snippets/test/logging/log_test.lua +++ b/doc/code_snippets/test/logging/log_test.lua @@ -6,26 +6,16 @@ local g = t.group() g.before_each(function(cg) cg.server = server:new { workdir = fio.cwd() .. '/tmp', - box_cfg = { log_level = 'warn' } + box_cfg = {} } cg.server:start() cg.server:exec(function() - log = require('log') - - -- Prints 'warn' messages -- + local log = require('log') + log.cfg { level = 'verbose' } log.warn('Warning message') - --[[ - 2023-07-20 11:03:57.029 [16300] main/103/interactive/tarantool [C]:-1 W> Warning message - --- - ... - --]] - - -- Swallows 'debug' messages -- + log.info('Tarantool version: %s', box.info.version) + log.error({ 500, 'Internal error' }) log.debug('Debug message') - --[[ - --- - ... - --]] end) end) @@ -43,5 +33,7 @@ end g.test_log_contains_messages = function(cg) find_in_log(cg, 'Warning message', true) + find_in_log(cg, 'Tarantool version:', true) + find_in_log(cg, 'Internal error', true) find_in_log(cg, 'Debug message', false) end diff --git a/doc/reference/configuration/cfg_logging.rst b/doc/reference/configuration/cfg_logging.rst index dbcbe37f1c..85d396ae83 100644 --- a/doc/reference/configuration/cfg_logging.rst +++ b/doc/reference/configuration/cfg_logging.rst @@ -17,15 +17,16 @@ application. Since version 1.6.2. - Specify the level of detail the :ref:`log ` has. There are seven levels: + Specify the level of detail the :ref:`log ` has. There are the following levels: - * 1 -- ``SYSERROR`` - * 2 -- ``ERROR`` - * 3 -- ``CRITICAL`` - * 4 -- ``WARNING`` - * 5 -- ``INFO`` - * 6 -- ``VERBOSE`` - * 7 -- ``DEBUG`` + * 0 -- ``fatal`` + * 1 -- ``syserror`` + * 2 -- ``error`` + * 3 -- ``crit`` + * 4 -- ``warn`` + * 5 -- ``info`` + * 6 -- ``verbose`` + * 7 -- ``debug`` 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 @@ -33,7 +34,7 @@ application. :ref:`log ` configuration parameter. | - | Type: integer + | Type: integer, string | Default: 5 | Environment variable: TT_LOG_LEVEL | Dynamic: yes diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 45b56cc045..5508a5d293 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -89,7 +89,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi **Example** .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: lua + :language: yaml :start-at: filter: :end-at: custom ] :dedent: @@ -117,8 +117,8 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi .. code-block:: yaml audit_log: - to: file - format: plain + to: file + format: plain the output in the file might look as follows: @@ -169,17 +169,15 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi **Example** + This starts the `cronolog `_ program when the server starts + and sends all ``audit_log`` messages to cronolog standard input (``stdin``). + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml :language: yaml :start-at: audit_log: - :end-at: '| cronolog audit_tarantool.log' + :end-at: 'cronolog audit_tarantool.log' :dedent: - This starts the `cronolog `_ program when the server starts - and sends all ``audit_log`` messages to cronolog standard input (``stdin``). - If the ``audit_log`` string starts with '|', - the string is interpreted as a Unix `pipeline `_. - | | Type: string | Default: box.NULL @@ -1874,6 +1872,365 @@ instances For example, :ref:`iproto ` and :ref:`database ` configuration parameters defined at the instance level are applied to this instance only. + + +.. _configuration_reference_log: + +log +--- + +The ``log`` section defines configuration parameters related to logging. +To handle logging in your application, use the :ref:`log module `. + +.. NOTE:: + + ``log`` can be defined in any :ref:`scope `. + +* :ref:`log.to ` +* :ref:`log.file ` +* :ref:`log.format ` +* :ref:`log.level ` +* :ref:`log.modules ` +* :ref:`log.nonblock ` +* :ref:`log.pipe ` +* :ref:`log.syslog.* ` + + - :ref:`log.syslog.facility ` + - :ref:`log.syslog.identity ` + - :ref:`log.syslog.server ` + + +.. _configuration_reference_log_to: + +.. confval:: log.to + + Define a location Tarantool sends logs to. + This option accepts the following values: + + * ``stderr``: write logs to the standard error stream. + * ``file``: write logs to a file (see :ref:`log.file `). + * ``pipe``: start a program and write logs to its standard input (see :ref:`log.pipe `). + * ``syslog``: write logs to a system logger (see :ref:`log.syslog.* `). + + | + | Type: string + | Default: 'stderr' + | Environment variable: TT_LOG_TO + + +.. _configuration_reference_log_file: + +.. confval:: log.file + + Specify a file for logs destination. + To write logs to a file, you need to set :ref:`log.to ` to ``file``. + Otherwise, ``log.file`` is ignored. + + **Example** + + The example below shows how to write logs to a file placed in the specified directory: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_file/config.yaml + :language: yaml + :start-at: log: + :end-at: instance.log + :dedent: + + Example on GitHub: `log_file `_. + + | + | Type: string + | Default: 'var/log/{{ instance_name }}/tarantool.log' + | Environment variable: TT_LOG_FILE + + +.. _configuration_reference_log_format: + +.. confval:: log.format + + Specify a format that is used for a log entry. + The following formats are supported: + + * ``plain``: a log entry is formatted as plain text. Example: + + .. code-block:: text + + 2024-04-09 11:00:10.369 [12089] main/104/interactive I> log level 5 (INFO) + + * ``json``: a log entry is formatted as JSON and includes additional fields. Example: + + .. code-block:: text + + { + "time": "2024-04-09T11:00:57.174+0300", + "level": "INFO", + "message": "log level 5 (INFO)", + "pid": 12160, + "cord_name": "main", + "fiber_id": 104, + "fiber_name": "interactive", + "file": "src/main.cc", + "line": 498 + } + + | + | Type: string + | Default: 'plain' + | Environment variable: TT_LOG_FORMAT + + +.. _configuration_reference_log_level: + +.. confval:: log.level + + Specify the level of detail logs have. + There are the following levels: + + * 0 -- ``fatal`` + * 1 -- ``syserror`` + * 2 -- ``error`` + * 3 -- ``crit`` + * 4 -- ``warn`` + * 5 -- ``info`` + * 6 -- ``verbose`` + * 7 -- ``debug`` + + By setting ``log.level``, you can enable logging of all events with severities above or equal to the given level. + + **Example** + + The example below shows how to log all events with severities above or equal to the ``VERBOSE`` level. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_level/config.yaml + :language: yaml + :start-at: log: + :end-at: verbose + :dedent: + + Example on GitHub: `log_level `_. + + | + | Type: number, string + | Default: 5 + | Environment variable: TT_LOG_LEVEL + + +.. _configuration_reference_log_modules: + +.. confval:: log.modules + + Configure the specified log levels (:ref:`log.level `) for different modules. + + You can specify a logging level for the following module types: + + * Modules (files) that use the default logger. + Example: :ref:`Set log levels for files that use the default logger `. + + * Modules that use custom loggers created using the :ref:`log.new() ` function. + Example: :ref:`Set log levels for modules that use custom loggers `. + + * The ``tarantool`` module that enables you to configure the logging level for Tarantool core messages. + Specifically, it configures the logging level for messages logged from non-Lua code, including C modules. + Example: :ref:`Set a log level for C modules `. + + .. _configuration_reference_log_modules_example_existing_modules: + + **Example 1: Set log levels for files that use the default logger** + + Suppose you have two identical modules placed by the following paths: ``test/module1.lua`` and ``test/module2.lua``. + These modules use the default logger and look as follows: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua + :language: lua + :dedent: + + To configure logging levels, you need to provide module names corresponding to paths to these modules: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml + :language: yaml + :start-at: log: + :end-at: app.lua + :dedent: + + To load these modules in your application (``app.lua``), you need to add the corresponding ``require`` directives: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua + :language: lua + :start-at: module1 = require + :end-at: module2 = require + :dedent: + + Given that ``module1`` has the ``verbose`` logging level and ``module2`` has the ``error`` level, calling ``module1.say_hello()`` shows a message but ``module2.say_hello()`` is swallowed: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua + :language: lua + :start-after: module2 = require + :dedent: + + Example on GitHub: `log_existing_modules `_. + + .. _configuration_reference_log_modules_example_new_modules: + + **Example 2: Set log levels for modules that use custom loggers** + + This example shows how to set the ``verbose`` level for ``module1`` and the ``error`` level for ``module2``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml + :language: yaml + :start-at: log: + :end-at: app.lua + :dedent: + + To create custom loggers in your application (``app.lua``), call the :ref:`log.new() ` function: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua + :language: lua + :start-at: Creates new loggers + :end-at: module2_log = require + :dedent: + + Given that ``module1`` has the ``verbose`` logging level and ``module2`` has the ``error`` level, calling ``module1_log.info()`` shows a message but ``module2_log.info()`` is swallowed: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua + :language: lua + :start-after: module2_log = require + :dedent: + + Example on GitHub: `log_new_modules `_. + + .. _configuration_reference_log_modules_example_tarantool_module: + + **Example 3: Set a log level for C modules** + + This example shows how to set the ``info`` level for the ``tarantool`` module: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml + :language: yaml + :start-at: log: + :end-at: app.lua + :dedent: + + The specified level affects messages logged from C modules: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua + :language: lua + :dedent: + + The example above uses the `LuaJIT ffi library `_ to call C functions provided by the ``say`` module. + + Example on GitHub: `log_existing_c_modules `_. + + | + | Type: map + | Default: :ref:`box.NULL ` + | Environment variable: TT_LOG_MODULES + + +.. _configuration_reference_log_nonblock: + +.. confval:: log.nonblock + + Specify the logging behavior if the system is not ready to write. + If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. + Using this value may improve logging performance at the cost of losing some log messages. + + .. note:: + + The option only has an effect if the :ref:`log.to ` is set to ``syslog`` + or ``pipe``. + + | + | Type: boolean + | Default: false + | Environment variable: TT_LOG_NONBLOCK + +.. _configuration_reference_log_pipe: + +.. confval:: log.pipe + + Start a program and write logs to its standard input (``stdin``). + To send logs to a program's standard input, you need to set :ref:`log.to ` to ``pipe``. + + **Example** + + In the example below, Tarantool writes logs to the standard input of ``cronolog``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml + :language: yaml + :start-at: log: + :end-at: tarantool.log + :dedent: + + Example on GitHub: `log_pipe `_. + + | + | Type: string + | Default: :ref:`box.NULL ` + | Environment variable: TT_LOG_PIPE + + +.. _configuration_reference_log_syslog: + +log.syslog.* +~~~~~~~~~~~~ + +.. _configuration_reference_log_syslog-facility: + +.. confval:: log.syslog.facility + + Specify the syslog facility to be used when syslog is enabled. + To write logs to syslog, you need to set :ref:`log.to ` to ``syslog``. + + | + | Type: string + | Possible values: 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'security', 'syslog', 'user', 'uucp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7' + | Default: 'local7' + | Environment variable: TT_LOG_SYSLOG_FACILITY + +.. _configuration_reference_log_syslog-identity: + +.. confval:: log.syslog.identity + + Specify an application name used to identify Tarantool messages in syslog logs. + To write logs to syslog, you need to set :ref:`log.to ` to ``syslog``. + + | + | Type: string + | Default: 'tarantool' + | Environment variable: TT_LOG_SYSLOG_IDENTITY + +.. _configuration_reference_log_syslog-server: + +.. confval:: log.syslog.server + + Set a location of a syslog server. + This option accepts one of the following values: + + * An IPv4 address. Example: ``127.0.0.1:514``. + * A Unix socket path starting with ``unix:``. Examples: ``unix:/dev/log`` on Linux or ``unix:/var/run/syslog`` on macOS. + + To write logs to syslog, you need to set :ref:`log.to ` to ``syslog``. + + **Example** + + In the example below, Tarantool writes logs to a syslog server that listens for logging messages on the ``127.0.0.1:514`` address: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml + :language: yaml + :start-at: log: + :end-at: 127.0.0.1:514 + :dedent: + + Example on GitHub: `log_syslog `_. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_LOG_SYSLOG_SERVER + + + + .. _configuration_reference_memtx: memtx diff --git a/doc/reference/reference_lua/log.rst b/doc/reference/reference_lua/log.rst index f3ed55052b..97d9615f87 100644 --- a/doc/reference/reference_lua/log.rst +++ b/doc/reference/reference_lua/log.rst @@ -62,41 +62,53 @@ Below is a list of all ``log`` functions. Configure logging options. The following options are available: - * ``level``: Specifies the level of detail the log has. + * ``level``: Specify the level of detail the log has. - Learn more: :ref:`log_level `. + The example below shows how to set the log level to ``verbose``: - * ``log``: Specifies where to send the log's output, for example, - to a file, pipe, or system logger. + .. literalinclude:: /code_snippets/test/logging/log_test.lua + :language: lua + :start-at: local log = require + :end-at: log.cfg + :dedent: - Learn more: :ref:`log `. + See also: :ref:`log.level `. - * ``nonblock``: If **true**, Tarantool does not block during logging when the system - is not ready for writing, and drops the message instead. + * ``log``: Specify where to send the log's output, for example, to a file, pipe, or system logger. - Learn more: :ref:`log_nonblock `. + **Example 1: sending the log to the tarantool.log file** - * ``format``: Specifies the log format: 'plain' or 'json'. + .. code-block:: lua - Learn more: :ref:`log_format `. + log.cfg { log = 'tarantool.log' } - * ``modules``: Configures the specified log levels for different modules. + **Example 2: sending the log to a pipe** - Learn more: :ref:`log_modules `. + .. code-block:: lua - The example below shows how to set the log level to 'debug' and how to send the resulting log - to the 'tarantool.log' file: + log.cfg { log = '| cronolog tarantool.log' } - .. code-block:: lua + **Example 3: sending the log to syslog** - log = require('log') - log.cfg{ level='debug', log='tarantool.log'} + .. code-block:: lua - .. NOTE:: + log.cfg { log = 'syslog:server=unix:/dev/log' } + + See also: :ref:`log.to `. + + * ``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 `. + + * ``format``: Specify the log format: 'plain' or 'json'. + + See also: :ref:`log.format `. + + * ``modules``: Configure the specified log levels for different modules. + + See also: :ref:`log.modules `. - Note that calling ``log.cfg()`` before ``box.cfg()`` takes into account - logging options specified using :ref:`environment variables `, - such as ``TT_LOG`` and ``TT_LOG_LEVEL``. .. _log-ug_message: @@ -108,13 +120,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 ` property description. + :ref:`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 +138,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 +162,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 `. + the called function is less than :ref:`log.level `. .. _log-pid: @@ -171,33 +187,37 @@ Below is a list of all ``log`` functions. **Since:** :doc:`2.11.0 ` Create a new logger with the specified name. - You can configure a specific log level for a new logger using the :ref:`log_modules ` configuration property. + You can configure a specific log level for a new logger using the :ref:`log.modules ` configuration property. :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 `_.