The 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 system space.
  • gc() returns the state of the Tarantool garbage collector including the checkpoints and their consumers (users); see details below.
  • id corresponds to (see below).
  • lsn corresponds to replication.lsn (see below).
  • memory() returns the statistics about memory (see below).
  • pid is the process ID. This value is also shown by tarantool module and by the Linux command ps -A.
  • ro is true if the instance is in “read-only” mode (same as read_only in box.cfg{}), or if status is ‘orphan’.
  • signature is the sum of all lsn values from the vector clocks (vclock) of 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 corresponds to replication.upstream.status (see below).
  • uptime is the number of seconds since the instance started. This value can also be retrieved with tarantool.uptime().
  • uuid corresponds to replication.uuid (see below).
  • vclock corresponds to replication.downstream.vclock (see below).
  • version is the Tarantool version. This value is also shown by tarantool -V.
  • vinyl() returns runtime statistics for the vinyl storage engine. This function is deprecated, use box.stat.vinyl() instead.

The memory function of gives the admin user a picture of the whole Tarantool instance.


To get a picture of the vinyl subsystem, use box.stat.vinyl() instead.

  • memory().cache – number of bytes used for caching user data. The memtx storage engine does not require a cache, so in fact this is the number of bytes in the cache for the tuples stored for the vinyl storage engine.
  • memory().data – number of bytes used for storing user data (the tuples) with the memtx engine and with level 0 of the vinyl engine, without taking memory fragmentation into account.
  • memory().index – number of bytes used for indexing user data, including memtx and vinyl memory tree extents, the vinyl page index, and the vinyl bloom filters.
  • memory().lua – number of bytes used for Lua runtime.
  • memory().net – number of bytes used for network input/output buffers.
  • memory().tx – number of bytes in use by active transactions. For the vinyl storage engine, this is the total size of all allocated objects (struct txv, struct vy_tx, struct vy_read_interval) and tuples pinned for those objects.

An example with a minimum allocation while only the memtx storage engine is in use:

- cache: 0
  data: 6552
  tx: 0
  lua: 1315567
  net: 98304
  index: 1196032

The gc function of gives the admin user a picture of the factors that affect the Tarantool garbage collector. The garbage collector compares vclock (vector clock) values of users and checkpoints, so a look at may show why the garbage collector has not removed old WAL files, or show what it may soon remove.

  • gc().consumers – a list of users whose requests might affect the garbage collector.
  • gc().checkpoints – a list of preserved checkpoints.
  • gc().checkpoints[n].references – a list of references to a checkpoint.
  • gc().checkpoints[n].vclock – a checkpoint’s vclock value.
  • gc().checkpoints[n].signature – a sum of a checkpoint’s vclock’s components.
  • gc().checkpoint_is_in_progress – true if a checkpoint is in progress, otherwise false
  • gc().vclock – the garbage collector’s vclock.
  • gc().signature – the sum of the garbage collector’s checkpoint’s components.

The replication section of contains statistics for all instances in the replica set in regard to the current instance (see also “Monitoring a replica set”):

  • is a short numeric identifier of the instance within the replica set.
  • replication.uuid is a globally unique identifier of the instance. This value is also stored in system space.
  • replication.lsn is the log sequence number (LSN) for the latest entry in the instance’s write ahead log (WAL).
  • replication.upstream contains statistics for the replication data uploaded by the instance.
  • replication.upstream.status is the replication status of the instance:
    • auth means that the instance is getting authenticated to connect to a replication source.
    • connecting means that the instance is trying to connect to the replications source(s) listed in its replication parameter.
    • disconnected means that the instance is not connected to the replica set (due to network problems, not replication errors).
    • follow means that replication is in progress.
    • running means the instance’s role is “master” (non read-only) and replication is in progress.
    • stopped means that replication was stopped due to a replication error (e.g. duplicate key).
    • orphan means that the instance has not (yet) succeeded in joining the required number of masters (see orphan status).
    • sync means that the master and replica are synchronizing to have the same data.
  • replication.upstream.idle is the time (in seconds) since the instance received the last event from a master. This is the primary indicator of replication health. See more in Monitoring a replica set.
  • replication.upstream.peer contains the replication user name, host IP adress and port number used for the instance. See more in Monitoring a replica set.
  • replication.upstream.lag is the time difference between the local time at the instance, recorded when the event was received, and the local time at another master recorded when the event was written to the write ahead log on that master. See more in Monitoring a replica set.
  • replication.upstream.message contains an error message in case of a degraded state, empty otherwise.
  • replication.downstream contains statistics for the replication data requested and downloaded from the instance.
  • replication.downstream.vclock contains the vector clock, which is a table of ‘id, lsn’ pairs, for example vclock: {1: 3054773, 4: 8938827, 3: 285902018}. Even if an instance is removed, its values will still appear here.
  • replication.downstream.idle is the time (in seconds) since the last time this instance sent events through the downstream replication.
  • replication.downstream.status is the replication status for downstream replications:
    • stopped means that downstream replication has stopped.
    • follow means that downstream replication is in progress.

Since contents are dynamic, it’s not possible to iterate over keys with the Lua pairs() function. For this purpose, builds and returns a Lua table with all keys and values provided in the submodule.

Return:keys and values in the submodule


This example is for a master-replica set that contains one master instance and one replica instance. The request was issued at the replica instance.

- vinyl: []
  version: 2.2.0-482-g8c84932ad
  id: 2
  ro: true
  status: running
  vclock: {1: 9}
  uptime: 356
  lsn: 0
  memory: []
    uuid: e261a5bc-6303-4de3-9873-556f311255e0
  pid: 160
  gc: []
  signature: 9
      id: 1
      uuid: fce71bb3-0e99-40ec-ab7e-5159487e18d1
      lsn: 9
        status: follow
        idle: 0.035709699994186
        peer: replicator@
        lag: 0.00016164779663086
        status: follow
        idle: 0.59840899999836
        vclock: {1: 9}
      id: 2
      uuid: bc4629ce-ea31-4f75-b805-a4807bcacc93
      lsn: 0
  uuid: bc4629ce-ea31-4f75-b805-a4807bcacc93