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..32f2552513 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml @@ -0,0 +1,17 @@ +flightrec: + enabled: true + logs_size: 10485800 + logs_log_level: 5 + metrics_period: 240 + metrics_interval: 0.5 + requests_size: 10485780 + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' 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..36061b21bd 100644 --- a/doc/enterprise/flight_recorder.rst +++ b/doc/enterprise/flight_recorder.rst @@ -1,218 +1,74 @@ -.. _enterprise-flight-recorder: +.. _enterprise-flight-recorder: 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``. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/flightrec/config.yaml + :language: yaml + :start-at: flightrec: + :end-at: enabled: true + :dedent: -.. code-block:: lua - 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 ``snapshot.dir`` directory. +By default, the directory is ``var/lib/{{ instance_name }}/.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 :ref:`memtx_dir ` directory. 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. 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. +.. _enterprise-flight-recorder_configure: -.. _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. +Configuring a flight recorder +----------------------------- - | Type: integer - | Default: 16384 - | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE +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. +The ``flightrec`` configuration might look as follows: -.. _cfg_flightrec_requests_max_res_size: +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/flightrec/config.yaml + :language: yaml + :start-at: flightrec: + :end-at: 10485780 + :dedent: -.. confval:: flightrec_requests_max_res_size +In the example, the following options are set: - Specifies the maximum size (in bytes) of a response entry. - A response entry is truncated if this size is exceeded. +* :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. - | Type: integer - | Default: 16384 - | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE +Read more: :ref:`Flight recorder configuration options `. 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: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index ccca9d8a5f..d3a758a44e 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -492,8 +492,164 @@ 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:: + + ``flightrec`` can be defined in any :ref:`scope `. + +* :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 + + Enable the :ref:`flight recorder `. + + | 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: snapshot.dir + | Environment variable: TT_FLIGHTREC_DIR + + +.. _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. + 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``. + + | Type: integer + | Default: 6 + | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL + +.. _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_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..b0115ee35a 100644 --- a/doc/release/3.0.0.rst +++ b/doc/release/3.0.0.rst @@ -309,13 +309,16 @@ 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: +.. _3-0-flight-recorder-begin: + .. code-block:: tarantoolsession app:instance001> flightrec = require('flightrec') @@ -360,6 +363,7 @@ Then, you can use the Lua API to open and read ``*.ttfr`` files: --- ... +.. _3-0-flight-recorder-end: