Document box.ctl.on_recovery_state #3242
Description
Product: Tarantool
Since: 2.11
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_ctl/
SME: @ sergepetrenko
Details
box.ctl.on_recovery_state is a handle to register triggers that will
be executed on different stages of recovery/initial configuration.
A trigger registered this way is run on each of the supported recovery
stages, and receives the stage name as a parameter. The possible stages
are:
- "snapshot_recovered": the node has recovered the snapshot file.
- "wal_recovered": the node has recovered all the .xlog files.
- "indexes_built": all the secondary indexes are usable. This event
might come even before any actual data is recovered, meaning that the
indexes will be available right with the first recovered tuple. - "synced": the node has synced with enough remote peers and has left
orphan state.
All these stages are passed during initial box.cfg call when recovering
from .snap and .xlog files.
When bootstrapping a fresh cluster with no data, all the instances in it
will still execute triggers on the same stages for consistency.
For example, "snapshot_recovered" and "wal_recovered" will
be run once the node finishes cluster bootstrap or finishes joining to an
existing cluster.
Anyway, by the time the initial box.cfg call finishes, regardless of
recovery or bootstrap, the triggers will be called with parameters
"snapshot_recovery", "wal_recovered" and "indexes_built". The triggers
on "synced" state might execute later, when the node leaves the orphan
mode.
Note, that you must set box.ctl.on_recovery_state triggers before the
initial box.cfg call for them to take effect.
Example:
NO_WRAP
Tarantool 2.11.0
type 'help' for interactive help
tarantool> log = require('log')
---
...
tarantool> trigger_f = function(state) log.info('State "' .. state .. '" reached') end
---
...
tarantool> box.ctl.on_recovery_state(trigger_f)
---
- 'function: 0x0104662788'
...
tarantool> box.cfg{}
<stripped some messages>
2022-11-15 13:21:43.149 [98398] main/103/interactive I> recovering from `./00000000000000000004.snap'
2022-11-15 13:21:43.166 [98398] main/103/interactive I> cluster uuid 75c5c40e-c795-4c6f-b602-25fe5b1c9f3b
2022-11-15 13:21:43.187 [98398] main/103/interactive I> assigned id 1 to replica 1fbcb1d7-f600-4cc6-83b4-8d409d2937a9
2022-11-15 13:21:43.187 [98398] main/103/interactive I> update replication_synchro_quorum = 1
2022-11-15 13:21:43.187 [98398] main/103/interactive I> State "snapshot_recovered" reached
^^^^^^^^^^^^^^^^^^
2022-11-15 13:21:43.187 [98398] main/103/interactive I> recover from `./00000000000000000004.xlog'
2022-11-15 13:21:43.188 [98398] main/103/interactive I> done `./00000000000000000004.xlog'
2022-11-15 13:21:43.188 [98398] main/103/interactive I> recover from `./00000000000000000006.xlog'
2022-11-15 13:21:43.188 [98398] main/103/interactive I> done `./00000000000000000006.xlog'
2022-11-15 13:21:43.188 [98398] main/103/interactive I> Building secondary indexes in space 'test'...
2022-11-15 13:21:43.188 [98398] main/103/interactive I> Adding 2 keys to TREE index 'sk' ...
2022-11-15 13:21:43.188 [98398] main/103/interactive I> Space 'test': done
2022-11-15 13:21:43.188 [98398] main/103/interactive I> State "indexes_built" reached
^^^^^^^^^^^^^
2022-11-15 13:21:43.189 [98398] main/103/interactive I> State "wal_recovered" reached
^^^^^^^^^^^^^
2022-11-15 13:21:43.189 [98398] main/103/interactive I> ready to accept requests
2022-11-15 13:21:43.189 [98398] main/103/interactive I> State "synced" reached
^^^^^^
2022-11-15 13:21:43.189 [98398] main/103/interactive I> leaving orphan mode
<stripped some messages>
---
...
tarantool>
NO_WRAP
Requested by @sergepetrenko in tarantool/tarantool@24341d5.