Add description for the age and confirm_lag fields in `box.info.s…

…ynchro.queue` (#4559)

* Add description for the `age` and `confirm_lag` fields
* Add code snippet

Fixes #4284
Fixes #4400

---------
Co-authored-by: Elena Shebunyaeva <[email protected]>

doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/README.md

@@ -0,0 +1,23 @@
+# Using box.info.synchro
+
+A sample application demonstrating how to work with [box.info.synchro](https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_info/synchro/).
+
+## Running
+
+To start all instances, execute the following command in the [replication](../../../replication) directory:
+
+```console
+$ tt start box_info_synchro
+```
+
+To check the instance status, run:
+
+```console
+$ tt status box_info_synchro
+```
+
+To connect to the ``instance001`` instance, run:
+
+```console
+$ tt connect box_info_synchro:instance001
+```

doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/config.yaml

@@ -0,0 +1,31 @@
+credentials:
+ users:
+ replicator:
+ password: 'topsecret'
+ roles: [replication]
+
+iproto:
+ advertise:
+ peer:
+ login: replicator
+
+groups:
+ group001:
+ replicasets:
+ replicaset001:
+ instances:
+ instance001:
+ database:
+ mode: rw
+ replication:
+ synchro_quorum: 2
+ synchro_timeout: 1000
+ iproto:
+ listen:
+ - uri: '127.0.0.1:3301'
+ instance002:
+ database:
+ mode: ro
+ iproto:
+ listen:
+ - uri: '127.0.0.1:3302'

doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/instances.yml

@@ -0,0 +1,2 @@
+instance001:
+instance002:

doc/reference/reference_lua/box_info/synchro.rst

@@ -1,8 +1,7 @@
 .. _box_info_synchro:
 
-================================================================================
 box.info.synchro
-================================================================================
+================
 
 .. module:: box.info
 
@@ -26,9 +25,13 @@ box.info.synchro
  but they can't create any synchronous transactions.
  To claim or reclaim the queue, use :ref:`box.ctl.promote() <box_ctl-promote>` on the instance that you want
  to promote.
- With elections enabled, an instance runs ``box.ctl.promote()`` command automatically after winning the elections.
  To clear the ownership, call :ref:`box.ctl.demote() <box_ctl-demote>` on the synchronous queue owner.
 
+ When Raft election is enabled and :ref:`replication.election_mode <configuration_reference_replication_election_mode>`
+ is set to ``candidate``, the new Raft leader claims the queue automatically after winning the elections.
+ It means that the value of ``box.info.synchro.queue.owner`` becomes equal to :ref:`box.info.election.leader <box_info_election>`.
+ When Raft is enabled, no manual intervention with ``box.ctl.promote()`` or ``box.ctl.demote()`` is required.
+
  - ``term`` (since version :doc:`2.10.0 </release/2.10.0>`) -- current queue term.
  It contains the term of the last ``PROMOTE`` request.
  Usually, it is equal to :ref:`box.info.election.term <box_info_election>`.
@@ -43,102 +46,126 @@ box.info.synchro
  Until the request is complete, any other incoming synchronous transactions and system requests
  will be delayed.
 
+ - ``age`` (since version :doc:`3.2.0 </release/3.2.0>`) -- the time in seconds that the oldest entry currently
+ present in the queue has spent waiting for the quorum to collect.
+
+ - ``confirm_lag`` (since version :doc:`3.2.0 </release/3.2.0>`) -- the time in seconds that the latest successfully
+ confirmed entry waited for the quorum to collect.
+
  * ``quorum`` -- the resulting value of the
- :ref:`replication_synchro_quorum <cfg_replication-replication_synchro_quorum>` configuration option.
+ :ref:`replication.synchro_quorum <configuration_reference_replication_synchro_quorum>` configuration option.
  Since version :doc:`2.5.3 </release/2.5.3>`, the option can be set as a dynamic formula.
  In this case, the value of the ``quorum`` member depends on the current number of replicas.
 
  **Example 1:**
 
- In this example, the ``quorum`` field is equal to ``1``.
+ In this example, the ``quorum`` field is equal to `1`.
  That is, synchronous transactions work like asynchronous ones.
  `1` means that a successful WAL writing to the master is enough to commit.
 
  .. code-block:: tarantoolsession
 
- tarantool> box.info.synchro
+ box_info_synchro:instance001> box.info.synchro
  ---
  - queue:
  owner: 1
+ confirm_lag: 0
  term: 2
+ age: 0
  len: 0
  busy: false
  quorum: 1
  ...
 
  **Example 2:**
 
- First, set a quorum number and a timeout for synchronous replication using the following command:
+ Example on GitHub: `box_info_synchro <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro>`_
+
+ In this example, there are two instances:
+
+ - ``instance001`` is going to be the leader.
+ - ``instance002`` is a follower instance.
+
+ .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/box_info_synchro/config.yaml
+ :language: yaml
+ :start-at: groups
+ :end-at: 3302
+ :dedent:
+
+ On the **first** instance, grant the user with the ``super`` role:
 
  .. code-block:: tarantoolsession
 
- tarantool> box.cfg{
- > replication_synchro_quorum=2,
- > replication_synchro_timeout=1000
- > }
+ box_info_synchro:instance001> box.schema.user.grant('guest', 'super')
 
- Next, check the current state of synchronous replication:
+ After that, use the ``box.ctl.promote()`` function to claim the queue:
 
  .. code-block:: tarantoolsession
 
- tarantool> box.info.synchro
+ box_info_synchro:instance001> box.ctl.promote()
+
+ Create a space named ``sync`` and enable synchronous replication on this space:
+
+ .. code-block:: tarantoolsession
+
+ box_info_synchro:instance001> s = box.schema.space.create("sync", {is_sync=true})
+
+ Then, create an index:
+
+ .. code-block:: tarantoolsession
+
+ box_info_synchro:instance001> _ = s:create_index('pk')
+
+ Check the current state of synchronous replication:
+
+ .. code-block:: tarantoolsession
+
+ box_info_synchro:instance001> box.info.synchro
  ---
  - queue:
  owner: 1
+ confirm_lag: 0
  term: 2
+ age: 0
  len: 0
  busy: false
  quorum: 2
  ...
 
- Create a space called ``sync`` and enable synchronous replication on this space.
- Then, create an index.
+ On the **second** instance, simulate failure like if this instance would crash or go out of the network:
 
  .. code-block:: tarantoolsession
 
- tarantool> s = box.schema.space.create("sync", {is_sync=true})
- tarantool> _ = s:create_index('pk')
+ box_info_synchro:instance002> os.exit(0)
+  ⨯ Connection was closed. Probably instance process isn't running anymore
 
- After that, use ``box.ctl.promote()`` function to claim a queue:
+ On the **first** instance, try to perform some synchronous transactions.
+ The transactions would hang, because the :ref:`replication.synchro_quorum <configuration_reference_replication_synchro_quorum>`
+ option is set to `2`, and the second instance is not available:
 
  .. code-block:: tarantoolsession
 
- tarantool> box.ctl.promote()
-
- Next, perform data manipulations:
-
- .. code-block:: tarantoolsession
-
- tarantool> require('fiber').new(function() box.space.sync:replace{1} end)
- ---
- - status: suspended
- name: lua
- id: 119
- ...
- tarantool> require('fiber').new(function() box.space.sync:replace{1} end)
+ box_info_synchro:instance001> fiber = require('fiber')
  ---
- - status: suspended
- name: lua
- id: 120
  ...
- tarantool> require('fiber').new(function() box.space.sync:replace{1} end)
+ box_info_synchro:instance001> for i = 1, 3 do fiber.new(function() box.space.sync:replace{i} end) end
  ---
- - status: suspended
- name: lua
- id: 121
  ...
 
- If you call the ``box.info.synchro`` command again,
- you will see that now there are 3 transactions waiting in the queue:
+ Call the ``box.info.synchro`` command on the first instance again:
 
  .. code-block:: tarantoolsession
 
- tarantool> box.info.synchro
+ box_info_synchro:instance001> box.info.synchro
  ---
  - queue:
  owner: 1
+ confirm_lag: 0
  term: 2
+ age: 5.2658250015229
  len: 3
  busy: false
  quorum: 2
- ...
+ ...
+
+ The ``len`` field is now equal to 3. It means that there are 3 transactions waiting in the queue.