From ed0a1cc9049a49efadf288462786882392773801 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Thu, 18 Jan 2024 12:49:13 +0300 Subject: [PATCH 1/8] flightrec: update the topic * Add `flightrec` reference section (YAML) * Update the Flight Recorder page --- .../instances.enabled/flightrec/config.yaml | 11 + .../instances.enabled/flightrec/instances.yml | 1 + doc/enterprise/flight_recorder.rst | 195 ++---------------- .../configuration/configuration_reference.rst | 184 +++++++++++++++++ doc/release/3.0.0.rst | 5 +- 5 files changed, 220 insertions(+), 176 deletions(-) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/flightrec/instances.yml diff --git a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml new file mode 100644 index 0000000000..068979476d --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml @@ -0,0 +1,11 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + flightrec: + enabled: true \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/flightrec/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/flightrec/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/enterprise/flight_recorder.rst b/doc/enterprise/flight_recorder.rst index ce3f6cbac2..ee1a25a49e 100644 --- a/doc/enterprise/flight_recorder.rst +++ b/doc/enterprise/flight_recorder.rst @@ -3,36 +3,40 @@ Flight recorder =============== +**Example on GitHub**: `flightrec `_ + The flight recorder available in the Enterprise Edition is an event collection tool that gathers various information about a working Tarantool instance, such as: * logs - * metrics - * requests and responses This information helps you investigate incidents related to :ref:`crashing ` a Tarantool instance. -.. _enable: +.. _enterprise-flight-recorder_enable: Enabling the flight recorder ---------------------------- The flight recorder is disabled by default and can be enabled and configured for a specific Tarantool instance. -To enable the flight recorder, set the ``flightrec_enabled`` -:doc:`configuration option ` to ``true``. -This option is :ref:`dynamic ` and can be changed at runtime by calling ``box.cfg{}``: +To enable the flight recorder, set the :ref:`flightrec.enabled ` +configuration option to ``true``. This option is dynamic and can be changed at runtime. -.. code-block:: lua +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/flightrec/config.yaml + :language: yaml + :start-at: flightrec: + :end-at: enabled: true + :dedent: - box.cfg{ flightrec_enabled = true } After ``flightrec_enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. This file is stored in the :ref:`memtx_dir ` directory. +By default, the directory is ``var/log/{{ instance_name }}/.ttfr``. + If the instance crashes and reboots, Tarantool rotates the flight recording: ``current.ttfr`` is renamed to ``.ttfr`` (for example, ``20230411T050721.ttfr``) and the new ``current.ttfr`` file is created for collecting data. @@ -44,175 +48,16 @@ Tarantool continues writing to the existing ``current.ttfr`` file after restart. Note that old flight recordings should be removed manually. +See also: :ref:`Flight recorder configuration options `. -.. _config: - -Configuration -------------- - -This section describes options related to the flight recorder configuration. -Note that all options are :ref:`dynamic ` and can be changed at runtime. - -.. TODO not implemented yet - .. _config-directory: - - Flight recording directory - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. _cfg_flightrec_dir: - - .. confval:: flightrec_dir - - Specifies the directory used to store flight recordings (``*.ttfr`` files). - - | Type: string - | Default: :ref:`memtx_dir ` - | Environment variable: TT_FLIGHTREC_DIR - - - -.. _config-logs: - -Logs -~~~~ - -This section describes the flight recorder settings related to :ref:`logging `. -For example, you can configure a more detailed logging level in the flight recorder for deeper analysis. - -* :ref:`flightrec_logs_size ` -* :ref:`flightrec_logs_max_msg_size ` -* :ref:`flightrec_logs_log_level ` - -.. _cfg_flightrec_logs_size: - -.. confval:: flightrec_logs_size - - Specifies the size (in bytes) of the log storage. - You can set this option to ``0`` to disable the log storage. - - | Type: integer - | Default: 10485760 - | Environment variable: TT_FLIGHTREC_LOGS_SIZE - - -.. _cfg_flightrec_logs_max_msg_size: - -.. confval:: flightrec_logs_max_msg_size - - Specifies the maximum size (in bytes) of the log message. - The log message is truncated if its size exceeds this limit. - - | Type: integer - | Default: 4096 - | Maximum: 16384 - | Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE - - -.. _cfg_flightrec_logs_log_level: - -.. confval:: flightrec_logs_log_level - - Specifies the level of detail the log has. - You can learn more about log levels from the :ref:`log_level ` - option description. - Note that the ``flightrec_logs_log_level`` value might differ from ``log_level``. - - | Type: integer - | Default: 6 - | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL - - -.. _config-metrics: - -Metrics -~~~~~~~ - -This section describes the flight recorder settings related to collecting -:ref:`metrics `. - -* :ref:`flightrec_metrics_period ` -* :ref:`flightrec_metrics_interval ` - -.. _cfg_flightrec_metrics_period: - -.. confval:: flightrec_metrics_period - - Specifies the time period (in seconds) that defines how long metrics are stored from the moment of dump. - So, this value defines how much historical metrics data is collected up to the moment of crash. - The frequency of metric dumps is defined by :ref:`flightrec_metrics_interval `. - - | Type: integer - | Default: 180 - | Environment variable: TT_FLIGHTREC_METRICS_PERIOD - - -.. _cfg_flightrec_metrics_interval: - -.. confval:: flightrec_metrics_interval - - Specifies the time interval (in seconds) that defines the frequency of dumping metrics. - This value shouldn't exceed :ref:`flightrec_metrics_period `. - - | Type: number - | Default: 1.0 - | Minimum: 0.001 - | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL - -.. NOTE:: - - Given that the average size of a metrics entry is 2 kB, - you can estimate the size of the metrics storage as follows: - - .. code-block:: console - - (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB - - - -.. _config-requests: - -Requests -~~~~~~~~ - -This section lists the flight recorder settings related to -storing the :ref:`request and response ` data. - -* :ref:`flightrec_requests_size ` -* :ref:`flightrec_requests_max_req_size ` -* :ref:`flightrec_requests_max_res_size ` - -.. _cfg_flightrec_requests_size: - -.. confval:: flightrec_requests_size - - Specifies the size (in bytes) of storage for the request and response data. - You can set this parameter to ``0`` to disable a storage of requests and responses. - - | Type: integer - | Default: 10485760 - | Environment variable: TT_FLIGHTREC_REQUESTS_SIZE - - - -.. _cfg_flightrec_requests_max_req_size: - -.. confval:: flightrec_requests_max_req_size - - Specifies the maximum size (in bytes) of a request entry. - A request entry is truncated if this size is exceeded. - - | Type: integer - | Default: 16384 - | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE - +Reading flight recordings +------------------------- -.. _cfg_flightrec_requests_max_res_size: +Since:** :doc:`3.0.0 ` version, you can read flight recordings using the API provided by the +``flightrec`` module. To open and read ``*.ttfr`` files, use the Lua API: -.. confval:: flightrec_requests_max_res_size +.. include:: /release/3.0.0.rst + :start-after: 3-0-flight-recorder-begin + :end-before: 3-0-flight-recorder-end - Specifies the maximum size (in bytes) of a response entry. - A response entry is truncated if this size is exceeded. - | Type: integer - | Default: 16384 - | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index ccca9d8a5f..3606201086 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -492,8 +492,192 @@ The ``database`` section defines database-specific configuration parameters, suc | Default: false | Environment variable: TT_DATABASE_USE_MVCC_ENGINE +.. _configuration_reference_flightrec: +flightrec +--------- +.. admonition:: Enterprise Edition + :class: fact + + Configuring ``flightrec`` parameters is available in the `Enterprise Edition `_ only. + + +The ``flightrec`` section describes options related to the :ref:`flight recorder ` configuration. +Note that all options are dynamic and can be changed at runtime. + +.. NOTE:: + + ``flightrec`` can be defined in any :ref:`scope `. + +To enable flight recorder, set the ``flightrec.enabled`` option to ``true`. + +.. _configuration_reference_flightrec_enabled: + +.. confval:: flightrec.enabled + + Whether the :ref:`flight recorder ` is enabled. + + | Type: boolean + | Default: false + | Environment variable: TT_FLIGHTREC_ENABLED + + +.. TODO not implemented yet + .. _config-directory: + + .. _configuration_reference_flightrec_dir: + + .. confval:: flightrec.dir + + Specify the directory used to store flight recordings (``*.ttfr`` files). + + | Type: string + | Default: :ref:`memtx_dir ` + | Environment variable: TT_FLIGHTREC_DIR + + +.. _configuration_reference_flightrec_logs: + +Logs +~~~~ + +This section describes the flight recorder settings related to :ref:`logging `. +For example, you can configure a more detailed logging level in the flight recorder for deeper analysis. + +* :ref:`flightrec.logs_size ` +* :ref:`flightrec.logs_max_msg_size ` +* :ref:`flightrec.logs_log_level ` + +.. _configuration_reference_flightrec_logs_size: + +.. confval:: flightrec.logs_size + + Specify the size (in bytes) of the log storage. + You can set this option to ``0`` to disable the log storage. + + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_LOGS_SIZE + +.. _configuration_reference_flightrec_logs_max_msg_size: + +.. confval:: flightrec.logs_max_msg_size + + Specify the maximum size (in bytes) of the log message. + The log message is truncated if its size exceeds this limit. + + | Type: integer + | Default: 4096 + | Maximum: 16384 + | Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE + + +.. _configuration_reference_flightrec_logs_log_level: + +.. confval:: flightrec.logs_log_level + + Specify the level of detail the log has. + You can learn more about log levels from the :ref:`log_level ` + option description. + Note that the ``flightrec.logs_log_level`` value might differ from ``log_level``. + + | Type: integer + | Default: 6 + | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL + +.. _configuration_reference_flightrec_metrics: + +Metrics +~~~~~~~ + +This section describes the flight recorder settings related to collecting +:ref:`metrics `. + +* :ref:`flightrec.metrics_period ` +* :ref:`flightrec.metrics_interval ` + +.. _configuration_reference_flightrec_metrics_period: + +.. confval:: flightrec.metrics_period + + Specify the time period (in seconds) that defines how long metrics are stored from the moment of dump. + So, this value defines how much historical metrics data is collected up to the moment of crash. + The frequency of metric dumps is defined by :ref:`flightrec.metrics_interval `. + + | Type: integer + | Default: 180 + | Environment variable: TT_FLIGHTREC_METRICS_PERIOD + + +.. _configuration_reference_flightrec_metrics_interval: + +.. confval:: flightrec.metrics_interval + + Specify the time interval (in seconds) that defines the frequency of dumping metrics. + This value shouldn't exceed :ref:`flightrec.metrics_period `. + + | Type: number + | Default: 1.0 + | Minimum: 0.001 + | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL + +.. NOTE:: + + Given that the average size of a metrics entry is 2 kB, + you can estimate the size of the metrics storage as follows: + + .. code-block:: console + + (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB + + +.. _configuration_reference_flightrec_requests: + +Requests +~~~~~~~~ + +This section lists the flight recorder settings related to +storing the :ref:`request and response ` data. + +* :ref:`flightrec.requests_size ` +* :ref:`flightrec.requests_max_req_size ` +* :ref:`flightrec.requests_max_res_size ` + +.. _configuration_reference_flightrec_requests_size: + +.. confval:: flightrec.requests_size + + Specify the size (in bytes) of storage for the request and response data. + You can set this parameter to ``0`` to disable a storage of requests and responses. + + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_REQUESTS_SIZE + + +.. _configuration_reference_flightrec_requests_max_req_size: + +.. confval:: flightrec.requests_max_req_size + + Specify the maximum size (in bytes) of a request entry. + A request entry is truncated if this size is exceeded. + + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE + + +.. _configuration_reference_flightrec_requests_max_res_size: + +.. confval:: flightrec.requests_max_res_size + + Specify the maximum size (in bytes) of a response entry. + A response entry is truncated if this size is exceeded. + + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE .. _configuration_reference_iproto: diff --git a/doc/release/3.0.0.rst b/doc/release/3.0.0.rst index bb6415b794..1da9842881 100644 --- a/doc/release/3.0.0.rst +++ b/doc/release/3.0.0.rst @@ -316,13 +316,15 @@ To enable the flight recorder in a YAML file, set ``flightrec.enabled`` to true: Then, you can use the Lua API to open and read ``*.ttfr`` files: +.. _3-0-flight-recorder-begin: + .. code-block:: tarantoolsession app:instance001> flightrec = require('flightrec') --- ... - app:instance001> flightrec_file = flightrec.open('var/lib/instance001/20231225T085435.ttfr') + app:instance001> flightrec_file = flightrec.open('var/lib/instance001/current.ttfr') --- ... @@ -360,6 +362,7 @@ Then, you can use the Lua API to open and read ``*.ttfr`` files: --- ... +.. _3-0-flight-recorder-end: From 1f9ad1d6ad8c85c3e660bf091b5535d05331d76f Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Tue, 23 Jan 2024 18:58:13 +0300 Subject: [PATCH 2/8] flightrec: add review fixes --- .../instances.enabled/flightrec/config.yaml | 7 ++- doc/enterprise/flight_recorder.rst | 39 +++++++----- .../configuration/configuration_reference.rst | 62 +++++-------------- doc/release/3.0.0.rst | 11 ++-- 4 files changed, 54 insertions(+), 65 deletions(-) diff --git a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml index 068979476d..82607aa5af 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml @@ -8,4 +8,9 @@ groups: listen: - uri: '127.0.0.1:3301' flightrec: - enabled: true \ No newline at end of file + enabled: true + logs_size: 10485800 + logs_log_level: 5 + metrics_period: 240 + metrics_interval: 0.5 + requests_size: 10485780 diff --git a/doc/enterprise/flight_recorder.rst b/doc/enterprise/flight_recorder.rst index ee1a25a49e..ec6640b683 100644 --- a/doc/enterprise/flight_recorder.rst +++ b/doc/enterprise/flight_recorder.rst @@ -1,4 +1,4 @@ -.. _enterprise-flight-recorder: +.. _enterprise-flight-recorder: Flight recorder =============== @@ -15,7 +15,6 @@ gathers various information about a working Tarantool instance, such as: This information helps you investigate incidents related to :ref:`crashing ` a Tarantool instance. - .. _enterprise-flight-recorder_enable: Enabling the flight recorder @@ -24,9 +23,9 @@ Enabling the flight recorder The flight recorder is disabled by default and can be enabled and configured for a specific Tarantool instance. To enable the flight recorder, set the :ref:`flightrec.enabled ` -configuration option to ``true``. This option is dynamic and can be changed at runtime. +configuration option to ``true``. -.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/flightrec/config.yaml +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/flightrec/config.yaml :language: yaml :start-at: flightrec: :end-at: enabled: true @@ -34,7 +33,7 @@ configuration option to ``true``. This option is dynamic and can be changed at r After ``flightrec_enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. -This file is stored in the :ref:`memtx_dir ` directory. +This file is stored in the ``memtx.dir`` directory. By default, the directory is ``var/log/{{ instance_name }}/.ttfr``. If the instance crashes and reboots, Tarantool rotates the flight recording: @@ -43,21 +42,33 @@ and the new ``current.ttfr`` file is created for collecting data. In the case of correct shutdown (for example, using ``os.exit()``), Tarantool continues writing to the existing ``current.ttfr`` file after restart. -.. NOTE:: +.. NOTE:: Note that old flight recordings should be removed manually. -See also: :ref:`Flight recorder configuration options `. +.. _enterprise-flight-recorder_configure: + +Configuring a flight recorder +----------------------------- + +When the flight recorder is enabled, you can set the options related to :ref:`logging `, +:ref:`metrics `, and storing the :ref:`request and response ` data. -Reading flight recordings -------------------------- +The ``flightrec`` configuration might look as follows: -Since:** :doc:`3.0.0 ` version, you can read flight recordings using the API provided by the -``flightrec`` module. To open and read ``*.ttfr`` files, use the Lua API: +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/flightrec/config.yaml + :language: yaml + :start-at: flightrec: + :end-at: 10485780 + :dedent: -.. include:: /release/3.0.0.rst - :start-after: 3-0-flight-recorder-begin - :end-before: 3-0-flight-recorder-end +In the configuration, the following options are set: +* :ref:`flightrec.logs_size ` -- a log storage size in bytes +* :ref:`flightrec.logs_log_level ` -- a :ref:`log_level ` +* :ref:`flightrec.metrics_period ` -- the number of seconds to store metrics after the dump +* :ref:`flightrec.metrics_interval ` -- the frequency of metrics dumps in seconds +* :ref:`flightrec.requests_size ` -- a storage size for the request and response data in bytes +Read more: :ref:`Flight recorder configuration options `. diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 3606201086..ecfde80a77 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -502,21 +502,27 @@ flightrec Configuring ``flightrec`` parameters is available in the `Enterprise Edition `_ only. - The ``flightrec`` section describes options related to the :ref:`flight recorder ` configuration. -Note that all options are dynamic and can be changed at runtime. .. NOTE:: ``flightrec`` can be defined in any :ref:`scope `. -To enable flight recorder, set the ``flightrec.enabled`` option to ``true`. +* :ref:`flightrec.enabled ` +* :ref:`flightrec.logs_size ` +* :ref:`flightrec.logs_max_msg_size ` +* :ref:`flightrec.logs_log_level ` +* :ref:`flightrec.metrics_period ` +* :ref:`flightrec.metrics_interval ` +* :ref:`flightrec.requests_size ` +* :ref:`flightrec.requests_max_req_size ` +* :ref:`flightrec.requests_max_res_size ` .. _configuration_reference_flightrec_enabled: .. confval:: flightrec.enabled - Whether the :ref:`flight recorder ` is enabled. + Enable the :ref:`flight recorder `. | Type: boolean | Default: false @@ -533,22 +539,10 @@ To enable flight recorder, set the ``flightrec.enabled`` option to ``true`. Specify the directory used to store flight recordings (``*.ttfr`` files). | Type: string - | Default: :ref:`memtx_dir ` + | Default: memtx.dir | Environment variable: TT_FLIGHTREC_DIR -.. _configuration_reference_flightrec_logs: - -Logs -~~~~ - -This section describes the flight recorder settings related to :ref:`logging `. -For example, you can configure a more detailed logging level in the flight recorder for deeper analysis. - -* :ref:`flightrec.logs_size ` -* :ref:`flightrec.logs_max_msg_size ` -* :ref:`flightrec.logs_log_level ` - .. _configuration_reference_flightrec_logs_size: .. confval:: flightrec.logs_size @@ -578,6 +572,7 @@ For example, you can configure a more detailed logging level in the flight recor .. confval:: flightrec.logs_log_level Specify the level of detail the log has. + The default value is 6 (``VERBOSE``). You can learn more about log levels from the :ref:`log_level ` option description. Note that the ``flightrec.logs_log_level`` value might differ from ``log_level``. @@ -586,17 +581,6 @@ For example, you can configure a more detailed logging level in the flight recor | Default: 6 | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL -.. _configuration_reference_flightrec_metrics: - -Metrics -~~~~~~~ - -This section describes the flight recorder settings related to collecting -:ref:`metrics `. - -* :ref:`flightrec.metrics_period ` -* :ref:`flightrec.metrics_interval ` - .. _configuration_reference_flightrec_metrics_period: .. confval:: flightrec.metrics_period @@ -622,27 +606,15 @@ This section describes the flight recorder settings related to collecting | Minimum: 0.001 | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL -.. NOTE:: - - Given that the average size of a metrics entry is 2 kB, - you can estimate the size of the metrics storage as follows: + .. NOTE:: - .. code-block:: console + Given that the average size of a metrics entry is 2 kB, + you can estimate the size of the metrics storage as follows: - (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB + .. code-block:: console + (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB -.. _configuration_reference_flightrec_requests: - -Requests -~~~~~~~~ - -This section lists the flight recorder settings related to -storing the :ref:`request and response ` data. - -* :ref:`flightrec.requests_size ` -* :ref:`flightrec.requests_max_req_size ` -* :ref:`flightrec.requests_max_res_size ` .. _configuration_reference_flightrec_requests_size: diff --git a/doc/release/3.0.0.rst b/doc/release/3.0.0.rst index 1da9842881..b0115ee35a 100644 --- a/doc/release/3.0.0.rst +++ b/doc/release/3.0.0.rst @@ -309,10 +309,11 @@ With the 3.0 version, you can read flight recordings using the API provided by t To enable the flight recorder in a YAML file, set ``flightrec.enabled`` to true: -.. code-block:: yaml - - flightrec: - enabled: true +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/flightrec/config.yaml + :language: yaml + :start-at: flightrec: + :end-at: enabled: true + :dedent: Then, you can use the Lua API to open and read ``*.ttfr`` files: @@ -324,7 +325,7 @@ Then, you can use the Lua API to open and read ``*.ttfr`` files: --- ... - app:instance001> flightrec_file = flightrec.open('var/lib/instance001/current.ttfr') + app:instance001> flightrec_file = flightrec.open('var/lib/instance001/20231225T085435.ttfr') --- ... From 2d258ac4c236be25b28538135b8bd4f90c168249 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Tue, 23 Jan 2024 19:04:25 +0300 Subject: [PATCH 3/8] Add minor fixes (cfg reference) --- .../configuration/cfg_authentication.rst | 8 ++++---- .../configuration/cfg_flight_recorder.rst | 16 +++++++-------- doc/reference/configuration/cfg_logging.rst | 20 +++++++++---------- .../configuration/cfg_replication.rst | 10 +++++----- doc/reference/configuration/cfg_storage.rst | 4 ++-- 5 files changed, 29 insertions(+), 29 deletions(-) diff --git a/doc/reference/configuration/cfg_authentication.rst b/doc/reference/configuration/cfg_authentication.rst index 5cb8bdcae7..d1bba787ec 100644 --- a/doc/reference/configuration/cfg_authentication.rst +++ b/doc/reference/configuration/cfg_authentication.rst @@ -24,7 +24,7 @@ Since :doc:`2.11.0 `. - Specifies a period of time (in seconds) that a specific user should wait + Specify a period of time (in seconds) that a specific user should wait for the next attempt after failed authentication. With the configuration below, Tarantool refuses the authentication attempt if the previous @@ -105,7 +105,7 @@ Since :doc:`2.11.0 `. - Specifies the minimum number of characters for a password. + Specify the minimum number of characters for a password. The following example shows how to set the minimum password length to 10. @@ -181,7 +181,7 @@ Since :doc:`2.11.0 `. - Specifies the maximum period of time (in days) a user can use the same password. + Specify the maximum period of time (in days) a user can use the same password. When this period ends, a user gets the "Password expired" error on a login attempt. To restore access for such users, use :doc:`box.schema.user.passwd `. @@ -207,7 +207,7 @@ Since :doc:`2.11.0 `. - Specifies the number of unique new user passwords before an old password can be reused. + Specify the number of unique new user passwords before an old password can be reused. In the example below, a new password should differ from the last three passwords. diff --git a/doc/reference/configuration/cfg_flight_recorder.rst b/doc/reference/configuration/cfg_flight_recorder.rst index 36c333db0d..b5664dbc4c 100644 --- a/doc/reference/configuration/cfg_flight_recorder.rst +++ b/doc/reference/configuration/cfg_flight_recorder.rst @@ -36,7 +36,7 @@ Since :doc:`2.11.0 `. - Specifies the size (in bytes) of the log storage. + Specify the size (in bytes) of the log storage. You can set this option to ``0`` to disable the log storage. | Type: integer @@ -51,7 +51,7 @@ Since :doc:`2.11.0 `. - Specifies the maximum size (in bytes) of the log message. + Specify the maximum size (in bytes) of the log message. The log message is truncated if its size exceeds this limit. | Type: integer @@ -67,7 +67,7 @@ Since :doc:`2.11.0 `. - Specifies the level of detail the log has. + Specify the level of detail the log has. You can learn more about log levels from the :ref:`log_level ` option description. Note that the ``flightrec_logs_log_level`` value might differ from ``log_level``. @@ -84,7 +84,7 @@ Since :doc:`2.11.0 `. - Specifies the time period (in seconds) that defines how long metrics are stored from the moment of dump. + Specify the time period (in seconds) that defines how long metrics are stored from the moment of dump. So, this value defines how much historical metrics data is collected up to the moment of crash. The frequency of metric dumps is defined by :ref:`flightrec_metrics_interval `. @@ -100,7 +100,7 @@ Since :doc:`2.11.0 `. - Specifies the time interval (in seconds) that defines the frequency of dumping metrics. + Specify the time interval (in seconds) that defines the frequency of dumping metrics. This value shouldn't exceed :ref:`flightrec_metrics_period `. .. NOTE:: @@ -125,7 +125,7 @@ Since :doc:`2.11.0 `. - Specifies the size (in bytes) of storage for the request and response data. + Specify the size (in bytes) of storage for the request and response data. You can set this parameter to ``0`` to disable a storage of requests and responses. | Type: integer @@ -141,7 +141,7 @@ Since :doc:`2.11.0 `. - Specifies the maximum size (in bytes) of a request entry. + Specify the maximum size (in bytes) of a request entry. A request entry is truncated if this size is exceeded. | Type: integer @@ -156,7 +156,7 @@ Since :doc:`2.11.0 `. - Specifies the maximum size (in bytes) of a response entry. + Specify the maximum size (in bytes) of a response entry. A response entry is truncated if this size is exceeded. | Type: integer diff --git a/doc/reference/configuration/cfg_logging.rst b/doc/reference/configuration/cfg_logging.rst index 4a738f39ec..f58809ca67 100644 --- a/doc/reference/configuration/cfg_logging.rst +++ b/doc/reference/configuration/cfg_logging.rst @@ -11,21 +11,21 @@ application. * :ref:`log_format ` * :ref:`log_modules ` -.. _cfg_logging-log_level: +.. _cfg_logging-log_level: -.. confval:: log_level +.. confval:: log_level Since version 1.6.2. - Specifies the level of detail the :ref:`log ` has. There are seven levels: + Specify the level of detail the :ref:`log ` has. There are seven levels: - * 1 – ``SYSERROR`` - * 2 – ``ERROR`` - * 3 – ``CRITICAL`` - * 4 – ``WARNING`` - * 5 – ``INFO`` - * 6 – ``VERBOSE`` - * 7 – ``DEBUG`` + * 1 -- ``SYSERROR`` + * 2 -- ``ERROR`` + * 3 -- ``CRITICAL`` + * 4 -- ``WARNING`` + * 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 diff --git a/doc/reference/configuration/cfg_replication.rst b/doc/reference/configuration/cfg_replication.rst index c71d9c4dcc..a4a2cbfeea 100644 --- a/doc/reference/configuration/cfg_replication.rst +++ b/doc/reference/configuration/cfg_replication.rst @@ -240,7 +240,7 @@ Since :doc:`2.11.0 `. - Specifies a strategy used to bootstrap a :ref:`replica set `. + Specify a strategy used to bootstrap a :ref:`replica set `. The following strategies are available: * ``auto``: a node doesn't boot if a half or more of other nodes in a replica set are not connected. @@ -291,7 +291,7 @@ This option is in effect if :ref:`bootstrap_strategy ` is set to ``legacy``. - Specifies the number of nodes to be up and running to start a replica set. + Specify the number of nodes to be up and running to start a replica set. This parameter has effect during :ref:`bootstrap ` or :ref:`configuration update `. Setting ``replication_connect_quorum`` to ``0`` makes Tarantool @@ -580,7 +580,7 @@ Since version :doc:`2.6.1 `. - Specifies the role of a replica set node in the + Specify the role of a replica set node in the :ref:`leader election process `. Possible values: @@ -630,7 +630,7 @@ Since version :doc:`2.6.1 `. - Specifies the timeout between election rounds in the + Specify the timeout between election rounds in the :ref:`leader election process ` if the previous round ended up with a split-vote. @@ -664,7 +664,7 @@ In earlier Tarantool versions, use :ref:`election_fencing_enabled ` instead. - Specifies the :ref:`leader fencing mode ` that + Specify the :ref:`leader fencing mode ` that affects the leader election process. When the parameter is set to ``soft`` or ``strict``, the leader resigns its leadership if it has less than :ref:`replication_synchro_quorum ` diff --git a/doc/reference/configuration/cfg_storage.rst b/doc/reference/configuration/cfg_storage.rst index 78d1e624d5..c7c743c930 100644 --- a/doc/reference/configuration/cfg_storage.rst +++ b/doc/reference/configuration/cfg_storage.rst @@ -72,7 +72,7 @@ Since version :doc:`2.10.0 `. - Specifies the allocator used for memtx tuples. + Specify the allocator used for memtx tuples. The possible values are ``system`` and ``small``: * ``system`` is based on the ``malloc`` function. @@ -109,7 +109,7 @@ Since version :doc:`2.8.1 `. - Specifies the granularity (in bytes) of memory allocation in the :ref:`small allocator `. + Specify the granularity (in bytes) of memory allocation in the :ref:`small allocator `. The value of ``slab_alloc_granularity`` should be a power of two and should be greater than or equal to 4. Below are few recommendations on how to adjust the ``slab_alloc_granularity`` value: From a6ac57ec74a4c9ffcff46e7326fe6761c8306f3e Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Tue, 23 Jan 2024 19:13:09 +0300 Subject: [PATCH 4/8] Add minor fix --- doc/enterprise/flight_recorder.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/enterprise/flight_recorder.rst b/doc/enterprise/flight_recorder.rst index ec6640b683..0997918ea5 100644 --- a/doc/enterprise/flight_recorder.rst +++ b/doc/enterprise/flight_recorder.rst @@ -63,7 +63,7 @@ The ``flightrec`` configuration might look as follows: :end-at: 10485780 :dedent: -In the configuration, the following options are set: +In the example, the following options are set: * :ref:`flightrec.logs_size ` -- a log storage size in bytes * :ref:`flightrec.logs_log_level ` -- a :ref:`log_level ` From 47806896909b0306d677c7d0c09dc134a1abdbdb Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Wed, 24 Jan 2024 10:51:58 +0300 Subject: [PATCH 5/8] flightrec: add review fixes --- .../config/instances.enabled/flightrec/config.yaml | 14 +++++++------- doc/enterprise/flight_recorder.rst | 10 +++++----- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml index 82607aa5af..739824c6b9 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml @@ -7,10 +7,10 @@ groups: iproto: listen: - uri: '127.0.0.1:3301' - flightrec: - enabled: true - logs_size: 10485800 - logs_log_level: 5 - metrics_period: 240 - metrics_interval: 0.5 - requests_size: 10485780 + flightrec: + enabled: true + logs_size: 10485800 + logs_log_level: 5 + metrics_period: 240 + metrics_interval: 0.5 + requests_size: 10485780 diff --git a/doc/enterprise/flight_recorder.rst b/doc/enterprise/flight_recorder.rst index 0997918ea5..89349cc113 100644 --- a/doc/enterprise/flight_recorder.rst +++ b/doc/enterprise/flight_recorder.rst @@ -65,10 +65,10 @@ The ``flightrec`` configuration might look as follows: In the example, the following options are set: -* :ref:`flightrec.logs_size ` -- a log storage size in bytes -* :ref:`flightrec.logs_log_level ` -- a :ref:`log_level ` -* :ref:`flightrec.metrics_period ` -- the number of seconds to store metrics after the dump -* :ref:`flightrec.metrics_interval ` -- the frequency of metrics dumps in seconds -* :ref:`flightrec.requests_size ` -- a storage size for the request and response data in bytes +* :ref:`flightrec.logs_size ` -- a log storage size in bytes. +* :ref:`flightrec.logs_log_level ` -- a :ref:`log_level `. +* :ref:`flightrec.metrics_period ` -- the number of seconds to store metrics after the dump. +* :ref:`flightrec.metrics_interval ` -- the frequency of metrics dumps in seconds. +* :ref:`flightrec.requests_size ` -- a storage size for the request and response data in bytes. Read more: :ref:`Flight recorder configuration options `. From 4cf830a593143f665d5aab9a3d56bc304e4671a6 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Wed, 24 Jan 2024 11:05:28 +0300 Subject: [PATCH 6/8] flightrec: add review fixes --- doc/enterprise/flight_recorder.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/enterprise/flight_recorder.rst b/doc/enterprise/flight_recorder.rst index 89349cc113..b32ae7695e 100644 --- a/doc/enterprise/flight_recorder.rst +++ b/doc/enterprise/flight_recorder.rst @@ -33,8 +33,8 @@ configuration option to ``true``. After ``flightrec_enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. -This file is stored in the ``memtx.dir`` directory. -By default, the directory is ``var/log/{{ instance_name }}/.ttfr``. +This file is stored in the ``snapshot.dir`` directory. +By default, the directory is ``var/lib/{{ instance_name }}/.ttfr``. If the instance crashes and reboots, Tarantool rotates the flight recording: ``current.ttfr`` is renamed to ``.ttfr`` (for example, ``20230411T050721.ttfr``) From 32dc17e6fbc64b8217776525a0a3c6210aacf14a Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Wed, 24 Jan 2024 11:09:34 +0300 Subject: [PATCH 7/8] flightrec: add review fixes --- doc/reference/configuration/configuration_reference.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index ecfde80a77..d3a758a44e 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -539,7 +539,7 @@ The ``flightrec`` section describes options related to the :ref:`flight recorder Specify the directory used to store flight recordings (``*.ttfr`` files). | Type: string - | Default: memtx.dir + | Default: snapshot.dir | Environment variable: TT_FLIGHTREC_DIR From 385a647374f5a1d7e710435c9ab6ea2a11ba1cc4 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Wed, 24 Jan 2024 11:27:14 +0300 Subject: [PATCH 8/8] flightrec: add review fixes --- .../instances.enabled/flightrec/config.yaml | 15 ++++++++------- doc/enterprise/flight_recorder.rst | 2 +- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml index 739824c6b9..32f2552513 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml @@ -1,3 +1,11 @@ +flightrec: + enabled: true + logs_size: 10485800 + logs_log_level: 5 + metrics_period: 240 + metrics_interval: 0.5 + requests_size: 10485780 + groups: group001: replicasets: @@ -7,10 +15,3 @@ groups: iproto: listen: - uri: '127.0.0.1:3301' - flightrec: - enabled: true - logs_size: 10485800 - logs_log_level: 5 - metrics_period: 240 - metrics_interval: 0.5 - requests_size: 10485780 diff --git a/doc/enterprise/flight_recorder.rst b/doc/enterprise/flight_recorder.rst index b32ae7695e..36061b21bd 100644 --- a/doc/enterprise/flight_recorder.rst +++ b/doc/enterprise/flight_recorder.rst @@ -32,7 +32,7 @@ configuration option to ``true``. :dedent: -After ``flightrec_enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. +After ``flightrec.enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. This file is stored in the ``snapshot.dir`` directory. By default, the directory is ``var/lib/{{ instance_name }}/.ttfr``.