Submodule box.info

Submodule box.info

The box.info 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 box.space._schema system space.
  • id corresponds to replication.id (see below).
  • lsn corresponds to replication.lsn (see below).
  • memory has 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{}).
  • signature is the sum of all lsn values from the vector clocks (vclock) of all instances in the replica set.
  • 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 vinyl storage engine.

The memory function of box.info gives the admin user a picture of the whole Tarantool instance. (Use box.info.vinyl() instead for a picture specifically of the vinyl subsystem.)

  • 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:

tarantool> box.info.memory()
- cache: 0
  data: 6552
  tx: 0
  lua: 1315567
  net: 98304
  index: 1196032

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

  • replication.id 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 box.space._cluster 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 the instance’s role is “replica” (read-only) and 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).
  • 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.

Since box.info contents are dynamic, it’s not possible to iterate over keys with the Lua pairs() function. For this purpose, box.info() 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.

tarantool> box.info()
- version: 1.7.6-68-g51fcffb77
  id: 2
  ro: true
  vclock: {1: 5}
  uptime: 917
  lsn: 0
  vinyl: []
    uuid: 783e2285-55b1-42d4-b93c-68dcbb7a8c18
  pid: 35341
  status: running
  signature: 5
      id: 1
      uuid: 471cd36e-cb2e-4447-ac66-2d28e9dd3b67
      lsn: 5
        status: follow
        idle: 124.98795700073
        peer: replicator@
        lag: 0
        vclock: {1: 5}
      id: 2
      uuid: ac45d5d2-8a16-4520-ad5e-1abba6baba0a
      lsn: 0
  uuid: ac45d5d2-8a16-4520-ad5e-1abba6baba0a