persistence: apply review suggestions

Author: xuniq

doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml

@@ -6,9 +6,10 @@ groups:
           instance001:
             snapshot:
               dir: 'var/lib/{{ instance_name }}/snapshots'
-              count: 10
+              count: 3
               by:
-                interval: 60
+                interval: 7200
+                wal_size: 1000000000000000000
             iproto:
               listen:
               - uri: '127.0.0.1:3301'

doc/concepts/configuration/configuration_persistence.rst

@@ -26,32 +26,32 @@ This section describes how to define snapshot settings in the :ref:`snapshot <co
 
 ..  _configuration_persistence_snapshot_creation:
 
-Configure the automatic snapshot creation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Set up automatic snapshot creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In Tarantool, it is possible to set automatic :ref:`snapshot creation </reference/reference_lua/box_snapshot>`.
-To enable it, the :ref:`snapshot.by.interval <configuration_reference_snapshot_by_interval>` option is used.
-The option sets up the :ref:`checkpoint daemon <configuration_persistence_checkpoint_daemon>` that takes new snapshots
-every ``snapshot.by.interval`` seconds.
-When the number of snapshots reaches the limit of :ref:`snapshot.count <configuration_reference_snapshot_count>` size,
-the daemon activates Tarantool garbage collector after the new snapshot is taken.
-Tarantool garbage collector deletes the oldest snapshot file and any associated WAL files.
+In Tarantool, it is possible to automate the :ref:`snapshot creation </reference/reference_lua/box_snapshot>`.
+Automatic creation is enabled by default and can be configured in two ways:
 
-The :ref:`snapshot.by.wal_size <configuration_reference_snapshot_by_wal_size>` option defines the maximum size in bytes
-for of all WAL files created since the last snapshot taken.
-Once this size is exceeded, the checkpoint daemon takes a snapshot and deletes the old WAL files.
+*   A new snapshot is taken once in a given period (see :ref:`snapshot.by.interval <configuration_reference_snapshot_by_interval>`).
+*   A new snapshot is taken once the size of all WAL files created since the last snapshot exceeds a given limit
+    (see :ref:`snapshot.by.wal_size <configuration_reference_snapshot_by_wal_size>`).
 
-The configuration of the checkpoint daemon might look as follows:
+The ``snapshot.by.interval`` option sets up the :ref:`checkpoint daemon <configuration_persistence_checkpoint_daemon>`
+that takes a new snapshot every ``snapshot.by.interval`` seconds.
+If the ``snapshot.by.interval`` option is set to zero, the checkpoint daemon is disabled.
+
+The ``snapshot.by.wal_size`` option defines the maximum size in bytes for of all WAL files created since the last snapshot taken.
+Once this size is exceeded, the checkpoint daemon takes a snapshot. Then, :ref:`Tarantool garbage collector <configuration_persistence_garbage_collector>`
+deletes the old WAL files.
+
+The example shows how to specify the ``snapshot.by.interval`` and the ``snapshot.by.wal_size`` options:
 
 ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml
     :language: yaml
-    :start-at: count:
-    :end-at: 60
+    :start-at: by:
+    :end-at: 1000000000000000000
     :dedent:
 
-If the ``snapshot.by.interval`` option is set to zero, the checkpoint daemon is disabled.
-If the ``snapshot.count`` option is set to zero, the checkpoint daemon does not delete old snapshots.
-
 ..  _configuration_persistence_snapshot_dir:
 
 Specify a directory for snapshot files
@@ -79,6 +79,28 @@ For example, you can place snapshots and write-ahead logs on different hard driv
       wal:
         dir: '/media/drive2/wals'
 
+..  _configuration_persistence_snapshot_count:
+
+Configure a maximum number of stored snapshots
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can set a limit on the number of snapshots stored in the :ref:`snapshot.dir <configuration_reference_snapshot_dir>`
+directory using the :ref:`snapshot.count <configuration_reference_snapshot_count>` option.
+Once the number of snapshots reaches the given limit, :ref:`Tarantool garbage collector <configuration_persistence_garbage_collector>`
+deletes the oldest snapshot file and any associated WAL files after the new snapshot is taken.
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml
+    :language: yaml
+    :start-at: count:
+    :end-at: 7200
+    :dedent:
+
+In the example, the snapshot is created every two hours (every 7200 seconds) until there are three snapshots in the
+``snapshot.dir`` directory.
+After creating a new snapshot (the fourth one), the oldest snapshot and the corresponding WALs are deleted.
+
+If the ``snapshot.count`` option is set to zero, the garbage collector does not delete old snapshots.
+
 ..  _configuration_persistence_wal:
 
 Configure the write-ahead log
@@ -93,8 +115,15 @@ This section describes how to define WAL settings in the :ref:`wal <configuratio
 Set the WAL mode
 ~~~~~~~~~~~~~~~~
 
