Update docs for the 'box.info' module (#4427)

Author: andreyaksenov

doc/reference/configuration/cfg_replication.rst

@@ -16,6 +16,10 @@
 * :ref:`election_mode <cfg_replication-election_mode>`
 * :ref:`election_timeout <cfg_replication-election_timeout>`
 * :ref:`election_fencing_mode <cfg_replication-election_fencing_mode>`
+* :ref:`instance_name <cfg_replication-instance_name>`
+* :ref:`replicaset_name <cfg_replication-replicaset_name>`
+* :ref:`cluster_name <cfg_replication-cluster_name>`
+
 
 .. _cfg_replication-replication:
 
@@ -708,3 +712,87 @@
     | Default: 'soft'
     | Environment variable: TT_ELECTION_FENCING_MODE
     | Dynamic: yes
+
+.. _cfg_replication-instance_name:
+
+.. confval:: instance_name
+
+    Since version :doc:`3.0.0 </release/3.0.0>`.
+
+    Specify the instance name.
+    This value must be unique in a replica set.
+
+    The following rules are applied to instance names:
+
+    -   The maximum number of symbols is 63.
+    -   Should start with a letter.
+    -   Can contain lowercase letters (a-z). If uppercase letters are used, they are converted to lowercase.
+    -   Can contain digits (0-9).
+    -   Can contain the following characters: ``-``, ``_``.
+
+    To change or remove the specified name, you should temporarily set the :ref:`box.cfg.force_recovery <cfg_binary_logging_snapshots-force_recovery>` configuration option to ``true``.
+    When all the names are updated and all the instances synced, ``box.cfg.force_recovery`` can be set back to ``false``.
+
+    ..  NOTE::
+
+        The instance name is persisted in the :ref:`box.space._cluster <box_space-cluster>` system space.
+
+    See also: :ref:`box_info_name`
+
+    |
+    | Type: string
+    | Default: null
+    | Environment variable: TT_INSTANCE_NAME
+    | Dynamic: no
+
+.. _cfg_replication-replicaset_name:
+
+.. confval:: replicaset_name
+
+    Since version :doc:`3.0.0 </release/3.0.0>`.
+
+    Specify the name of a replica set to which this instance belongs.
+    This value must be the same for all instances of the replica set.
+
+    See the :ref:`instance_name <cfg_replication-instance_name>` description to learn:
+
+    -   which rules are applied to names
+    -   how to change or remove an already specified name
+
+    ..  NOTE::
+
+        The replica set name is persisted in the :ref:`box.space._schema <box_space-schema>` system space.
+
+    See also: :ref:`box_info_replicaset`
+
+    |
+    | Type: string
+    | Default: null
+    | Environment variable: TT_REPLICASET_NAME
+    | Dynamic: no
+
+.. _cfg_replication-cluster_name:
+
+.. confval:: cluster_name
+
+    Since version :doc:`3.0.0 </release/3.0.0>`.
+
+    Specify the name of a cluster to which this instance belongs.
+    This value must be the same for all instances of the cluster.
+
+    See the :ref:`instance_name <cfg_replication-instance_name>` description to learn:
+
+    -   which rules are applied to names
+    -   how to change or remove an already specified name
+
+    ..  NOTE::
+
+        The cluster name is persisted in the :ref:`box.space._schema <box_space-schema>` system space.
+
+    See also: :ref:`box_info_cluster`
+
+    |
+    | Type: string
+    | Default: null
+    | Environment variable: TT_CLUSTER_NAME
+    | Dynamic: no

doc/reference/configuration/configuration_reference.rst

@@ -2582,6 +2582,14 @@ The ``groups`` section provides the ability to define the :ref:`full topology of
 
     A group name.
 
+    The following rules are applied to group names:
+
+    -   The maximum number of symbols is 63.
+    -   Should start with a letter.
+    -   Can contain lowercase letters (a-z).
+    -   Can contain digits (0-9).
+    -   Can contain the following characters: ``-``, ``_``.
+
 .. _configuration_reference_groups_name_replicasets:
 
 .. confval:: groups.<group_name>.replicasets
@@ -2616,6 +2624,9 @@ replicasets
 
     A replica set name.
 
+    Note that the rules applied to a replica set name are the same as for groups.
+    Learn more in :ref:`groups.\<group_name\> <configuration_reference_groups_name>`.
+
 .. _configuration_reference_replicasets_name_leader:
 
 .. confval:: replicasets.<replicaset_name>.leader
@@ -2679,6 +2690,9 @@ instances
 
     An instance name.
 
+    Note that the rules applied to an instance name are the same as for groups.
+    Learn more in :ref:`groups.\<group_name\> <configuration_reference_groups_name>`.
+
 .. _configuration_reference_instances_name_config_parameter:
 
 .. confval:: instances.<instance_name>.<config_parameter>

doc/reference/reference_lua/box_info.rst

@@ -6,60 +6,7 @@ Submodule box.info
 
 .. module:: box.info
 
-The ``box.info`` submodule provides access to information about server instance
-variables.
-
-* **cluster.uuid** is the UUID of the replica set.
-  Every instance in a replica set will have the same ``cluster.uuid`` value.
-  This value is also stored in :ref:`box.space._schema <box_space-schema>`
-  system space.
-* **gc()** returns the state of the
-  :ref:`Tarantool garbage collector <cfg_checkpoint_daemon-garbage-collector>`
-  including the checkpoints and their consumers (users); see details
-  :doc:`here </reference/reference_lua/box_info/gc>`.
-* **id** corresponds to :samp:`replication[{n}].id`
-  (see :doc:`here </reference/reference_lua/box_info/replication>`).
-* **lsn** corresponds to :samp:`replication[{n}].lsn`
-  (see :doc:`here </reference/reference_lua/box_info/replication>`).
-* **listen** returns a real address to which an instance was bound
-  (see :doc:`here </reference/reference_lua/box_info/listen>`).
-* **memory()** returns the statistics about memory
-  (see :doc:`here </reference/reference_lua/box_info/memory>`).
-* **pid** is the process ID. This value is also shown by
-  :ref:`tarantool <tarantool-build>` module
-  and by the Linux command ``ps -A``.
-* **ro** is ``true`` if the instance is in read-only mode
-  (same as :ref:`read_only <cfg_basic-read_only>` in ``box.cfg{}``),
-  or if status is 'orphan'.
-* **ro_reason** is ``nil`` if the instance is in writable mode.
-  When the field is not ``nil``, it contains the reason why the instance is read-only.
-  Possible error reasons: ``election``, ``synchro``, ``config``, and ``orphan``
-  (see :ref:`box.info.ro_reason <box_info_ro-reason>` for details).
-* **signature** is the sum of all ``lsn`` values from each :ref:`vector clock <replication-vector>`
-  (**vclock**) for all instances in the replica set.
-* **sql().cache.size** is the number of bytes in the SQL prepared statement cache.
-* **sql().cache.stmt_count** is the number of statements in the SQL prepared statement cache.
-* **status** is the current state of the instance. It can be:
-
-  * ``running`` -- the instance is loaded,
-  * ``loading`` -- the instance is either recovering xlogs/snapshots or bootstrapping,
-  * ``orphan`` --  the instance has not (yet) succeeded in joining the required
-    number of masters (see :ref:`orphan status <replication-orphan_status>`),
-  * ``hot_standby`` -- the instance is :ref:`standing by <index-hot_standby>` another instance.
-* **uptime** is the number of seconds since the instance started.
-  This value can also be retrieved with
-  :ref:`tarantool.uptime() <tarantool-build>`.
-* **uuid** corresponds to :samp:`replication[{n}].uuid`
-  (see :doc:`here </reference/reference_lua/box_info/replication>`).
-* **vclock** is a table with the vclock values of all instances in a replica set which have made data changes.
-* **version** is the Tarantool version. This value is also shown by
-  :ref:`tarantool -V <index-tarantool_version>`.
-* **vinyl()** returns runtime statistics for the vinyl storage engine.
-  This function is deprecated, use
-  :ref:`box.stat.vinyl() <box_introspection-box_stat_vinyl>` instead.
-* **election** shows the current state of a replica set node regarding leader
-  election (see :doc:`here </reference/reference_lua/box_info/election>`).
-
+The ``box.info`` submodule provides access to information about a running Tarantool instance.
 Below is a list of all ``box.info`` functions and members.
 
 ..  container:: table
@@ -68,53 +15,125 @@ Below is a list of all ``box.info`` functions and members.
     ..  rst-class:: left-align-column-2
 
     ..  list-table::
-        :widths: 25 75
+        :widths: 30 70
         :header-rows: 1
 
         *   - Name
             - Use
 
         *  - :doc:`./box_info/info`
-           - Return all keys and values provided in the submodule
+           - Get all keys and values provided by the ``box.info`` submodule
+
+        *  - :doc:`./box_info/cluster`
+           - Information about the cluster to which the current instance belongs
+
+        *  - :doc:`./box_info/config`
+           - The instance's state in regard to configuration
+
+        *  - :doc:`./box_info/election`
+           - The current state of this replica set node in regard to leader election
 
         *  - :doc:`./box_info/gc`
-           - Return info about garbage collector
+           - Get information about the Tarantool garbage collector
+
+        *  - :doc:`./box_info/hostname`
+           - The hostname that identifies a machine the current instance is running on
+
+        *  - :doc:`./box_info/id`
+           - A numeric identifier of the current instance within the replica set
+
+        *  - :doc:`./box_info/listen`
+           - A real address to which an instance is bound
+
+        *  - :doc:`./box_info/lsn`
+           - A log sequence number (LSN) for the latest entry in the instance's write-ahead log (WAL)
 
         *  - :doc:`./box_info/memory`
-           - Return info about memory usage
+           - Get information about memory usage for the current instance
+
+        *  - :doc:`./box_info/name`
+           - The name of the current instance
+
+        *  - :doc:`./box_info/package`
+           - The package name
+
+        *  - :doc:`./box_info/pid`
+           - Get a process ID of the current instance
+
+        *  - :doc:`./box_info/replicaset`
+           - Information about the replica set to which the current instance belongs
+
+        *  - :doc:`./box_info/replication`
+           - Statistics for all instances in the replica set
 
         *  - :doc:`./box_info/replication_anon`
            - List all the anonymous replicas following the instance
 
-        *  - :doc:`./box_info/replication`
-           - Return statistics for all instances in the replica set
+        *  - :doc:`./box_info/ro`
+           - The current mode of the instance (writable or read-only)
 
-        *  - :doc:`./box_info/listen`
-           - Return a real address to which an instance was bound
+        *  - :doc:`./box_info/ro_reason`
+           - The reason why the current instance is read-only
 
-        *  - :doc:`./box_info/election`
-           - Show the current state of a replica set node
-             in regards to leader election
+        *  - :doc:`./box_info/schema_version`
+           - The database schema version
+
+        *  - :doc:`./box_info/signature`
+           - The sum of all ``lsn`` values from each vector clock for all instances in the replica set
+
+        *  - :doc:`./box_info/sql`
+           - Get information about the cache for all SQL prepared statements
+
+        *  - :doc:`./box_info/status`
+           - The current state of the instance
 
         *  - :doc:`./box_info/synchro`
-           - Show the current state of synchronous replication
+           - The current state of synchronous replication
 
-        *  - :doc:`./box_info/ro_reason`
-           - Show the current mode of an instance (writable or read-only)
+        *  - :doc:`./box_info/uptime`
+           - The number of seconds since the instance started
+
+        *  - :doc:`./box_info/uuid`
+           - A globally unique identifier of the current instance
+
+        *  - :doc:`./box_info/vclock`
+           - A table with the vclock values of all instances in a replica set which have made data changes
+
+        *  - :doc:`./box_info/version`
+           - The Tarantool version
+
+        *  - :doc:`./box_info/vinyl`
+           - (Deprecated) Get runtime statistics for the vinyl storage engine
 
-        *  - :doc:`./box_info/schema_version`
-           - Show the database schema version
 
 ..  toctree::
     :hidden:
 
     box_info/info
+    box_info/cluster
+    box_info/config
+    box_info/election
     box_info/gc
+    box_info/hostname
+    box_info/id
+    box_info/listen
+    box_info/lsn
     box_info/memory
-    box_info/replication_anon
+    box_info/name
+    box_info/package
+    box_info/pid
+    box_info/replicaset
     box_info/replication
-    box_info/listen
-    box_info/election
-    box_info/synchro
+    box_info/replication_anon
+    box_info/ro
     box_info/ro_reason
     box_info/schema_version
+    box_info/signature
+    box_info/sql
+    box_info/status
+    box_info/synchro
+    box_info/uptime
+    box_info/uuid
+    box_info/vclock
+    box_info/version
+    box_info/vinyl

doc/reference/reference_lua/box_info/cluster.rst

@@ -0,0 +1,18 @@
+.. _box_info_cluster:
+
+================================================================================
+box.info.cluster
+================================================================================
+
+.. module:: box.info
+
+.. data:: cluster
+
+    Information about the cluster to which the current instance belongs.
+    The returned table contains the following fields:
+
+    *   ``name`` -- the cluster name
+
+    See also: :ref:`compat.box_info_cluster_meaning <configuration_reference_compat_cluster_meaning>`
+
+    :rtype: table

doc/reference/reference_lua/box_info/config.rst

@@ -0,0 +1,29 @@
+.. _box_info_config:
+
+================================================================================
+box.info.config
+================================================================================
+
+.. module:: box.info
+
+.. data:: config
+
+    Since: :doc:`3.2.0 </release/3.2.0>`
+
+    The instance's state in regard to configuration.
+    Note that ``box.info.config`` returns the instance's state obtained using :ref:`config:info('v2') <config_api_reference_info>`.
+
+    :rtype: table
+
+    **Example**
+
+    ..  code-block:: tarantoolsession
+
+        sharded_cluster_crud:storage-a-002> box.info.config
+        ---
+        - status: ready
+          meta:
+            last: &0 []
+            active: *0
+          alerts: []
+        ...