flightrec: review fixes

Author: xuniq

doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml

@@ -8,4 +8,8 @@ groups:
               listen:
               - uri: '127.0.0.1:3301'
               flightrec:
-                enabled: true
+                enabled: true
+                logs_size: 10485800
+                logs_log_level: 5
+                metrics_period: 240
+                requests_size: 10485760

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 <admin-disaster_recovery>` a Tarantool instance.
 
-
 .. _enterprise-flight-recorder_enable:
 
 Enabling the flight recorder
@@ -24,17 +23,16 @@ 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_reference_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
     :language: yaml
     :start-at: flightrec:
     :end-at: enabled: true
     :dedent:
 
-
 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 <cfg_basic-memtx_dir>` directory.
+This file is stored in the ``memtx.dir`` directory.
 By default, the directory is ``var/log/{{ instance_name }}/<file_name>.ttfr``.
 
 If the instance crashes and reboots, Tarantool rotates the flight recording:
@@ -43,21 +41,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 <configuration_reference_flightrec>`.
+.. _enterprise-flight-recorder_configure:
+
+Configuring the flight recorder
+-------------------------------
+
+When the flight recorder is enabled, you can set the options related to :ref:`logging <cfg_logging-log>`,
+:ref:`metrics <metrics-reference>`, and storing the :ref:`request and response <internals-requests_responses>` data.
 
-Reading flight recordings
--------------------------
+The ``flightrec`` configuration might look as follows:
 
-Since:** :doc:`3.0.0 </release/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/replication/instances.enabled/flightrec/config.yaml
+    :language: yaml
+    :start-at: flightrec:
+    :end-at:
+    :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 <configuration_reference_flightrec_logs_size>` -- a log storage size in bytes
+*   :ref:`flightrec.logs_log_level <configuration_reference_flightrec_logs_log_level>` -- a :ref:`log_level <cfg_logging-log_level>`
+*   :ref:`flightrec.metrics_period <configuration_reference_flightrec_metrics_period>` -- the number of seconds to store metrics after the dump
+*   :ref:`flightrec.metrics_interval <configuration_reference_flightrec_metrics_interval>` -- the frequency of metrics dumps
+*   :ref:`flightrec.metrics_interval <configuration_reference_flightrec_metrics_interval>` -- a storage size for the request and response data
 
+Read more: :ref:`Flight recorder configuration options <configuration_reference_flightrec>`.

doc/reference/configuration/configuration_reference.rst

@@ -502,21 +502,27 @@ flightrec
 
     Configuring ``flightrec`` parameters is available in the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
 
-
 The ``flightrec`` section describes options related to the :ref:`flight recorder <enterprise-flight-recorder>` configuration.
-Note that all options are dynamic and can be changed at runtime.
 
 ..  NOTE::
 
     ``flightrec`` can be defined in any :ref:`scope <configuration_scopes>`.
 
-To enable flight recorder, set the ``flightrec.enabled`` option to ``true`.
+* :ref:`flightrec.enabled <configuration_reference_flightrec_enabled>`
+* :ref:`flightrec.logs_size <configuration_reference_flightrec_logs_size>`
+* :ref:`flightrec.logs_max_msg_size <configuration_reference_flightrec_logs_max_msg_size>`
+* :ref:`flightrec.logs_log_level <configuration_reference_flightrec_logs_log_level>`
+* :ref:`flightrec.metrics_period <configuration_reference_flightrec_metrics_period>`
+* :ref:`flightrec.metrics_interval <configuration_reference_flightrec_metrics_interval>`
+* :ref:`flightrec.requests_size <configuration_reference_flightrec_requests_size>`
+* :ref:`flightrec.requests_max_req_size <configuration_reference_flightrec_requests_max_req_size>`
+* :ref:`flightrec.requests_max_res_size <configuration_reference_flightrec_requests_max_res_size>`
 
 ..  _configuration_reference_flightrec_enabled:
 
 ..  confval:: flightrec.enabled
 
-    Whether the :ref:`flight recorder <enterprise-flight-recorder>` is enabled.
+    Enable the :ref:`flight recorder <enterprise-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 <cfg_basic-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 <cfg_logging-log>`.
-For example, you can configure a more detailed logging level in the flight recorder for deeper analysis.
-
-* :ref:`flightrec.logs_size <configuration_reference_flightrec_logs_size>`
-* :ref:`flightrec.logs_max_msg_size <configuration_reference_flightrec_logs_max_msg_size>`
-* :ref:`flightrec.logs_log_level <configuration_reference_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 <cfg_logging-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 <metrics-reference>`.
-
-* :ref:`flightrec.metrics_period <configuration_reference_flightrec_metrics_period>`
-* :ref:`flightrec.metrics_interval <configuration_reference_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 <internals-requests_responses>` data.
-
-* :ref:`flightrec.requests_size <configuration_reference_flightrec_requests_size>`
-* :ref:`flightrec.requests_max_req_size <configuration_reference_flightrec_requests_max_req_size>`
-* :ref:`flightrec.requests_max_res_size <configuration_reference_flightrec_requests_max_res_size>`
 
 ..  _configuration_reference_flightrec_requests_size:
 

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/replication/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')
     ---
     ...