Add example + integrate peer feedback

Author: lenkis

doc/reference/reference_lua/box_stat.rst

@@ -27,10 +27,10 @@ Below is a list of all ``box.stat`` functions.
             - Show network activity
 
         *   - :doc:`./box_stat/memtx`
-            -  Show memtx-storage-engine activity
+            -  Show ``memtx`` storage engine activity
 
         *   - :doc:`./box_stat/vinyl`
-            -  Show vinyl-storage-engine activity
+            -  Show ``vinyl`` storage engine activity
 
         *   - :doc:`./box_stat/reset`
             - Reset the statistics

doc/reference/reference_lua/box_stat/memtx.rst

@@ -40,20 +40,21 @@ box.stat.memtx().tx
         (equals ``total`` / number of open transactions).
       * ``max`` is the maximal number of bytes that a single transaction uses.
 
-  * ``box.stat.memtx().tx.mvcc`` shows memory allocation related to multiversion
-    concurrency control (MVCC). MVCC is reponsible for isolating transactions.
+  * ``box.stat.memtx().tx.mvcc`` shows memory allocation related to
+    :ref:`multiversion concurrency control (MVCC) <txn_mode_transaction-manager>`.
+    MVCC is reponsible for isolating transactions.
     It reveals conflicts and makes sure that tuples that do not belong to a particular
     space but were (or could be) read by some transaction were not deleted.
 
     It consists of the following sections:
 
     * ``trackers`` is the memory allocated for *trackers* of transaction reads.
       Like in the previous sections, Tarantool reports the total, average
-      and maximum number of bytes allocated for trackers per a single transaction.
+      and maximal number of bytes allocated for trackers per a single transaction.
     * ``conflicts`` is the memory allocated for *conflicts*
       which are entities created when transactional conflicts occur.
       Like in the previous sections, Tarantool reports the total, average
-      and maximum number of allocated bytes.
+      and maximal number of allocated bytes.
     * ``tuples`` is the memory allocated for storing tuples.
       With MVCC, tuples are stored using the *stories* mechanism. Nearly every
       tuple has its story. Even tuples in an index may have their stories, so
@@ -79,3 +80,91 @@ box.stat.memtx().tx
 
         * ``count`` is the number of stories or retained tuples.
         * ``total`` is the number of bytes allocated for stories or retained tuples.
+
+**Example**
+
+Let's take a look at `used` and `retained` tuples in a transaction.
+
+Within the first ``box.cfg()`` call to a new Tarantool instance, we
+:ref:`enable the MVCC engine <txn_mode_mvcc-enabling>`:
+
+.. code-block:: console
+
+   box.cfg{memtx_use_mvcc_engine = true}
+
+Next, we create a space with a primary index, and begin a transaction:
+
+.. code-block:: console
+
+   box.schema.space.create('test')
+   box.space.test:create_index('pk')
+
+   box.begin()
+   box.space.test:replace{0, 0}
+   box.space.test:replace{0, string.rep('a', 100)}
+   box.space.test:replace{0, 1}
+   box.space.test:replace{1, 1}
+   box.space.test:replace{2, 1}
+
+In the transaction above, we replace three tuples by the `0` key:
+
+* ``{0, 0}``
+* ``{0, 'aa...aa'}``
+* ``{0, 1}``
+
+MVCC considers all these tuples as `used` since they belong to the current transaction.
+Meanwhile, MVCC considers tuples ``{0, 0}`` and ``{0, 'aa..aa'}`` as `retained` because
+they don't belong to any index (unlike ``{0, 1}``), but they cannot be deleted yet.
+
+If we call ``box.stat.memtx.tx()`` now, we'll see something like this:
+
+.. code-block:: javascript
+   :emphasize-lines: 33-39
+
+	tarantool> box.stat.memtx.tx()
+	---
+	- txn:
+	    statements:
+	      max: 720
+	      avg: 720
+	      total: 720
+	    user:
+	      max: 0
+	      avg: 0
+	      total: 0
+	    system:
+	      max: 916
+	      avg: 916
+	      total: 916
+	  mvcc:
+	    trackers:
+	      max: 0
+	      avg: 0
+	      total: 0
+	    conflicts:
+	      max: 0
+	      avg: 0
+	      total: 0
+	    tuples:
+	      tracking:
+	        stories:
+	          count: 0
+	          total: 0
+	        retained:
+	          count: 0
+	          total: 0
+	      used:
+	        stories:
+	          count: 6
+	          total: 944
+	        retained:
+	          count: 2
+	          total: 119
+	      read_view:
+	        stories:
+	          count: 0
+	          total: 0
+	        retained:
+	          count: 0
+	          total: 0
+	...