-To be able to recover data in case of a possible instance restart, enable recording to the write-ahead log.
-To do it, set the :ref:`wal.mode <configuration_reference_wal_mode>` configuration option to ``write`` or ``fsync``.
+The recording to the write-ahead log is enabled by default.
+It means that if an instance restart occurs, the data will be recovered.
+The recording to the WAL can be configured using the :ref:`wal.mode <configuration_reference_wal_mode>` configuration option.
+
+There are two modes that enable writing to the WAL:
+
+*   ``write`` (default) -- enable WAL and write the data without waiting the data to be flushed to the storage device.
+*   ``fsync`` -- enable WAL and ensure that the record is written to the storage device.
+
 The example below shows how to specify the ``write`` WAL mode for ``instance001``:
 
 ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml
@@ -103,9 +132,6 @@ The example below shows how to specify the ``write`` WAL mode for ``instance001`
     :end-at: 'write'
     :dedent:
 
-The ``write`` mode enables WAL and writes the data without waiting the data to be flushed to the storage device.
-The ``fsync`` mode enables WAL and ensures that the record is written to the storage device.
-
 To turn the WAL writer off, set the ``wal.mode`` option to ``none``.
 
 ..  _configuration_persistence_wal_dir:
@@ -159,7 +185,7 @@ Set a delay for the garbage collector
 
 In Tarantool, the :ref:`checkpoint daemon <configuration_persistence_checkpoint_daemon>`
 takes new snapshots at the given interval (see :ref:`snapshot.by.interval <configuration_reference_snapshot_by_interval>`).
-After an instance restart, the daemon activates the Tarantool garbage collector that deletes the old WAL files.
+After an instance restart, the Tarantool garbage collector deletes the old WAL files.
 
 To delay the immediate deletion of WAL files, use the :ref:`wal.cleanup_delay <configuration_reference_wal_cleanup_delay>`
 configuration option. The delay eliminates possible erroneous situations when the master deletes WALs
@@ -180,7 +206,7 @@ In the example, the delay is set to 5 hours (18000 seconds):
 Specify the WAL extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In Tarantool Enterprise, you can store an old and new tuple for each crud operation performed.
+In Tarantool Enterprise, you can store an old and new tuple for each CRUD operation performed.
 The detailed description and examples of the WAL extensions are provided in the :ref:`WAL extensions <wal_extensions>` section.
 
 See also: :ref:`wal.ext.* <configuration_reference_wal_ext>` configuration options.
@@ -191,32 +217,49 @@ Checkpoint daemon
 -----------------
 
 The checkpoint daemon (snapshot daemon) is a constantly running :ref:`fiber <app-fibers>`.
-If the checkpoint daemon is enabled, it takes new :ref:`snapshot (.snap) files <index-box_persistence>` at the
-:ref:`given interval <configuration_reference_snapshot_by_interval>` automatically.
-If necessary, the checkpoint daemon also activates the Tarantool garbage collector that deletes old snapshot and WAL files.
+The checkpoint daemon creates a schedule for the periodic snapshot creation based on
+the :ref:`configuration options <configuration_reference_snapshot_by>`and the speed of file size growth.
+If enabled, the daemon makes new snapshots (``.snap``) files according to this schedule.
+
+The work of checkpoint daemon is based on the following configuration options:
+
+*   :ref:`snapshot.by.interval <configuration_reference_snapshot_by_interval>` -- a new snapshot is taken once in a given period.
+*   :ref:`snapshot.by.wal_size <configuration_reference_snapshot_by_wal_size>` -- a new snapshot is taken once the size
+    of all WAL files created since the last snapshot exceeds a given limit.
+
+If necessary, the checkpoint daemon also activates the :ref:`Tarantool garbage collector <configuration_persistence_garbage_collector>` that deletes old snapshot and WAL files.
+
+..  _configuration_persistence_garbage_collector:
+
+Tarantool garbage collector
+---------------------------
+
+Tarantool garbage collector can be activated by the :ref:`checkpoint daemon <configuration_persistence_checkpoint_daemon>`.
+The garbage collector tracks the snapshots that are to be :ref:`relayed to a replica <memtx-replication>` or needed
+by other consumers. When the files are no longer needed, Tarantool garbage collector deletes them.
 
 ..  NOTE::
 
-    This garbage collector is distinct from the `Lua garbage collector <https://www.lua.org/manual/5.1/manual.html#2.10>`_
+    The garbage collector called by the checkpoint daemon, is distinct from the `Lua garbage collector <https://www.lua.org/manual/5.1/manual.html#2.10>`_
     which is for Lua objects, and distinct from the Tarantool garbage collector that specializes in :ref:`handling shard buckets <vshard-gc>`.
 
 This garbage collector is called as follows:
 
 *   When the number of snapshots reaches the limit of :ref:`snapshot.count <configuration_reference_snapshot_count>` size.
     After a new snapshot is taken, Tarantool garbage collector deletes the oldest snapshot file and any associated WAL files.
 
