Add space.stat and tuple.info reference

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 the sum of memory usage statitics
+        of tuples stored in this arena. See :ref:`box_tuple-info` for details.
+
+        .. note::
+
+            The statistics is collected only for 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: 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,38 @@
+
+.. _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 used to store the tuple
+            in mempool.
+        -   ``arena`` - type of the arena where the tuple is allocated.
+            Possible values are: ``memtx``, ``malloc``, ``runtime``.
+
+        :return: 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
+            ...