Appendixes

Appendixes

Appendixes

Appendix A. Audit log

Audit log provides records on the Tarantool DBMS events in the JSON-format. The following event logs are available:

  • successful/failed user authentication and authorization,
  • closed connection,
  • password change,
  • creation/deletion of a user/role,
  • enabling/disabling a user,
  • changing privileges of a user/role.

Log structure

Key Type Description Example
type string type of event
<“access_denied”>
type_id number id of event
<8>
description string description of event
<“Authentication failed”>
time string time of event
<“YYYY-MM-DDTHH:MM:SS.03f[+|-]GMT”>
peer string remote client
<“ip:port”>
user string user
<“user”>
param string parameters of event see below

Events description

Event Key Parameters
user authorized successfully auth_ok
{“name”: “user”}
user authorization failed auth_fail
{“name”: “user”}
user logged out or quit the session disconnect  
failed access attempts to secure data (personal records, details, geolocation, etc.) access_denied
{“name”: “obj_name”,
“obj_type“: “space”,
“access_type”: “read”}
creating a user user_create
{“name”: “user”}
dropping a user user_drop
{“name”: “user”}
disabling a user user_disable
{“name”: “user”}
enabling a user user_enable
{“name”: “user”}
granting (changing) privileges (roles, profiles, etc.) for the user user_priv
{“name”: “user”}
“obj_name”: “obj_name”,
“obj_type”: “space”,
“old_priv”: “”,
“new_priv”: “read,write”}
resetting password of the user (the user making changes should be specified) password_change
{“name”: “user”}
creating a role role_create
{“name”: “role”}
granting (changing) privileges for the role role_priv
{“name”: “role”}
“obj_name”: “obj_name”,
“obj_type”: “space”,
“old_priv”: “”,
“new_priv”: “read,write”}

Appendix B. Useful Tarantool parameters

  • box.info
  • box.info.replication
  • box.info.memory
  • box.stat
  • box.stat.net
  • box.slab.info
  • box.slab.stats

For details, please see reference on module `box` in the main Tarantool documentation.

Appendix C. Monitoring system metrics

Option Description SNMP type Units of measure Threshold
Version Tarantool version DisplayString    
IsAlive instance availability indicator

Integer

(listing)

 

0 - unavailable

1 - available

MemoryLua storage space used by Lua Gauge32 Mbyte 900
MemoryData storage space used for storing data Gauge32 Mbyte set the value manually
MemoryNet storage space used for network I/O Gauge32 Mbyte 1024
MemoryIndex storage space used for storing indexes Gauge32 Mbyte set the value manually
MemoryCache storage space used for storing caches (for vinyl engine only) Gauge32 Mbyte  
ReplicationLag lag time since the last sync between (the maximum value in case there are multiple fibers) Integer32 sec. 5
FiberCount number of fibers Gauge32 pc. 1000
CurrentTime current time, in seconds, starting at January, 1st, 1970 Unsigned32 Unix timestamp, in sec.  
StorageStatus status of a replica set Integer listing > 1
StorageAlerts number of alerts for storage nodes Gauge32 pc. >= 1
StorageTotalBkts total number of buckets in the storage Gauge32 pc. < 0
StorageActiveBkts number of buckets in the ACTIVE state Gauge32 pc. < 0
StorageGarbageBkts number of buckets in the GARBAGE state Gauge32 pc. < 0
StorageReceivingBkts number of buckets in the RECEIVING state Gauge32 pc. < 0
StorageSendingBkts number of buckets in the SENDING state Gauge32 pc. < 0
RouterStatus status of the router Integer listing > 1
RouterAlerts number of alerts for the router Gauge32 pc. >= 1
RouterKnownBkts number of buckets within the known destination replica sets Gauge32 pc. < 0
RouterUnknownBkts number of buckets that are unknown to the router Gauge32 pc. < 0
RequestCount total number of requests Counter64 pc.  
InsertCount total number of insert requests Counter64 pc.  
DeleteCount total number of delete requests Counter64 pc.  
ReplaceCount total number of replace requests Counter64 pc.  
UpdateCount total number of update requests Counter64 pc.  
SelectCount total number of select requests Counter64 pc.  
EvalCount number of calls made via Eval Counter64 pc.  
CallCount number of calls made via call Counter64 pc.  
ErrorCount number of errors in Tarantool Counter64 pc.  
AuthCount number of completed authentication operations Counter64 pc.  

