Add space.stat() and tuple.info() reference (#4373)

Resolves #3841 #3840

Author: p7nov

doc/reference/reference_lua/box_space.rst

@@ -88,6 +88,9 @@ Below is a list of all ``box.space`` functions and members.
         *  - :doc:`./box_space/select`
            - Select one or more tuples
 
+        *  - :doc:`./box_space/stat`
+           - Get statistics on memory usage
+
         *  - :doc:`./box_space/truncate`
            - Delete all tuples
 
@@ -202,6 +205,7 @@ To see examples, visit the :ref:`how-to guide on CRUD operations <box_space_exam
     box_space/replace
     box_space/run_triggers
     box_space/select
+    box_space/stat
     box_space/truncate
     box_space/update
     box_space/upsert

doc/reference/reference_lua/box_space/stat.rst

@@ -0,0 +1,48 @@
+.. _box_space-stat:
+
+space_object:stat()
+===================
+
+.. class:: space_object
+
+    .. method:: stat()
+
+        Get statistics on memory usage by the space.
+
+        Returns a table with the cumulative statistics on the memory usage by tuples in the space.
+        Statistics are grouped by arena types: ``memtx`` or ``malloc``.
+        For each arena type, the return table includes tuple memory usage statistics
+        listed in the :ref:`box_tuple-info` reference.
+
+        .. note::
+
+            Memory usage statistics are shown only for the memtx storage engine.
+            For other types of spaces, an empty table is returned.
+
+        :param space_object space_object: an :ref:`object reference
+                                          <app_server-object_reference>`
+
+        :return: space memory usage statistics
+        :rtype: table
+
+        **Possible errors:** ``space_object`` does not exist.
+
+
+        **Example:**
+
+        .. code-block:: tarantoolsession
+
+            tarantool> box.space.tester:stat()
+            ---
+            - tuple:
+                memtx:
+                  waste_size: 145
+                  data_size: 235
+                  header_size: 36
+                  field_map_size: 24
+                malloc:
+                  waste_size: 0
+                  data_size: 0
+                  header_size: 0
+                  field_map_size: 0
+            ...

doc/reference/reference_lua/box_tuple.rst

@@ -47,6 +47,9 @@ Below is a list of all ``box.tuple`` functions.
         *  - :doc:`./box_tuple/find`
            - Get the number of the first field/all fields matching the search value
 
+        *  - :doc:`./box_tuple/info`
+           - Get information about the tuple
+
         *  - :doc:`./box_tuple/next`
            - Get the next field value from tuple
 
@@ -82,6 +85,7 @@ Below is a list of all ``box.tuple`` functions.
     box_tuple/field_name
     box_tuple/field_path
     box_tuple/find
+    box_tuple/info
     box_tuple/next
     box_tuple/pairs
     box_tuple/totable

doc/reference/reference_lua/box_tuple/info.rst

@@ -0,0 +1,45 @@
+
+.. _box_tuple-info:
+
+tuple_object.info()
+===================
+
+.. class:: tuple_object
+
+    .. method:: info()
+
+        Get information about the tuple memory usage.
+
+        Returns a table with the following fields:
+
+        -   ``data_size`` -- size of MessagePack data in the tuple.
+            This number equals to number returned by :ref:`box_tuple-bsize`.
+        -   ``header_size`` - size of the internal tuple header.
+        -   ``field_map_size`` -- size of the field map.
+            Field map is used to speed up access to indexed fields of the tuple.
+        -   ``waste_size`` -- amount of excess memory wasted due to internal fragmentation in the `slab allocator <https://github.com/tarantool/small>`_.
+
+            .. note::
+
+                `waste_size` is provided for reference only and can be inaccurate.
+                Avoid using it for memory usage calculations.
+
+        -   ``arena`` - type of the arena where the tuple is allocated.
+            Possible values are: ``memtx``, ``malloc``, ``runtime``.
+
+        :return: tuple memory usage statistics
+        :rtype: table
+
+
+        **Example**
+
+        .. code-block:: tarantoolsession
+
+            tarantool> box.space.tester:get('222200000'):info()
+            ---
+            - data_size: 55
+              waste_size: 95
+              arena: memtx
+              field_map_size: 4
+              header_size: 6
+            ...

doc/release/3.0.0.rst

@@ -148,7 +148,7 @@ You can see the total memory usage using :ref:`box.slab.info() <box_slab_info>`:
     - 75302024
     ...
 
-A new ``space_object:stat()`` method allows you to determine how the additional 5 Mb of memory is used:
+A new `space_object:stat() <box_space-stat>` method allows you to determine how the additional 5 Mb of memory is used:
 
 .. code-block:: console
 
@@ -173,7 +173,7 @@ The above report gives the following information:
 -   ``data_size``: the actual size of data, which equals to ``space_object:bsize()``.
 -   ``waste_size``: the size of memory wasted due to internal fragmentation in the `slab allocator <https://github.com/tarantool/small>`_.
 
-To get such information about a specific tuple, use ``tuple_object:info()``:
+To get such information about a specific tuple, use :ref:`tuple_object:info() <box_tuple-info>`:
 
 .. code-block:: console