-*   When the size all WAL files created since the last snapshot reaches the limit of :ref:`snapshot.by.wal_size <configuration_reference_snapshot_by_wal_size>`.
+*   When the size of all WAL files created since the last snapshot reaches the limit of :ref:`snapshot.by.wal_size <configuration_reference_snapshot_by_wal_size>`.
     Once this size is exceeded, the checkpoint daemon takes a snapshot, then the garbage collector deletes the old WAL files.
 
-If the checkpoint daemon deletes an old snapshot file, the Tarantool garbage collector also deletes
+If an old snapshot filen is deleted, the Tarantool garbage collector also deletes
 any :ref:`write-ahead log (.xlog) <internals-wal>` files that meet the following conditions:
 
 *   The WAL files are older than the snapshot file.
 *   The WAL files contain information present in the snapshot file.
 
 Tarantool garbage collector also deletes obsolete vinyl ``.run`` files.
 
-The checkpoint daemon and the Tarantool garbage collector don't delete a file in the following cases:
+Tarantool garbage collector doesn't delete a file in the following cases:
 
 *   A **backup** is running, and the file has not been backed up
     (see :ref:`"Hot backup" <admin-backups-hot_backup_vinyl_memtx>`).

doc/dev_guide/internals/file_formats.rst

@@ -5,22 +5,26 @@ File formats
 
 .. _internals-wal:
 
-Data persistence and the WAL file format
-----------------------------------------
+The WAL file format
+-------------------
 
-To maintain data persistence, Tarantool writes each data change request (insert,
-update, delete, replace, upsert) into a write-ahead log (WAL) file in the
+To maintain :ref:`data persistence <concepts-data_model-persistence>`, Tarantool writes each data change request (insert,
+update, delete, replace, upsert) to a write-ahead log (WAL) file in the
 :ref:`wal.dir <configuration_reference_wal_dir>` directory.
-Each data change request gets assigned a continuously growing 64-bit log sequence
+Each data change request is assigned a continuously growing 64-bit log sequence
 number. The name of the WAL file is based on the log sequence number of the first
 record in the file, plus an extension ``.xlog``.
 A new WAL file is created
 when the current one reaches the :ref:`wal_max_size <cfg_binary_logging_snapshots-wal_max_size>` size.
 
-Apart from a log sequence number and the data change request (formatted as in
-:ref:`Tarantool's binary protocol <internals-box_protocol>`),
-each WAL record contains a header, some metadata, and then the data formatted
-according to `msgpack <https://en.wikipedia.org/wiki/MessagePack>`_ rules.
+Each WAL record contains:
+
+*   a log sequence number
+*   a data change request (formatted as in :ref:`Tarantool's binary protocol <internals-box_protocol>`)
+
+*   a header
+*   some metadata
+*   the data formatted according to `msgpack <https://en.wikipedia.org/wiki/MessagePack>`_ rules.
 
 To see the hexadecimal bytes of the given WAL file, use the ``hexdump`` command:
 
