Document wal.retention_period (#4399)

Author: andreyaksenov

doc/reference/configuration/configuration_reference.rst

@@ -4660,6 +4660,7 @@ To learn more about the WAL configuration, check the :ref:`Persistence <configur
 -   :ref:`wal.max_size <configuration_reference_wal_max_size>`
 -   :ref:`wal.mode <configuration_reference_wal_mode>`
 -   :ref:`wal.queue_max_size <configuration_reference_wal_queue_max_size>`
+-   :ref:`wal.retention_period <configuration_reference_wal_retention_period>`
 -   :ref:`wal.ext.* <configuration_reference_wal_ext>`
 
 ..  _configuration_reference_wal_cleanup_delay:
@@ -4680,6 +4681,8 @@ To learn more about the WAL configuration, check the :ref:`Persistence <configur
         The option has no effect on nodes running as
         :ref:`anonymous replicas <configuration_reference_replication_anon>`.
 
+    See also: :ref:`wal.retention_period <configuration_reference_wal_retention_period>`
+
     |
     | Type: number
     | Default: 14400
@@ -4768,6 +4771,36 @@ To learn more about the WAL configuration, check the :ref:`Persistence <configur
     | Default: 16777216
     | Environment variable: TT_WAL_QUEUE_MAX_SIZE
 
+..  _configuration_reference_wal_retention_period:
+
+..  confval:: wal.retention_period
+
+    **Since:** :doc:`3.1.0 </release/3.1.0>` (`Enterprise Edition <https://www.tarantool.io/compare/>`_ only)
+
+    The delay in seconds used to prevent the :ref:`Tarantool garbage collector <configuration_persistence_checkpoint_daemon>` from removing a :ref:`write-ahead log <internals-wal>` file after it has been closed.
+    If a node is restarted, ``wal.retention_period`` counts down from the last modification time of the write-ahead log file.
+
+    The garbage collector doesn't track write-ahead logs that are to be :ref:`relayed <memtx-replication>` to anonymous replicas, such as:
+
+    *   Anonymous replicas added as a part of a cluster configuration (see :ref:`replication.anon <configuration_reference_replication_anon>`).
+    *   CDC (Change Data Capture) that retrieves data using anonymous replication.
+
+    In case of a replica or CDC downtime, the required write-ahead logs can be removed.
+    As a result, such a replica needs to be rebootstrapped.
+    You can use ``wal.retention_period`` to prevent such issues.
+
+    Note that :ref:`wal.cleanup_delay <configuration_reference_wal_cleanup_delay>` option also sets the delay used to prevent the Tarantool garbage collector from removing write-ahead logs.
+    The difference is that the garbage collector doesn't take into account ``wal.cleanup_delay`` if all the nodes in the replica set are up and running, which may lead to the removal of the required write-ahead logs.
+
+    ..  NOTE::
+
+        :ref:`box.info.gc().wal_retention_vclock <box_info_gc>` can be used to get a vclock value of the oldest write-ahead log protected by ``wal.retention_period``.
+
+    |
+    | Type: number
+    | Default: 0
+    | Environment variable: TT_WAL_RETENTION_PERIOD
+
 ..  _configuration_reference_wal_ext:
 
 wal.ext.*

doc/reference/reference_lua/box_info/gc.rst

@@ -22,4 +22,5 @@ box.info.gc()
     * **gc().checkpoints[n].signature** -- a sum of a checkpoint's vclock's components.
     * **gc().checkpoint_is_in_progress** -- true if a checkpoint is in progress, otherwise false
     * **gc().vclock** -- the garbage collector's vclock.
-    * **gc().signature** -- the sum of the garbage collector's checkpoint's components.
+    * **gc().signature** -- the sum of the garbage collector's checkpoint's components.
+    * **gc().wal_retention_vclock** -- a vclock value of the oldest write-ahead log file protected from removing by the garbage collector by using the :ref:`wal.retention_period <configuration_reference_wal_retention_period>` option.