System events | Tarantool
Документация на русском языке
поддерживается сообществом

System events

Since 2.10.0.

Predefined events have a special naming schema – theirs names always start with the reserved box. prefix. It means that you cannot create new events with it.

The system processes the following events:

  • box.status
  • box.election
  • box.schema
  • box.shutdown

In response to each event, the server sends back certain IPROTO fields.

The events are available from the beginning as non-MP_NIL. If a watcher subscribes to a system event before it has been broadcast, it receives an empty table for the event value.

The event is generated when there is a change in any of the values listed in the event. For example, see the parameters in the event below – id, instance_uuid, and replicaset_uuid. Suppose the ìd value ( has changed. This triggers the event, which states that the value of has changed, while and remain the same.

Contains identification of the instance. Value changes are rare.

  • id: the numeric instance ID is unknown before the registration. For anonymous replicas, the value is 0 until they are officially registered.
  • instance_uuid: the UUID of the instance never changes after the first box.cfg. The value is unknown before the box.cfg call.
  • replicaset_uuid: the value is unknown until the instance joins a replicaset or boots a new one.
-- value
MP_STR “id”: MP_UINT;,
MP_STR “instance_uuid”: MP_UUID;,
MP_STR “replicaset_uuid”: MP_UUID,

Contains generic information about the instance status.

MP_STR “is_ro”: MP_BOOL,
MP_STR “is_ro_cfg”: MP_BOOL box.cfg.read_only,
MP_STR “status”: MP_STR,

Contains fields of that are necessary to find out the most recent writable leader.

  • term: shows the current election term.
  • role: indicates the election state of the node – leader, follower, or candidate.
  • is_ro: indicates the read-only mode or the orphan status.
  • leader: shows the leader node ID in the current term.
MP_STR “term”: MP_UINT,
MP_STR “role”: MP_STR,
MP_STR “is_ro”: MP_BOOL,
MP_STR “leader”: MP_UINT,

Contains schema-related data.

  • version: shows the schema version.
MP_STR “version”: MP_UINT schema_version,

Contains a boolean value which indicates whether there is an active shutdown request.

The event is generated when the server receives a shutdown request (os.exit() command or SIGTERM signal).

The box.shutdown event is applied for the graceful shutdown protocol. It is a feature which is available since 2.10.0. This protocol is supposed to be used with connectors to signal a client about the upcoming server shutdown and close active connections without broken requests. For more information, refer to the graceful shutdown protocol section.

local conn =
local log = require('log')
-- Subscribe to updates of key ''
local w = conn:watch('', function(key, value)
    assert(key == '')"The value is '%s'", value)

If you want to unregister the watcher when it’s no longer needed, use the following command:

Нашли ответ на свой вопрос?
Обратная связь