@@ -102,7 +106,7 @@ It is possible to turn the write-ahead log completely off, by setting the ``wal_
 Even without the write-ahead log it's still possible to take a persistent copy of the
 entire data set with the :ref:`box.snapshot() <box-snapshot>` request.
 
-An .xlog file always contains changes based on the primary key.
+An ``.xlog`` file always contains changes based on the primary key.
 Even if the client requested an update or delete using
 a secondary key, the record in the .xlog file contains the primary key.
 
@@ -111,12 +115,14 @@ a secondary key, the record in the .xlog file contains the primary key.
 The snapshot file format
 ------------------------
 
-The format of a snapshot .snap file is similar to the format of a WAL .xlog file, except for the header and content.
-The snapshot header contains the instance's global unique identifier
-and the snapshot file's position in history, relative to earlier snapshot files.
-Also, the content differs: an .xlog file may contain records for any data-change
-requests (inserts, updates, upserts, and deletes), a .snap file may only contain records
-of inserts to memtx spaces.
+The format of a snapshot (``.snap``) file is the following:
+
+*   The snapshot header contains the instance's global unique identifier
+    and the snapshot file's position in history, relative to earlier snapshot files.
+
+*   The snapshot content contains the records of inserts to memtx spaces.
+    That differs from the content of an ``.xlog`` file that may contain records for any data-change requests
+    (inserts, updates, upserts, and deletes).
 
 Primarily, the records in the snapshot file have the following order:
 

doc/reference/configuration/cfg_basic.rst

@@ -100,9 +100,12 @@
 
     Since version 1.7.4.
 
-    A directory where memtx stores snapshot (.snap) files. Can be relative to
-    :ref:`work_dir <cfg_basic-work_dir>`. If not specified, defaults to
-    ``work_dir``. See also :ref:`wal_dir <cfg_basic-wal_dir>`.
+    A directory where memtx stores snapshot (.snap) files.
+    A relative path in this option is interpreted as relative to :ref:`work_dir <cfg_basic-work_dir>`.
+
+    By default, snapshots and WAL files are stored in the same directory.
+    However, you can set different values for the ``memtx_dir`` and :ref:`wal_dir <cfg_basic-wal_dir>` options
+    to store them on different physical disks for performance matters.
 
     | Type: string
     | Default: "."
@@ -230,11 +233,12 @@
 
     Since version 1.6.2.
 
-    A directory where write-ahead log (.xlog) files are stored. Can be relative
-    to :ref:`work_dir <cfg_basic-work_dir>`. Sometimes ``wal_dir`` and
-    :ref:`memtx_dir <cfg_basic-memtx_dir>` are specified with different values, so
-    that write-ahead log files and snapshot files can be stored on different
-    disks. If not specified, defaults to ``work_dir``.
+    A directory where write-ahead log (.xlog) files are stored.
+    A relative path in this option is interpreted as relative to :ref:`work_dir <cfg_basic-work_dir>`.
+
+    By default, WAL files and snapshots are stored in the same directory.
+    However, you can set different values for the ``wal_dir`` and :ref:`memtx_dir <cfg_basic-memtx_dir>` options
+    to store them on different physical disks for performance matters.
 
     | Type: string
     | Default: "."

doc/reference/configuration/cfg_binary_logging_snapshots.rst

@@ -130,15 +130,14 @@
 
     Since version :doc:`2.6.3 </release/2.6.3>`.
 
-    The delay (in seconds) used to prevent the :ref:`Tarantool garbage collector <cfg_checkpoint_daemon-garbage-collector>`
+    The delay in seconds used to prevent the :ref:`Tarantool garbage collector <cfg_checkpoint_daemon-garbage-collector>`
     from immediately removing :ref:`write-ahead log <internals-wal>` files after a node restart.
     This delay eliminates possible erroneous situations when the master deletes WALs
     needed by :ref:`replicas <replication-roles>` after restart.
     As a consequence, replicas sync with the master faster after its restart and
     don't need to download all the data again.
-
-    Once all the nodes in the replica set are up and running,
-    automatic cleanup is started again even if ``wal_cleanup_delay`` has not expired.
+    Once all the nodes in the replica set are up and running, a scheduled garbage collection is started again
+    even if ``wal_cleanup_delay`` has not expired.
 
     .. NOTE::