Appendix D. Deprecated features

The ZooKeeper along with orchestrator are no longer supported. However, they still can be used, if necessary.

The following sections describe the corresponding functionality.

Controlling the cluster via API

To control the cluster, use the orchestrator included in the delivery package. The orchestrator uses ZooKeeper to store and distribute the configuration. The orchestrator provides the REST API for controlling the cluster. Configurations in the ZooKeeper are changed as a result of calling the orchestrator’s API-functions, which in turn leads to changes in configurations of the Tarantool nodes.

We recommend using a curl command line interface to call the API-functions of the orchestrator.

The following example shows how to register a new availability zone (DC):

$ curl -X POST http://HOST:PORT/api/v1/zone \
    -d '{
  "name": "Caucasian Boulevard"
  }'

To check whether the DC registration was successful, try the following instruction. It retrieves the list of all registered nodes in the JSON format:

$ curl http://HOST:PORT/api/v1/zone| python -m json.tool

To apply the new configuration directly on the Tarantool nodes, increase the configuration version number after calling the API function. To do this, use the POST request to /api/v1/version:

$ curl -X POST http://HOST:PORT/api/v1/version

Altogether, to update the cluster configuration:

  1. Call the POST/PUT method of the orchestrator.
    As a result, the ZooKeeper nodes are updated, and a subsequent update of the Tarantool nodes is initiated.
  2. Update the configuration version using the POST request to /api/v1/version.
    As a result, the configuration is applied to the Tarantool nodes.

See Appendix E for the detailed orchestrator API.

Setting up geo redundancy

Logically, cluster nodes can belong to some availability zone. Physically, an availability zone is a separate DC, or a rack inside a DC. You can specify a matrix of weights (distances) for the availability zones.

New zones are added by calling a corresponding API method of the orchestrator.

By default, the matrix of weights (distances) for the zones is not configured, and geo-redundancy for such configurations works as follows:

  • Data is always written to the master.
  • If the master is available, then it is used for reading.
  • If the master is unavailable, then any available replica is used for reading.

When you define a matrix of weights (distances) by calling /api/v1/zones/weights, the automatic scale-out system of the Tarantool DBMS finds a replica which is the closest to the specified router in terms of weights, and starts using this replica for reading. If this replica is not available, then the next nearest replica is selected, taking into account the distances specified in the configuration.

Appendix E. Orchestrator API reference

Configuring the zones

POST /api/v1/zone

Create a new zone.

Request

{
"name": "zone 1"
}

Response

{
"error": {
    "code": 0,
    "message": "ok"
},
"data": {
    "id": 2,
    "name": "zone 2"
},
"status": true
}

Potential errors

  • zone_exists - the specified zone already exists
GET /api/v1/zone/{zone_id: optional}

Return information on the specified zone or on all the zones.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": [
        {
            "id": 1,
            "name": "zone 11"
        },
        {
            "id": 2,
            "name": "zone 2"
        }
    ],
    "status": true
}

Potential errors

  • zone_not_found - the specified zone is not found
PUT /api/v1/zone/{zone_id}

Update information on the zone.

Body

{
    "name": "zone 22"
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • zone_not_found - the specified zone is not found
DELETE /api/v1/zone/{zone_id}

Delete a zone if it doesn’t store any nodes.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • zone_not_found - the specified zone is not found
  • zone_in_use - the specified zone stores at least one node

Configuring the zone weights

POST /api/v1/zones/weights

Set the zone weights configuration.

Body

{
    "weights": {
        "1": {
            "2": 10,
            "3": 11
        },
        "2": {
            "1": 10,
            "3": 12
        },
        "3": {
            "1": 11,
            "2": 12
        }
    }
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • zones_weights_error - configuration error
GET /api/v1/zones/weights

Return the zone weights configuration.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {
        "1": {
            "2": 10,
            "3": 11
        },
        "2": {
            "1": 10,
            "3": 12
        },
        "3": {
            "1": 11,
            "2": 12
        }
    },
    "status": true
}

Potential errors

  • zone_not_found - the specified zone is not found

Configuring registry

GET /api/v1/registry/nodes/new

Return all the detected nodes.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": [
        {
            "uuid": "uuid-2",
            "hostname": "tnt2.public.i",
            "name": "tnt2"
        }
    ],
    "status": true
}
POST /api/v1/registry/node

