Skip to content

Commit 567d022

Browse files
lenkislenkis
authored
Add info on box.stat.memtx().tx (#4535)
Closes gh-4501 Add reference for box.stat.memtx().tx
1 parent 794f3bf commit 567d022

File tree

4 files changed

+185
-4
lines changed

4 files changed

+185
-4
lines changed

‎doc/reference/reference_capi/txn.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@
3939
4040
Roll back the current transaction as far as the specified savepoint.
4141
42+
.. _txn-box_txn_alloc:
43+
4244
.. c:function:: void *box_txn_alloc(size_t size)
4345
4446
Allocate memory on txn memory pool.

‎doc/reference/reference_lua/box_stat.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,11 @@ Below is a list of all ``box.stat`` functions.
2626
* - :doc:`./box_stat/net`
2727
- Show network activity
2828

29+
* - :doc:`./box_stat/memtx`
30+
- Show ``memtx`` storage engine activity
31+
2932
* - :doc:`./box_stat/vinyl`
30-
- Show vinyl-storage-engine activity
33+
- Show ``vinyl`` storage engine activity
3134

3235
* - :doc:`./box_stat/reset`
3336
- Reset the statistics
@@ -37,5 +40,6 @@ Below is a list of all ``box.stat`` functions.
3740

3841
box_stat/stat
3942
box_stat/net
43+
box_stat/memtx
4044
box_stat/vinyl
41-
box_stat/reset
45+
box_stat/reset

‎doc/reference/reference_lua/box_stat/memtx.rst

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
.. _box_introspection-box_stat_memtx:
2+
3+
box.stat.memtx()
4+
================
5+
6+
.. module:: box.stat
7+
8+
.. function:: memtx()
9+
10+
Shows ``memtx`` storage engine activity.
11+
12+
.. _box_introspection-box_stat_memtx_tx:
13+
14+
box.stat.memtx().tx
15+
-------------------
16+
17+
``tx`` shows the statistics of the memtx transactional manager,
18+
which is responsible for transactions (``box.stat.memtx().tx.txn``)
19+
and multiversion concurrency control (``box.stat.memtx().tx.mvcc``).
20+
21+
* ``box.stat.memtx().tx.txn`` shows memory allocation related to transactions.
22+
23+
It consists of the following sections:
24+
25+
* ``statements`` are *transaction statements*.
26+
As an example, consider a user starting a transaction with
27+
``space:replace{0, 1}`` within this transaction. Under the hood,
28+
this operation becomes a statement for this transaction.
29+
* ``user`` is the memory that a user allocated within
30+
the current transaction using the Tarantool C API function
31+
:ref:`box_txn_alloc() <txn-box_txn_alloc>`.
32+
* ``system`` is the memory allocated for internal needs
33+
(for example, logs) and savepoints.
34+
35+
.. _box_introspection-box_stat_memtx_tx_total_avg_max:
36+
37+
For each section, Tarantool reports the following statistics:
38+
39+
* ``total`` is the number of bytes that are currently allocated in memtx
40+
for all transactions within the section scope.
41+
* ``avg`` is the average number of bytes that a single transaction uses
42+
(equals ``total`` / number of open transactions).
43+
* ``max`` is the maximal number of bytes that a single transaction uses.
44+
45+
* ``box.stat.memtx().tx.mvcc`` shows memory allocation related to
46+
:ref:`multiversion concurrency control (MVCC) <txn_mode_transaction-manager>`.
47+
MVCC is reponsible for isolating transactions.
48+
It reveals conflicts and makes sure that tuples that do not belong to a particular
49+
space but were (or could be) read by some transaction were not deleted.
50+
51+
It consists of the following sections:
52+
53+
* ``trackers`` is the memory allocated for *trackers* of transaction reads.
54+
Like in the :ref:`previous sections <box_introspection-box_stat_memtx_tx_total_avg_max>`,
55+
Tarantool reports the total, average, and maximal number of bytes allocated
56+
for trackers per a single transaction.
57+
* ``conflicts`` is the memory allocated for *conflicts*
58+
which are entities created when transactional conflicts occur.
59+
Like in the :ref:`previous sections <box_introspection-box_stat_memtx_tx_total_avg_max>`,
60+
Tarantool reports the total, average, and maximal number of allocated bytes.
61+
* ``tuples`` is the memory allocated for storing tuples.
62+
With MVCC, tuples are stored using the *stories* mechanism. Nearly every
63+
tuple has its story. Even tuples in an index may have their stories, so
64+
it may be useful to differentiate memory allocated for tuples and memory
65+
allocated for stories.
66+
67+
All stored tuples fall into three categories, with memory statistics
68+
reported for each category:
69+
70+
* ``tracking`` is for tuples that are not used by any transactions directly,
71+
but MVCC uses them for tracking transaction reads.
72+
* ``used`` is for tuples that are used by active read-write transactions.
73+
See a detailed :ref:`example <box_introspection-box_stat_memtx_tx_example>` below.
74+
* ``read_view`` is for tuples that are not used by active read-write transactions,
75+
but are used by read-only transactions.
76+
77+
For each of the three categories, Tarantool reports two statistical blocks:
78+
79+
* ``stories`` is for stories.
80+
* ``retained`` is for *retained* tuples which do not belong to any index,
81+
but MVCC doesn't allow to delete them yet.
82+
83+
For each block, Tarantool reports the following statistics:
84+
85+
* ``count`` is the number of stories or retained tuples.
86+
* ``total`` is the number of bytes allocated for stories or retained tuples.
87+
88+
.. _box_introspection-box_stat_memtx_tx_example:
89+
90+
**Example**
91+
92+
This example illustrates memory statistics for ``used`` tuples in a transaction.
93+
94+
The cluster must be started with the :ref:`database.use_mvcc_engine <configuration_reference_database_use_mvcc_engine>`
95+
parameter set to true. This :ref:`enables MVCC <txn_mode_mvcc-enabling>` so that
96+
``box.stat.memtx.tx().mvcc`` contains non-zero values.
97+
98+
The next step is to create a space with a primary index and to begin a transaction:
99+
100+
.. code-block:: lua
101+
102+
box.schema.space.create('test')
103+
box.space.test:create_index('pk')
104+
105+
box.begin()
106+
box.space.test:replace{0, 0}
107+
box.space.test:replace{0, string.rep('a', 100)}
108+
box.space.test:replace{0, 1}
109+
box.space.test:replace{1, 1}
110+
box.space.test:replace{2, 1}
111+
112+
In the transaction above, three tuples are replaced by the `0` key:
113+
114+
* ``{0, 0}``
115+
* ``{0, 'aa...aa'}``
116+
* ``{0, 1}``
117+
118+
MVCC considers all these tuples as ``used`` since they belong to the current transaction.
119+
Also, MVCC considers tuples ``{0, 0}`` and ``{0, 'aa..aa'}`` as ``retained`` because
120+
they don't belong to any index (unlike ``{0, 1}``) but cannot be deleted yet.
121+
122+
Calling ``box.stat.memtx.tx()`` now returns the following result:
123+
124+
.. code-block:: tarantoolsession
125+
:emphasize-lines: 33-39
126+
127+
tarantool> box.stat.memtx.tx()
128+
---
129+
- txn:
130+
statements:
131+
max: 720
132+
avg: 720
133+
total: 720
134+
user:
135+
max: 0
136+
avg: 0
137+
total: 0
138+
system:
139+
max: 916
140+
avg: 916
141+
total: 916
142+
mvcc:
143+
trackers:
144+
max: 0
145+
avg: 0
146+
total: 0
147+
conflicts:
148+
max: 0
149+
avg: 0
150+
total: 0
151+
tuples:
152+
tracking:
153+
stories:
154+
count: 0
155+
total: 0
156+
retained:
157+
count: 0
158+
total: 0
159+
used:
160+
stories:
161+
count: 6
162+
total: 944
163+
retained:
164+
count: 2
165+
total: 119
166+
read_view:
167+
stories:
168+
count: 0
169+
total: 0
170+
retained:
171+
count: 0
172+
total: 0
173+
...
174+
175+
Pay attention to highlighted lines -- it's the memory allocated for `used` tuples.

‎doc/reference/reference_lua/box_stat/reset.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,6 @@ box.stat.reset()
77

88
.. function:: reset()
99

10-
Resets the statistics of ``box.stat()``,
11-
``box.stat.net()``, ``box.stat.vinyl()``, and
10+
Resets the statistics of ``box.stat()``, ``box.stat.net()``,
11+
``box.stat.memtx()``, ``box.stat.vinyl()``, and
1212
:ref:`box.space.index <box_space-space_index>`.

0 commit comments

Comments
 (0)