Document on_recovery_state and on_election (#3580)

andreyaksenov · web-flow · commit 95e06909bd57 · 2023-08-01T16:09:33.000+03:00
diff --git a/doc/code_snippets/test/triggers/on_recovery_state_test.lua b/doc/code_snippets/test/triggers/on_recovery_state_test.lua
@@ -0,0 +1,41 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+
+local run_before_cfg = [[
+    local log = require('log')
+    local log_recovery_state = function(state)
+        log.info(state .. ' state reached')
+    end
+    box.ctl.on_recovery_state(log_recovery_state)
+]]
+
+g.before_each(function(cg)
+    cg.server = server:new {
+        workdir = fio.cwd() .. '/tmp',
+        env = {
+            ['TARANTOOL_RUN_BEFORE_BOX_CFG'] = run_before_cfg,
+        }
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+local function find_in_log(cg, str, must_be_present)
+    t.helpers.retrying({timeout = 0.3, delay = 0.1}, function()
+        local found = cg.server:grep_log(str) ~= nil
+        t.assert(found == must_be_present)
+    end)
+end
+
+g.test_log_contains_reached_states = function(cg)
+    find_in_log(cg, 'indexes_built state reached', true)
+    find_in_log(cg, 'snapshot_recovered state reached', true)
+    find_in_log(cg, 'wal_recovered state reached', true)
+    find_in_log(cg, 'synced state reached', true)
+end
diff --git a/doc/dev_guide/internals/recovery_internals.rst b/doc/dev_guide/internals/recovery_internals.rst
@@ -4,7 +4,7 @@
 The recovery process
 --------------------------------------------------------------------------------
 
-The recovery process begins when box.cfg{} happens for the
+The recovery process begins when ``box.cfg{}`` happens for the
 first time after the Tarantool server instance starts.
 
 The recovery process must recover the databases
@@ -19,43 +19,48 @@ make a checkpoint, and the snapshot operation is rolled back if
 anything goes wrong, so vinyl's checkpoint is at least as fresh
 as the snapshot file.)
 
-Step 1
-    Read the configuration parameters in the ``box.cfg{}`` request.
-    Parameters which affect recovery may include :ref:`work_dir <cfg_basic-work_dir>`,
-    :ref:`wal_dir <cfg_basic-wal_dir>`, :ref:`memtx_dir <cfg_basic-memtx_dir>`,
-    :ref:`vinyl_dir <cfg_basic-vinyl_dir>`
-    and :ref:`force_recovery <cfg_binary_logging_snapshots-force_recovery>`.
-
-Step 2
-    Find the latest snapshot file. Use its data to reconstruct the in-memory
-    databases. Instruct the vinyl engine to recover to the latest checkpoint.
-
-    There are actually two variations of the reconstruction procedure for memtx
-    databases, depending on whether the recovery process is "default".
-
-    If the recovery process is default (``force_recovery`` is ``false``),
-    memtx can read data in the snapshot with all indexes disabled.
-    First, all tuples are read into memory. Then, primary keys are built in bulk,
-    taking advantage of the fact that the data is already sorted by primary key
-    within each space.
-
-    If the recovery process is non-default (``force_recovery`` is ``true``),
-    Tarantool performs additional checking. Indexes are enabled at
-    the start, and tuples are added one by one. This means that any unique-key
-    constraint violations will be caught, and any duplicates will be skipped.
-    Normally there will be no constraint violations or duplicates, so these checks
-    are only made if an error has occurred.
-
-Step 3
-    Find the WAL file that was made at the time of, or after, the snapshot file.
-    Read its log entries until the log-entry LSN is greater than the LSN of the
-    snapshot, or greater than the LSN of the vinyl checkpoint. This is the
-    recovery process's "start position"; it matches the current state of the
-    engines.
-
-Step 4
-    Redo the log entries, from the start position to the end of the WAL. The
-    engine skips a redo instruction if it is older than the engine's checkpoint.
-
-Step 5
-    For the memtx engine, re-create all secondary indexes.
+**Step 1**
+
+Read the configuration parameters in the ``box.cfg{}`` request.
+Parameters which affect recovery may include :ref:`work_dir <cfg_basic-work_dir>`,
+:ref:`wal_dir <cfg_basic-wal_dir>`, :ref:`memtx_dir <cfg_basic-memtx_dir>`,
+:ref:`vinyl_dir <cfg_basic-vinyl_dir>`
+and :ref:`force_recovery <cfg_binary_logging_snapshots-force_recovery>`.
+
+**Step 2**
+
+Find the latest snapshot file. Use its data to reconstruct the in-memory
+databases. Instruct the vinyl engine to recover to the latest checkpoint.
+
+There are actually two variations of the reconstruction procedure for memtx
+databases, depending on whether the recovery process is "default".
+
+If the recovery process is default (``force_recovery`` is ``false``),
+memtx can read data in the snapshot with all indexes disabled.
+First, all tuples are read into memory. Then, primary keys are built in bulk,
+taking advantage of the fact that the data is already sorted by primary key
+within each space.
+
+If the recovery process is non-default (``force_recovery`` is ``true``),
+Tarantool performs additional checking. Indexes are enabled at
+the start, and tuples are added one by one. This means that any unique-key
+constraint violations will be caught, and any duplicates will be skipped.
+Normally there will be no constraint violations or duplicates, so these checks
+are only made if an error has occurred.
+
+**Step 3**
+
+Find the WAL file that was made at the time of, or after, the snapshot file.
+Read its log entries until the log-entry LSN is greater than the LSN of the
+snapshot, or greater than the LSN of the vinyl checkpoint. This is the
+recovery process's "start position"; it matches the current state of the
+engines.
+
+**Step 4**
+
+Redo the log entries, from the start position to the end of the WAL. The
+engine skips a redo instruction if it is older than the engine's checkpoint.
+
+**Step 5**
+
+For the memtx engine, re-create all secondary indexes.
diff --git a/doc/reference/reference_lua/box_ctl.rst b/doc/reference/reference_lua/box_ctl.rst
@@ -44,6 +44,12 @@ Below is a list of all ``box.ctl`` functions.
         *  - :doc:`./box_ctl/on_shutdown`
            - Create a "shutdown trigger"
 
+        *  - :doc:`./box_ctl/on_recovery_state`
+           - Create a trigger executed on different stages of a node recovery or initial configuration
+
+        *  - :doc:`./box_ctl/on_election`
+           - Create a :ref:`trigger <triggers>` executed every time the current state of a replica set node in regard to :ref:`leader election <repl_leader_elect>` changes
+
         *  - :doc:`./box_ctl/set_on_shutdown_timeout`
            - Set a timeout in seconds for the ``on_shutdown`` trigger
 
@@ -63,6 +69,8 @@ Below is a list of all ``box.ctl`` functions.
     box_ctl/wait_rw
     box_ctl/on_schema_init
     box_ctl/on_shutdown
+    box_ctl/on_recovery_state
+    box_ctl/on_election
     box_ctl/set_on_shutdown_timeout
     box_ctl/is_recovery_finished
     box_ctl/promote
diff --git a/doc/reference/reference_lua/box_ctl/on_election.rst b/doc/reference/reference_lua/box_ctl/on_election.rst
@@ -0,0 +1,23 @@
+..  _box_ctl-on_election:
+
+===============================================================================
+box.ctl.on_election()
+===============================================================================
+
+..  module:: box.ctl
+
+..  function:: on_election(trigger-function)
+
+    **Since:** :doc:`2.10.0 </release/2.10.0>`
+
+    Create a :ref:`trigger <triggers>` executed every time
+    the current state of a replica set node in regard to :ref:`leader election <repl_leader_elect>` changes.
+    The current state is available in the :ref:`box.info.election <box_info_election>` table.
+
+    The trigger doesn't accept any parameters.
+    You can see the changes in ``box.info.election`` and
+    :ref:`box.info.synchro <box_info_synchro>`.
+
+    :param function     trigger-function: a trigger function
+
+    :return: ``nil`` or a function pointer
diff --git a/doc/reference/reference_lua/box_ctl/on_recovery_state.rst b/doc/reference/reference_lua/box_ctl/on_recovery_state.rst
@@ -0,0 +1,53 @@
+..  _box_ctl-on_recovery_state:
+
+===============================================================================
+box.ctl.on_recovery_state()
+===============================================================================
+
+..  module:: box.ctl
+
+..  function:: on_recovery_state(trigger-function)
+
+    **Since:** :doc:`2.11.0 </release/2.11.0>`
+
+    Create a :ref:`trigger <triggers>` executed on different stages of a node :ref:`recovery <internals-recovery_process>` or initial configuration.
+    Note that you need to set the ``box.ctl.on_recovery_state`` trigger before the initial :ref:`box.cfg <box_introspection-box_cfg>` call.
+
+    :param function     trigger-function: a trigger function
+
+    :return: ``nil`` or a function pointer
+
+    A registered trigger function is run on each of the supported recovery
+    state and receives the state name as a parameter:
+
+    *   ``snapshot_recovered``: the node has recovered the snapshot files.
+    *   ``wal_recovered``: the node has recovered the WAL files.
+    *   ``indexes_built``: the node has built secondary indexes for memtx spaces.
+        This stage might come before any actual data is recovered. This means that the
+        indexes are available right after the first tuple is recovered.
+    *   ``synced``: the node has synced with enough remote peers.
+        This means that the node changes the state from :ref:`orphan <internals-replication-orphan_status>` to ``running``.
+
+    All these states are passed during the initial ``box.cfg`` call when recovering
+    from the snapshot and WAL files.
+    Note that the ``synced`` state might be reached after the initial ``box.cfg`` call finishes.
+    For example, if :ref:`replication_sync_timeout <cfg_replication-replication_sync_timeout>`
+    is set to 0, the node finishes ``box.cfg`` without reaching ``synced`` and stays ``orphan``.
+    Once the node is synced with enough remote peers, the ``synced`` state is reached.
+
+    .. NOTE::
+
+        When bootstrapping a fresh cluster with no data, all the instances in this cluster
+        execute triggers on the same stages for consistency.
+        For example, ``snapshot_recovered`` and ``wal_recovered``
+        run when the node finishes a cluster's bootstrap or finishes joining to an existing cluster.
+
+
+    **Example:**
+
+    The example below shows how to :ref:`log <log-module>` a specified message when each state is reached.
+
+    ..  literalinclude:: /code_snippets/test/triggers/on_recovery_state_test.lua
+        :language: lua
+        :lines: 7-11
+        :dedent:
diff --git a/doc/reference/reference_lua/box_ctl/on_schema_init.rst b/doc/reference/reference_lua/box_ctl/on_schema_init.rst
@@ -6,10 +6,6 @@ box.ctl.on_schema_init()
 
 .. module:: box.ctl
 
-The ``box.ctl`` submodule also contains two functions for the two
-:ref:`server trigger <triggers>` definitions: ``on_shutdown`` and ``on_schema_init``.
-Please, familiarize yourself with the mechanism of trigger functions before using them.
-
 .. function:: on_schema_init(trigger-function [, old-trigger-function])
 
     Create a "schema_init :ref:`trigger <triggers>`".
diff --git a/doc/reference/reference_lua/box_ctl/on_shutdown.rst b/doc/reference/reference_lua/box_ctl/on_shutdown.rst
@@ -6,11 +6,6 @@ box.ctl.on_shutdown()
 
 ..  module:: box.ctl
 
-The ``box.ctl`` submodule also contains two functions for the two
-:ref:`server trigger <triggers>` definitions: ``on_shutdown`` and ``on_schema_init``.
-Please, familiarize yourself with the mechanism of trigger functions before using them.
-Details about trigger characteristics are in the :ref:`triggers <triggers-box_triggers>` section.
-
 ..  function:: on_shutdown(trigger-function [, old-trigger-function])
 
      Create a "shutdown :ref:`trigger <triggers>`".
diff --git a/locale/ru/LC_MESSAGES/dev_guide/internals/recovery_internals.po b/locale/ru/LC_MESSAGES/dev_guide/internals/recovery_internals.po
@@ -3,10 +3,10 @@ msgid "The recovery process"
 msgstr "Процесс восстановления"
 
 msgid ""
-"The recovery process begins when box.cfg{} happens for the first time after "
+"The recovery process begins when ``box.cfg{}`` happens for the first time after "
 "the Tarantool server instance starts."
 msgstr ""
-"Процесс восстановления начинается, когда box.cfg{} впервые используется "
+"Процесс восстановления начинается, когда ``box.cfg{}`` впервые используется "
 "после запуска экземпляра Tarantool-сервера."
 
 msgid ""
@@ -32,8 +32,8 @@ msgstr ""
 "операция создания снимка откатывается в случае какой-либо ошибки, поэтому "
 "контрольная точка vinyl'а будет настолько же актуальной, как и файл снимка.)"
 
-msgid "Step 1"
-msgstr "Шаг 1"
+msgid "**Step 1**"
+msgstr "**Шаг 1**"
 
 msgid ""
 "Read the configuration parameters in the ``box.cfg{}`` request. Parameters "
@@ -48,8 +48,8 @@ msgstr ""
 "<cfg_basic-memtx_dir>`, :ref:`vinyl_dir <cfg_basic-vinyl_dir>` и "
 ":ref:`force_recovery <cfg_binary_logging_snapshots-force_recovery>`."
 
-msgid "Step 2"
-msgstr "Шаг 2"
+msgid "**Step 2**"
+msgstr "**Шаг 2**"
 
 msgid ""
 "Find the latest snapshot file. Use its data to reconstruct the in-memory "
@@ -95,8 +95,8 @@ msgstr ""
 "ограничений или повторяющихся значений, поэтому такие проверки проводятся "
 "только в случае ошибки."
 
-msgid "Step 3"
-msgstr "Шаг 3"
+msgid "**Step 3**"
+msgstr "**Шаг 3**"
 
 msgid ""
 "Find the WAL file that was made at the time of, or after, the snapshot file."
@@ -111,8 +111,8 @@ msgstr ""
 "будет начальной точкой для процесса восстановления, которая соответствует "
 "текущему состоянию движков."
 
-msgid "Step 4"
-msgstr "Шаг 4"
+msgid "**Step 4**"
+msgstr "**Шаг 4**"
 
 msgid ""
 "Redo the log entries, from the start position to the end of the WAL. The "
@@ -121,8 +121,8 @@ msgstr ""
 "Повторить записи журнала с начальной точки до конца WAL. Движок пропускает "
 "команду повторения, если данные старше контрольной точки движка."
 
-msgid "Step 5"
-msgstr "Шаг 5"
+msgid "**Step 5**"
+msgstr "**Шаг 5**"
 
 msgid "For the memtx engine, re-create all secondary indexes."
 msgstr "Повторно создать все вторичные индексы для движка memtx."
diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/box_ctl/on_schema_init.po b/locale/ru/LC_MESSAGES/reference/reference_lua/box_ctl/on_schema_init.po
@@ -2,17 +2,6 @@
 msgid "box.ctl.on_schema_init()"
 msgstr ""
 
-msgid ""
-"The ``box.ctl`` submodule also contains two functions for the two "
-":ref:`server trigger <triggers>` definitions: ``on_shutdown`` and "
-"``on_schema_init``. Please, familiarize yourself with the mechanism of "
-"trigger functions before using them."
-msgstr ""
-"Встроенный модуль ``box.ctl`` также содержит две функции для определения "
-"двух :ref:`серверных триггеров <triggers>`: ``on_shutdown`` и "
-"``on_schema_init``. Пожалуйста, ознакомьтесь с механизмом триггерных функций"
-" перед их использованием."
-
 msgid ""
 "Create a \"schema_init :ref:`trigger <triggers>`\". The ``trigger-function``"
 " will be executed when :ref:`box.cfg{} <index-book_cfg>` happens for the "
diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/box_ctl/on_shutdown.po b/locale/ru/LC_MESSAGES/reference/reference_lua/box_ctl/on_shutdown.po
@@ -2,17 +2,6 @@
 msgid "box.ctl.on_shutdown()"
 msgstr ""
 
-msgid ""
-"The ``box.ctl`` submodule also contains two functions for the two "
-":ref:`server trigger <triggers>` definitions: ``on_shutdown`` and "
-"``on_schema_init``. Please, familiarize yourself with the mechanism of "
-"trigger functions before using them."
-msgstr ""
-"Встроенный модуль ``box.ctl`` также содержит две функции для определения "
-"двух :ref:`серверных триггеров <triggers>`: ``on_shutdown`` и "
-"``on_schema_init``. Пожалуйста, ознакомьтесь с механизмом триггерных функций"
-" перед их использованием."
-
 msgid ""
 "Details about trigger characteristics are in the :ref:`triggers <triggers-"
 "box_triggers>` section."