Register the detected node.

Body

{
    "zone_id": 1,
    "uuid": "uuid-2",
    "uri": "tnt2.public.i:3301",
    "user": "user1:pass1",
    "repl_user": "repl_user1:repl_pass1",
    "cfg": {
        "listen": "0.0.0.0:3301"
    }
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • node_already_registered - the specified node is already registred
  • zone_not_found - the specified zone is not found
  • node_not_discovered - the specified node is not detected
PUT /api/v1/registry/node/{node_uuid}

Update the registered node parameters.

Body

Pass only those parameters that need to be updated.

{
    "zone_id": 1,
    "repl_user": "repl_user2:repl_pass2",
    "cfg": {
        "listen": "0.0.0.0:3301",
        "memtx_memory": 100000
    }
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • node_not_registered - the specified node is not registered
GET /api/v1/registry/node/{node_uuid: optional}

Return information on the nodes in a cluster. If node_uuid is passed, information on this node only is returned.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {
        "uuid-1": {
            "user": "user1:pass1",
            "hostname": "tnt1.public.i",
            "repl_user": "repl_user2:repl_pass2",
            "uri": "tnt1.public.i:3301",
            "zone_id": 1,
            "name": "tnt1",
            "cfg": {
                "listen": "0.0.0.0:3301",
                "memtx_memory": 100000
            },
            "zone": 1
        },
        "uuid-2": {
            "user": "user1:pass1",
            "hostname": "tnt2.public.i",
            "name": "tnt2",
            "uri": "tnt2.public.i:3301",
            "repl_user": "repl_user1:repl_pass1",
            "cfg": {
                "listen": "0.0.0.0:3301"
            },
            "zone": 1
        }
    },
    "status": true
}

Potential errors

  • node_not_registered - the specified node is not registered
DELETE /api/v1/registry/node/{node_uuid}

Delete the node if it doesn’t belong to any replica set.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • node_not_registered - the specified node is not registered
  • node_in_use - the specified node is in use by a replica set

Routers API

GET /api/v1/routers

Return the list of all nodes that constitute the router.

Response

{
    "data": [
        "uuid-1"
    ],
    "status": true,
    "error": {
        "code": 0,
        "message": "ok"
    }
}
POST /api/v1/routers

Assign the router role to the node.

Body

{
    "uuid": "uuid-1"
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • node_not_registered - the specified node is not registred
DELETE /api/v1/routers/{uuid}

Release the router role from the node.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Configuring replica sets

POST /api/v1/replicaset

Create a replica set containing all the registered nodes.

Body

{
    "uuid": "optional-uuid",
    "replicaset": [
        {
            "uuid": "uuid-1",
            "master": true
        }
    ]
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {
        "replicaset_uuid": "cc6568a2-63ca-413d-8e39-704b20adb7ae"
    },
    "status": true
}

Potential errors

  • replicaset_exists – the specified replica set already exists
  • replicaset_empty – the specified replica set doesn’t contain any nodes
  • node_not_registered – the specified node is not registered
  • node_in_use – the specified node is in use by another replica set
PUT /api/v1/replicaset/{replicaset_uuid}

Update the replica set parameters.

Body

{
    "replicaset": [
        {
            "uuid": "uuid-1",
            "master": true
        },
        {
            "uuid": "uuid-2",
            "master": false,
            "off": true
        }
    ]
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • replicaset_empty – the specified replica set doesn’t contain any nodes
  • replicaset_not_found – the specified replica set is not found
  • node_not_registered – the specified node is not registered
  • node_in_use – the specified node is in use by another replica set
GET /api/v1/replicaset/{replicaset_uuid: optional}

Return information on all the cluster components. If replicaset_uuid is passed, information on this replica set only is returned.

Body

{
    "name": "zone 22"
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {
        "cc6568a2-63ca-413d-8e39-704b20adb7ae": {
            "uuid-1": {
                "hostname": "tnt1.public.i",
                "off": false,
                "repl_user": "repl_user2:repl_pass2",
                "uri": "tnt1.public.i:3301",
                "master": true,
                "name": "tnt1",
                "user": "user1:pass1",
                "zone_id": 1,
                "zone": 1
            },
            "uuid-2": {
                "hostname": "tnt2.public.i",
                "off": true,
                "repl_user": "repl_user1:repl_pass1",
                "uri": "tnt2.public.i:3301",
                "master": false,
                "name": "tnt2",
                "user": "user1:pass1",
                "zone": 1
            }
        }
    },
    "status": true
}

Potential errors

  • replicaset_not_found – the specified replica set is not found
DELETE /api/v1/replicaset/{replicaset_uuid}

Delete a zone if it doesn’t store any nodes.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • replicaset_not_found - the specified replica set is not found
POST /api/v1/replicaset/{replicaset_uuid}/master

Switch the master in the replica set.

Body

{
    "instance_uuid": "uuid-1",
    "hostname_name": "hostname:instance_name"
}

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Potential errors

  • replicaset_not_found – the specified replica set is not found
  • node_not_registered – the specified node is not registered
  • node_not_in_replicaset – the specified node is not in the specified replica set
POST /api/v1/replicaset/{replicaset_uuid}/node

Add a node to the replica set.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {},
    "status": true
}

Body

{
    "instance_uuid": "uuid-1",
    "hostname_name": "hostname:instance_name",
    "master": false,
    "off": false
}

Potential errors

  • replicaset_not_found – the specified replica set is not found
  • node_not_registered – the specified node is not registered
  • node_in_use – the specified node is in use by another replica set
GET /api/v1/replicaset/status

Return statistics on the cluster.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "data": {
        "cluster": {
            "routers": [
                {
                    "zone": 1,
                    "name": "tnt1",
                    "repl_user": "repl_user1:repl_pass1",
                    "hostname": "tnt1.public.i",
                    "status": null,
                    "uri": "tnt1.public.i:3301",
                    "user": "user1:pass1",
                    "uuid": "uuid-1",
                    "total_rps": null
                }
            ],
            "storages": [
                {
                    "hostname": "tnt1.public.i",
                    "repl_user": "repl_user2:repl_pass2",
                    "uri": "tnt1.public.i:3301",
                    "name": "tnt1",
                    "total_rps": null,
                    "status": 'online',
                    "replicas": [
                        {
                            "user": "user1:pass1",
                            "hostname": "tnt2.public.i",
                            "replication_info": null,
                            "repl_user": "repl_user1:repl_pass1",
                            "uri": "tnt2.public.i:3301",
                            "uuid": "uuid-2",
                            "status": 'online',
                            "name": "tnt2",
                            "total_rps": null,
                            "zone": 1
                        }
                    ],
                    "user": "user1:pass1",
                    "zone_id": 1,
                    "uuid": "uuid-1",
                    "replicaset_uuid": "cc6568a2-63ca-413d-8e39-704b20adb7ae",
                    "zone": 1
                }
            ]
        }
    },
    "status": true
}

Potential errors

  • zone_not_found - the specified zone is not found
  • zone_in_use - the specified zone stores at least one node

Setting up configuration versions

POST /api/v1/version

Set the zone weights configuration.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "status": true,
    "data": {
        "version": 2
    }
}

Potential errors

  • cfg_error - configuration error
GET /api/v1/version

Return the zone weights configuration.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "status": true,
    "data": {
        "version": 2
    }
}

Configuring sharding

POST /api/v1/sharding/cfg

Add a new sharding configuration.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "status": true,
    "data": {}
}
GET /api/v1/sharding/cfg

Return the current sharding configuration.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "status": true,
    "data": {}
}

Resetting cluster configuration

POST /api/v1/clean/cfg

Reset the cluster configuration.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "status": true,
    "data": {}
}
POST /api/v1/clean/all

Reset the cluster configuration and delete information on the cluster nodes from the ZooKeeper catalogues.

Response

{
    "error": {
        "code": 0,
        "message": "ok"
    },
    "status": true,
    "data": {}
}