Configuration reference
This reference covers all options and parameters which can be set for Tarantool on the command line or in an initialization file.
Tarantool is started by entering either of the following command:
$ tarantool $ tarantool options $ tarantool lua-initialization-file [ arguments ]
-
-V
,
--version
Print product name and version, for example:
$ ./tarantool --version Tarantool 1.7.0-1216-g73f7154 Target: Linux-x86_64-Debug ...
In this example:
“Tarantool” is the name of the reusable asynchronous networking programming framework.
The 3-number version follows the standard
<major>-<minor>-<patch>
scheme, in which<major>
number is changed only rarely,<minor>
is incremented for each new milestone and indicates possible incompatible changes, and<patch>
stands for the number of bug fix releases made after the start of the milestone. For non-released versions only, there may be a commit number and commit SHA1 to indicate how much this particular build has diverged from the last release.“Target” is the platform tarantool was built on. Some platform-specific details may follow this line.
Note
Tarantool uses git describe to produce its version id, and this id can be used at any time to check out the corresponding source from our git repository.
Some configuration parameters and some functions depend on a URI, or
“Universal Resource Identifier”. The URI string format is similar to the
generic syntax for a URI schema.
So it may contain (in order) a user name
for login, a password, a host name or host IP address, and a port number. Only
the port number is always mandatory. The password is mandatory if the user
name is specified, unless the user name is ‘guest’. So, formally, the URI
syntax is [host:]port
or [username:password@]host:port
.
If host is omitted, then ‘0.0.0.0’ or ‘[::]’ is assumed,
meaning respectively any IPv4 address or any IPv6 address,
on the local machine.
If username:password is omitted, then ‘guest’ is assumed. Some examples:
URI fragment | Example |
---|---|
port | 3301 |
host:port | 127.0.0.1:3301 |
username:password@host:port | notguest:sesame@mail.ru:3301 |
In certain circumstances a Unix domain socket may be used where a URI is expected, for example “unix/:/tmp/unix_domain_socket.sock” or simply “/tmp/unix_domain_socket.sock”.
A method for parsing URIs is illustrated in Module uri.
If the command to start Tarantool includes lua-initialization-file, then
Tarantool begins by invoking the Lua program in the file, which by convention
may have the name “script.lua
”. The Lua program may get further arguments
from the command line or may use operating-system functions, such as getenv()
.
The Lua program almost always begins by invoking box.cfg()
, if the database
server will be used or if ports need to be opened. For example, suppose
script.lua
contains the lines
#!/usr/bin/env tarantool
box.cfg{
listen = os.getenv("LISTEN_URI"),
memtx_memory = 100000,
pid_file = "tarantool.pid",
rows_per_wal = 50
}
print('Starting ', arg[1])
and suppose the environment variable LISTEN_URI contains 3301,
and suppose the command line is ~/tarantool/src/tarantool script.lua ARG
.
Then the screen might look like this:
$ export LISTEN_URI=3301
$ ~/tarantool/src/tarantool script.lua ARG
... main/101/script.lua C> version 1.7.0-1216-g73f7154
... main/101/script.lua C> log level 5
... main/101/script.lua I> mapping 107374184 bytes for a shared arena...
... main/101/script.lua I> recovery start
... main/101/script.lua I> recovering from './00000000000000000000.snap'
... main/101/script.lua I> primary: bound to 0.0.0.0:3301
... main/102/leave_local_hot_standby I> ready to accept requests
Starting ARG
... main C> entering the event loop
If you wish to start an interactive session on the same terminal after initialization is complete, you can use console.start().
Configuration parameters have the form:
box.cfg{[key = value [, key = value …]]}
Since box.cfg
may contain many configuration parameters and since some of the
parameters (such as directory addresses) are semi-permanent, it’s best to keep
box.cfg
in a Lua file. Typically this Lua file is the initialization file
which is specified on the tarantool command line.
Most configuration parameters are for allocating resources, opening ports, and
specifying database behavior. All parameters are optional. A few parameters are
dynamic, that is, they can be changed at runtime by calling box.cfg{}
a second time.
To see all the non-null parameters, say box.cfg
(no parentheses). To see a
particular parameter, for example the listen address, say box.cfg.listen
.
The following sections describe all parameters for basic operation, for storage, for binary logging and snapshots, for replication, for networking, for logging, and for feedback.
- background
- custom_proc_title
- listen
- memtx_dir
- pid_file
- read_only
- vinyl_dir
- vinyl_timeout
- username
- wal_dir
- work_dir
- worker_pool_threads
-
background
Since version 1.6.2. Run the server as a background task. The log and pid_file parameters must be non-null for this to work.
Type: booleanDefault: falseDynamic: no
-
custom_proc_title
Since version 1.6.7. Add the given string to the server’s process title (what’s shown in the COMMAND column for
ps -ef
andtop -c
commands).For example, ordinarily
ps -ef
shows the Tarantool server process thus:$ ps -ef | grep tarantool 1000 14939 14188 1 10:53 pts/2 00:00:13 tarantool <running>
But if the configuration parameters include
custom_proc_title='sessions'
then the output looks like:$ ps -ef | grep tarantool 1000 14939 14188 1 10:53 pts/2 00:00:16 tarantool <running>: sessions
Type: stringDefault: nullDynamic: yes
-
listen
Since version 1.6.4. The read/write data port number or URI (Universal Resource Identifier) string. Has no default value, so must be specified if connections will occur from remote clients that do not use the “admin port”. Connections made with
listen = URI
are called “binary port” or “binary protocol” connections.A typical value is 3301.
Note
A replica also binds to this port, and accepts connections, but these connections can only serve reads until the replica becomes a master.
Type: integer or stringDefault: nullDynamic: yes
-
memtx_dir
Since version 1.7.4. A directory where memtx stores snapshot (.snap) files. Can be relative to work_dir. If not specified, defaults to
work_dir
. See also wal_dir.Type: stringDefault: “.”Dynamic: no
-
pid_file
Since version 1.4.9. Store the process id in this file. Can be relative to work_dir. A typical value is “
tarantool.pid
”.Type: stringDefault: nullDynamic: no
-
read_only
Since version 1.7.1. Say
box.cfg{read_only=true...}
to put the server instance in read-only mode. After this, any requests that try to change persistent data will fail with errorER_READONLY
. Read-only mode should be used for master-replica replication. Read-only mode does not affect data-change requests for spaces defined as temporary. Although read-only mode prevents the server from writing to the WAL, it does not prevent writing diagnostics with the log module.Type: booleanDefault: falseDynamic: yesSetting
read_only == true
affects spaces differently depending on the options that were used during box.schema.space.create.
-
vinyl_dir
Since version 1.7.1. A directory where vinyl files or subdirectories will be stored. Can be relative to work_dir. If not specified, defaults to
work_dir
.Type: stringDefault: “.”Dynamic: no
-
vinyl_timeout
Since version 1.7.5. The vinyl storage engine has a scheduler which does compaction. When vinyl is low on available memory, the compaction scheduler may be unable to keep up with incoming update requests. In that situation, queries may time out after
vinyl_timeout
seconds. This should rarely occur, since normally vinyl would throttle inserts when it is running low on compaction bandwidth. Compaction can also be ordered manually with index_object:compact().Type: floatDefault: 60Dynamic: yes
-
username
Since version 1.4.9. UNIX user name to switch to after start.
Type: stringDefault: nullDynamic: no
-
wal_dir
Since version 1.6.2. A directory where write-ahead log (.xlog) files are stored. Can be relative to work_dir. Sometimes
wal_dir
and memtx_dir are specified with different values, so that write-ahead log files and snapshot files can be stored on different disks. If not specified, defaults towork_dir
.Type: stringDefault: “.”Dynamic: no
-
work_dir
Since version 1.4.9. A directory where database working files will be stored. The server instance switches to
work_dir
with chdir(2) after start. Can be relative to the current directory. If not specified, defaults to the current directory. Other directory parameters may be relative towork_dir
, for example:box.cfg{ work_dir = '/home/user/A', wal_dir = 'B', memtx_dir = 'C' }
will put xlog files in
/home/user/A/B
, snapshot files in/home/user/A/C
, and all other files or subdirectories in/home/user/A
.Type: stringDefault: nullDynamic: no
-
worker_pool_threads
Since version 1.7.5. The maximum number of threads to use during execution of certain internal processes (currently socket.getaddrinfo() and coio_call()).
Type: integerDefault: 4Dynamic: yes
- memtx_memory
- memtx_max_tuple_size
- memtx_min_tuple_size
- vinyl_bloom_fpr
- vinyl_cache
- vinyl_max_tuple_size
- vinyl_memory
- vinyl_page_size
- vinyl_range_size
- vinyl_run_count_per_level
- vinyl_run_size_ratio
- vinyl_read_threads
- vinyl_write_threads
-
memtx_memory
Since version 1.7.4. How much memory Tarantool allocates to actually store tuples. When the limit is reached, INSERT or UPDATE requests begin failing with error
ER_MEMORY_ISSUE
. The server does not go beyond thememtx_memory
limit to allocate tuples, but there is additional memory used to store indexes and connection information. Depending on actual configuration and workload, Tarantool can consume up to 20% more than thememtx_memory
limit.Type: floatDefault: 256 * 1024 * 1024 = 268435456 bytesDynamic: yes but it cannot be decreased
-
memtx_max_tuple_size
Since version 1.7.4. Size of the largest allocation unit, for the memtx storage engine. It can be increased if it is necessary to store large tuples. See also: vinyl_max_tuple_size.
Type: integerDefault: 1024 * 1024 = 1048576 bytesDynamic: no
-
memtx_min_tuple_size
Since version 1.7.4. Size of the smallest allocation unit. It can be decreased if most of the tuples are very small. The value must be between 8 and 1048280 inclusive.
Type: integerDefault: 16 bytesDynamic: no
-
vinyl_bloom_fpr
Since version 1.7.4. Bloom filter false positive rate – the suitable probability of the bloom filter to give a wrong result. The
vinyl_bloom_fpr
setting is a default value for one of the options in the Options for space_object:create_index() chart.Type: floatDefault = 0.05Dynamic: no
-
vinyl_cache
Since version 1.7.4. The cache size for the vinyl storage engine. The cache can be resized dynamically.
Type: integerDefault = 128 * 1024 * 1024 = 134217728 bytesDynamic: yes
-
vinyl_max_tuple_size
Since version 1.7.5. Size of the largest allocation unit, for the vinyl storage engine. It can be increased if it is necessary to store large tuples. See also: memtx_max_tuple_size.
Type: integerDefault: 1024 * 1024 = 1048576 bytesDynamic: no
-
vinyl_memory
Since version 1.7.4. The maximum number of in-memory bytes that vinyl uses.
Type: integerDefault = 128 * 1024 * 1024 = 134217728 bytesDynamic: yes but it cannot be decreased
-
vinyl_page_size
Since version 1.7.4. Page size. Page is a read/write unit for vinyl disk operations. The
vinyl_page_size
setting is a default value for one of the options in the Options for space_object:create_index() chart.Type: integerDefault = 8 * 1024 = 8192 bytesDynamic: no
-
vinyl_range_size
Since version 1.7.4. The default maximum range size for a vinyl index. The maximum range size affects the decision whether to split a range.
If
vinyl_range_size
is not nil and not 0, then it is used as the default value for therange_size
option in the Options for space_object:create_index() chart.If
vinyl_range_size
is nil or 0, andrange_size
is not specified when the index is created, then Tarantool sets a value later depending on performance considerations. To see the actual value, use index_object:stat().range_size.In Tarantool versions prior to 1.10.2,
vinyl_range_size
default value was 1073741824.Type: integerDefault = nil bytesDynamic: no
-
vinyl_run_count_per_level
Since version 1.7.4. The maximal number of runs per level in vinyl LSM tree. If this number is exceeded, a new level is created. The
vinyl_run_count_per_level
setting is a default value for one of the options in the Options for space_object:create_index() chart.Type: integerDefault = 2Dynamic: no
-
vinyl_run_size_ratio
Since version 1.7.4. Ratio between the sizes of different levels in the LSM tree. The
vinyl_run_size_ratio
setting is a default value for one of the options in the Options for space_object:create_index() chart.Type: floatDefault = 3.5Dynamic: no
The checkpoint daemon is a fiber which is constantly running. At intervals, it may make new snapshot (.snap) files and then may delete old snapshot files.
The checkpoint_interval and checkpoint_count configuration settings determine how long the intervals are, and how many snapshots should exist before deletions occur.
Tarantool garbage collector
The checkpoint daemon may activate the Tarantool garbage collector which deletes old files. This garbage collector is distinct from the Lua garbage collector which is for Lua objects, and distinct from a Tarantool garbage collector which specializes in handling shard buckets.
If the checkpoint daemon deletes an old snapshot file, then the
Tarantool garbage collector will also delete
any write-ahead log (.xlog) files which are older than
the snapshot file and which contain information that is present in the snapshot
file. It will also delete obsolete vinyl .run
files.
The checkpoint daemon and the Tarantool garbage collector will not delete a file if:
- a backup is ongoing and the file has not been backed up (see “Hot backup”), or
- replication is ongoing and the file has not been relayed to a replica (see “Replication architecture”),
- a replica is connecting, or
- a replica has fallen behind. The progress of each replica is tracked; if a replica’s position is far from being up to date, then the server stops to give it a chance to catch up. If an administrator concludes that a replica is permanently down, then the correct procedure is to restart the server, or (preferably) remove the replica from the cluster.
-
checkpoint_interval
Since version 1.7.4. The interval between actions by the checkpoint daemon, in seconds. If
checkpoint_interval
is set to a value greater than zero, and there is activity which causes change to a database, then the checkpoint daemon will call box.snapshot() everycheckpoint_interval
seconds, creating a new snapshot file each time. Ifcheckpoint_interval
is set to zero, then the checkpoint daemon is disabled.For example:
box.cfg{checkpoint_interval=60}
will cause the checkpoint daemon to create a new database snapshot once per minute, if there is activity.
Type: integerDefault: 3600 (one hour)Dynamic: yes
-
checkpoint_count
Since version 1.7.4. The maximum number of snapshots that may exist on the memtx_dir directory before the checkpoint daemon will delete old snapshots. If
checkpoint_count
equals zero, then the checkpoint daemon does not delete old snapshots. For example:box.cfg{ checkpoint_interval = 3600, checkpoint_count = 10 }
will cause the checkpoint daemon to create a new snapshot each hour until it has created ten snapshots. After that, it will delete the oldest snapshot (and any associated write-ahead-log files) after creating a new one.
Remember that, as noted earlier, snapshots will not be deleted if replication is ongoing and the file has not been relayed to a replica. Therefore
checkpoint_count
has no effect unless all replicas are alive.Type: integerDefault: 2Dynamic: yes
-
force_recovery
Since version 1.7.4. If
force_recovery
equals true, Tarantool tries to continue if there is an error while reading a snapshot file (at server instance start) or a write-ahead log file (at server instance start or when applying an update at a replica): skips invalid records, reads as much data as possible and lets the process finish with a warning. Users can prevent the error from recurring by writing to the database and executing box.snapshot().Otherwise, Tarantool aborts recovery if there is an error while reading.
Type: booleanDefault: falseDynamic: no
-
rows_per_wal
Since version 1.6.2. How many log records to store in a single write-ahead log file. When this limit is reached, Tarantool creates another WAL file named
<first-lsn-in-wal>.xlog
. This can be useful for simple rsync-based backups.Type: integerDefault: 500000Dynamic: no
-
wal_max_size
Since version 1.7.4. The maximum number of bytes in a single write-ahead log file. When a request would cause an .xlog file to become larger than
wal_max_size
, Tarantool creates another WAL file – the same effect that happens when the rows_per_wal limit is reached.Type: integerDefault: 268435456 (256 * 1024 * 1024) bytesDynamic: no
-
snap_io_rate_limit
Since version 1.4.9. Reduce the throttling effect of box.snapshot() on INSERT/UPDATE/DELETE performance by setting a limit on how many megabytes per second it can write to disk. The same can be achieved by splitting wal_dir and memtx_dir locations and moving snapshots to a separate disk. The limit also affects what box.stat.vinyl().regulator may show for the write rate of dumps to .run and .index files.
Type: floatDefault: nullDynamic: yes
-
wal_mode
Since version 1.6.2. Specify fiber-WAL-disk synchronization mode as:
none
: write-ahead log is not maintained;write
: fibers wait for their data to be written to the write-ahead log (no fsync(2));fsync
: fibers wait for their data, fsync(2) follows each write(2);
Type: stringDefault: “write”Dynamic: no
-
wal_dir_rescan_delay
Since version 1.6.2. Number of seconds between periodic scans of the write-ahead-log file directory, when checking for changes to write-ahead-log files for the sake of replication or hot standby.
Type: floatDefault: 2Dynamic: no
-
hot_standby
Since version 1.7.4. Whether to start the server in hot standby mode.
Hot standby is a feature which provides a simple form of failover without replication.
The expectation is that there will be two instances of the server using the same configuration. The first one to start will be the “primary” instance. The second one to start will be the “standby” instance.
To initiate the standby instance, start a second instance of the Tarantool server on the same computer with the same box.cfg configuration settings – including the same directories and same non-null URIs – and with the additional configuration setting
hot_standby = true
. Expect to see a notification ending with the wordsI> Entering hot standby mode
. This is fine. It means that the standby instance is ready to take over if the primary instance goes down.The standby instance will initialize and will try to take a lock on wal_dir, but will fail because the primary instance has made a lock on
wal_dir
. So the standby instance goes into a loop, reading the write ahead log which the primary instance is writing (so the two instances are always in sync), and trying to take the lock. If the primary instance goes down for any reason, the lock will be released. In this case, the standby instance will succeed in taking the lock, will connect on the listen address and will become the primary instance. Expect to see a notification ending with the wordsI> ready to accept requests
.Thus there is no noticeable downtime if the primary instance goes down.
Hot standby feature has no effect:
- if wal_dir_rescan_delay = a large number
(on Mac OS and FreeBSD);
on these platforms, it is designed so that the loop repeats every
wal_dir_rescan_delay
seconds. - if wal_mode = ‘none’;
it is designed to work with
wal_mode = 'write'
orwal_mode = 'fsync'
. - for spaces created with engine = ‘vinyl’;
it is designed to work for spaces created with
engine = 'memtx'
.
Type: booleanDefault: falseDynamic: no- if wal_dir_rescan_delay = a large number
(on Mac OS and FreeBSD);
on these platforms, it is designed so that the loop repeats every
- replication
- replication_connect_timeout
- replication_connect_quorum
- replication_skip_conflict
- replication_sync_lag
- replication_sync_timeout
- replication_timeout
- replicaset_uuid
- instance_uuid
-
replication
Since version 1.7.4. If
replication
is not an empty string, the instance is considered to be a Tarantool replica. The replica will try to connect to the master specified inreplication
with a URI (Universal Resource Identifier), for example:konstantin:secret_password@tarantool.org:3301
If there is more than one replication source in a replica set, specify an array of URIs, for example (replace ‘uri’ and ‘uri2’ in this example with valid URIs):
box.cfg{ replication = { ‘uri1’, ‘uri2’ } }
If one of the URIs is “self” – that is, if one of the URIs is for the instance where
box.cfg{}
is being executed on – then it is ignored. Thus it is possible to use the samereplication
specification on multiple server instances, as shown in these examples.The default user name is ‘guest’.
A read-only replica does not accept data-change requests on the listen port.
The
replication
parameter is dynamic, that is, to enter master mode, simply setreplication
to an empty string and issue:box.cfg{ replication = new-value }
Type: stringDefault: nullDynamic: yes
-
replication_connect_timeout
Since version 1.9.0. The number of seconds that a replica will wait when trying to connect to a master in a cluster. See orphan status for details.
This parameter is different from replication_timeout, which a master uses to disconnect a replica when the master receives no acknowledgments of heartbeat messages.
Type: floatDefault: 30Dynamic: yes
-
replication_connect_quorum
Since version 1.9.0. By default a replica will try to connect to all the masters, or it will not start. (The default is recommended so that all replicas will receive the same replica set UUID.)
However, by specifying
replication_connect_quorum = N
, where N is a number greater than or equal to zero, users can state that the replica only needs to connect to N masters.This parameter has effect during bootstrap and during configuration update. Setting
replication_connect_quorum = 0
makes Tarantool require no immediate reconnect only in case of recovery. See orphan status for details.Example:
box.cfg{replication_connect_quorum=2}
Type: integerDefault: nullDynamic: yes
-
replication_skip_conflict
Since version 1.10.1. By default, if a replica adds a unique key that another replica has added, replication stops with error = ER_TUPLE_FOUND.
However, by specifying
replication_skip_conflict = true
, users can state that such errors may be ignored.Example:
box.cfg{replication_skip_conflict=true}
Type: booleanDefault: falseDynamic: yes
-
replication_sync_lag
Since version 1.9.0. The maximum lag allowed for a replica. When a replica syncs (gets updates from a master), it may not catch up completely. The number of seconds that the replica is behind the master is called the “lag”. Syncing is considered to be complete when the replica’s lag is less than or equal to
replication_sync_lag
.If a user sets
replication_sync_lag
to nil or to 365 * 100 * 86400 (TIMEOUT_INFINITY), then lag does not matter – the replica is always considered to be “synced”. Also, the lag is ignored (assumed to be infinite) in case the master is running Tarantool older than 1.7.7, which does not send heartbeat messages.This parameter is ignored during bootstrap. See orphan status for details.
Type: floatDefault: 10Dynamic: yes
-
replication_sync_timeout
Since version 1.10.2. The number of seconds that a replica will wait when trying to sync with a master in a cluster, or a quorum of masters, after connecting or during configuration update. This could fail indefinitely if
replication_sync_lag
is smaller than network latency, or if the replica cannot keep pace with master updates. Ifreplication_sync_timeout
expires, the replica enters orphan status.Type: floatDefault: 300Dynamic: yes
-
replication_timeout
Since version 1.7.5. If the master has no updates to send to the replicas, it sends heartbeat messages every
replication_timeout
seconds, and each replica sends an ACK packet back.Both master and replicas are programmed to drop the connection if they get no response in four
replication_timeout
periods. If the connection is dropped, a replica tries to reconnect to the master.See more in Monitoring a replica set.
Type: integerDefault: 1Dynamic: yes
-
replicaset_uuid
Since version 1.9.0. As described in section “Replication architecture”, each replica set is identified by a universally unique identifier called replica set UUID, and each instance is identified by an instance UUID.
Ordinarily it is sufficient to let the system generate and format the UUID strings which will be permanently stored.
However, some administrators may prefer to store Tarantool configuration information in a central repository, for example Apache ZooKeeper. Such administrators can assign their own UUID values for either – or both – instances (instance_uuid) and replica set (
replicaset_uuid
), when starting up for the first time.General rules:
- The values must be true unique identifiers, not shared by other instances or replica sets within the common infrastructure.
- The values must be used consistently, not changed after initial setup (the initial values are stored in snapshot files and are checked whenever the system is restarted).
- The values must comply with RFC 4122. The nil UUID is not allowed.
The UUID format includes sixteen octets represented as 32 hexadecimal (base 16) digits, displayed in five groups separated by hyphens, in the form
8-4-4-4-12
for a total of 36 characters (32 alphanumeric characters and four hyphens).Example:
box.cfg{replicaset_uuid='7b853d13-508b-4b8e-82e6-806f088ea6e9'}
Type: stringDefault: nullDynamic: no
-
instance_uuid
Since version 1.9.0. For replication administration purposes, it is possible to set the universally unique identifiers of the instance (
instance_uuid
) and the replica set (replicaset_uuid
), instead of having the system generate the values.See the description of replicaset_uuid parameter for details.
Example:
box.cfg{instance_uuid='037fec43-18a9-4e12-a684-a42b716fcd02'}
Type: stringDefault: nullDynamic: no
-
io_collect_interval
Since version 1.4.9. The instance will sleep for io_collect_interval seconds between iterations of the event loop. Can be used to reduce CPU load in deployments in which the number of client connections is large, but requests are not so frequent (for example, each connection issues just a handful of requests per second).
Type: floatDefault: nullDynamic: yes
-
net_msg_max
Since version 1.10.1. To handle messages, Tarantool allocates fibers. To prevent fiber overhead from affecting the whole system, Tarantool restricts how many messages the fibers handle, so that some pending requests are blocked.
On powerful systems, increase
net_msg_max
and the scheduler will immediately start processing pending requests.On weaker systems, decrease
net_msg_max
and the overhead may decrease although this may take some time because the scheduler must wait until already-running requests finish.When
net_msg_max
is reached, Tarantool suspends processing of incoming packages until it has processed earlier messages. This is not a direct restriction of the number of fibers that handle network messages, rather it is a system-wide restriction of channel bandwidth. This in turn causes restriction of the number of incoming network messages that the transaction processor thread handles, and therefore indirectly affects the fibers that handle network messages. (The number of fibers is smaller than the number of messages because messages can be released as soon as they are delivered, while incoming requests might not be processed until some time after delivery.)On typical systems, the default value (768) is correct.
Type: integerDefault: 768Dynamic: yes
-
readahead
Since version 1.6.2. The size of the read-ahead buffer associated with a client connection. The larger the buffer, the more memory an active connection consumes and the more requests can be read from the operating system buffer in a single system call. The rule of thumb is to make sure the buffer can contain at least a few dozen requests. Therefore, if a typical tuple in a request is large, e.g. a few kilobytes or even megabytes, the read-ahead buffer size should be increased. If batched request processing is not used, it’s prudent to leave this setting at its default.
Type: integerDefault: 16320Dynamic: yes
-
log_level
Since version 1.6.2. What level of detail the log will have. There are seven levels:
- 1 –
SYSERROR
- 2 –
ERROR
- 3 –
CRITICAL
- 4 –
WARNING
- 5 –
INFO
- 6 –
VERBOSE
- 7 –
DEBUG
By setting log_level, one can enable logging of all classes below or equal to the given level. Tarantool prints its logs to the standard error stream by default, but this can be changed with the log configuration parameter.
Type: integerDefault: 5Dynamic: yesWarning: prior to Tarantool 1.7.5 there were only six levels and
DEBUG
was level 6. Starting with Tarantool 1.7.5VERBOSE
is level 6 andDEBUG
is level 7.VERBOSE
is a new level for monitoring repetitive events which would cause too much log writing ifINFO
were used instead.- 1 –
-
log
Since version 1.7.4. By default, Tarantool sends the log to the standard error stream (
stderr
). Iflog
is specified, Tarantool sends the log to a file, or to a pipe, or to the system logger.Example setting for sending the log to a file:
box.cfg{log = 'tarantool.log'} -- or box.cfg{log = 'file:tarantool.log'}
This will open the file
tarantool.log
for output on the server’s default directory. If thelog
string has no prefix or has the prefix “file:”, then the string is interpreted as a file path.Example setting for sending the log to a pipe:
box.cfg{log = '| cronolog tarantool.log'} -- or box.cfg{log = 'pipe: cronolog tarantool.log'}'
This will start the program cronolog when the server starts, and will send all log messages to the standard input (
stdin
) of cronolog. If thelog
string begins with ‘|’ or has the prefix “pipe:”, then the string is interpreted as a Unix pipeline.Example setting for sending the log to syslog:
box.cfg{log = 'syslog:identity=tarantool'} -- or box.cfg{log = 'syslog:facility=user'} -- or box.cfg{log = 'syslog:identity=tarantool,facility=user'} -- or box.cfg{log = 'syslog:server=unix:/dev/log'}
If the
log
string begins with “syslog:”, then it is interpreted as a message for the syslogd program which normally is running in the background of any Unix-like platform. The setting can be ‘syslog:’, ‘syslog:facility=…’, ‘syslog:identity=…’, ‘syslog:server=…’, or a combination.The
syslog:identity
setting is an arbitrary string which will be placed at the beginning of all messages. The default value is: tarantool.The
syslog:facility
setting is currently ignored but will be used in the future. The value must be one of the syslog keywords, which tell syslogd where the message should go. The possible values are: auth, authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0, local1, local2, local3, local4, local5, local6, local7. The default value is: user.The
syslog:server
setting is the locator for the syslog server. It can be a Unix socket path beginning with “unix:”, or an ipv4 port number. The default socket value is: dev/log (on Linux) or /var/run/syslog (on Mac OS). The default port value is: 514, the UDP port.When logging to a file, Tarantool reopens the log on SIGHUP. When log is a program, its pid is saved in the log.logger_pid variable. You need to send it a signal to rotate logs.
Type: stringDefault: nullDynamic: no
-
log_nonblock
Since version 1.7.4. If
log_nonblock
equals true, Tarantool does not block on the log file descriptor when it’s not ready for write, and drops the message instead. If log_level is high, and many messages go to the log file, settinglog_nonblock
to true may improve logging performance at the cost of some log messages getting lost.This parameter has effect only if the output is going to
syslog
or to a pipe.Type: booleanDefault: trueDynamic: no
-
too_long_threshold
Since version 1.6.2. If processing a request takes longer than the given value (in seconds), warn about it in the log. Has effect only if log_level is more than or equal to 4 (WARNING).
Type: floatDefault: 0.5Dynamic: yes
-
log_format
Since version 1.7.6. Log entries have two possible formats:
- ‘plain’ (the default), or
- ‘json’ (with more detail and with JSON labels).
Here is what a log entry looks like after
box.cfg{log_format='plain'}
:2017-10-16 11:36:01.508 [18081] main/101/interactive I> set 'log_format' configuration option to "plain"
Here is what a log entry looks like after
box.cfg{log_format='json'}
:{"time": "2017-10-16T11:36:17.996-0600", "level": "INFO", "message": "set 'log_format' configuration option to \"json\"", "pid": 18081,| "cord_name": "main", "fiber_id": 101, "fiber_name": "interactive", "file": "builtin\/box\/load_cfg.lua", "line": 317}
The
log_format='plain'
entry has time, process id, cord name, fiber_id, fiber_name, log level, and message.The
log_format='json'
entry has the same things along with their labels, and in addition has the file name and line number of the Tarantool source.Type: stringDefault: ‘plain’Dynamic: yes
This will illustrate how “rotation” works, that is, what happens when the server instance is writing to a log and signals are used when archiving it.
Start with two terminal shells, Terminal #1 and Terminal #2.
On Terminal #1: start an interactive Tarantool session, then say the logging
will go to Log_file
, then put a message “Log Line #1” in the log file:
box.cfg{log='Log_file'}
log = require('log')
log.info('Log Line #1')
On Terminal #2: use mv
so the log file is now named Log_file.bak
.
The result of this is: the next log message will go to Log_file.bak
.
mv Log_file Log_file.bak
On Terminal #1: put a message “Log Line #2” in the log file.
log.info('Log Line #2')
On Terminal #2: use ps
to find the process ID of the Tarantool instance.
ps -A | grep tarantool
On Terminal #2: use kill -HUP
to send a SIGHUP signal to the Tarantool instance.
The result of this is: Tarantool will open Log_file
again, and
the next log message will go to Log_file
.
(The same effect could be accomplished by executing log.rotate() on the instance.)
kill -HUP process_id
On Terminal #1: put a message “Log Line #3” in the log file.
log.info('Log Line #3')
On Terminal #2: use less
to examine files. Log_file.bak
will have these lines,
except that the date and time will depend on when the example is done:
2015-11-30 15:13:06.373 [27469] main/101/interactive I> Log Line #1`
2015-11-30 15:14:25.973 [27469] main/101/interactive I> Log Line #2`
and Log_file
will have
log file has been reopened
2015-11-30 15:15:32.629 [27469] main/101/interactive I> Log Line #3
By default a Tarantool daemon sends a small packet
once per hour, to https://feedback.tarantool.io.
The packet contains three values from box.info:
box.info.version
, box.info.uuid
, and box.info.cluster_uuid
.
By changing the feedback configuration parameters, users can
adjust or turn off this feature.
-
feedback_enabled
Since version 1.10.1. Whether to send feedback.
If this is set to
true
, feedback will be sent as described above. If this is set tofalse
, no feedback will be sent.Type: booleanDefault: trueDynamic: yes
These parameters are deprecated since Tarantool version 1.7.4:
- coredump
- logger
- logger_nonblock
- panic_on_snap_error,
- panic_on_wal_error
- replication_source
- slab_alloc_arena
- slab_alloc_factor
- slab_alloc_maximal
- slab_alloc_minimal
- snap_dir
- snapshot_count
- snapshot_period
-
logger
Deprecated in favor of log. The parameter was only renamed, while the type, values and semantics remained intact.
-
logger_nonblock
Deprecated in favor of log_nonblock. The parameter was only renamed, while the type, values and semantics remained intact.
-
panic_on_snap_error
Deprecated in favor of force_recovery.
If there is an error while reading a snapshot file (at server instance start), abort.
Type: booleanDefault: trueDynamic: no
-
panic_on_wal_error
Deprecated in favor of force_recovery.
Type: booleanDefault: trueDynamic: yes
-
replication_source
Deprecated in favor of replication. The parameter was only renamed, while the type, values and semantics remained intact.
-
slab_alloc_arena
Deprecated in favor of memtx_memory.
How much memory Tarantool allocates to actually store tuples, in gigabytes. When the limit is reached, INSERT or UPDATE requests begin failing with error
ER_MEMORY_ISSUE
. While the server does not go beyond the defined limit to allocate tuples, there is additional memory used to store indexes and connection information. Depending on actual configuration and workload, Tarantool can consume up to 20% more than the limit set here.Type: floatDefault: 1.0Dynamic: no
-
slab_alloc_factor
Deprecated, do not use.
The multiplier for computing the sizes of memory chunks that tuples are stored in. A lower value may result in less wasted memory depending on the total amount of memory available and the distribution of item sizes.
Type: floatDefault: 1.1Dynamic: no
-
slab_alloc_maximal
Deprecated in favor of memtx_max_tuple_size. The parameter was only renamed, while the type, values and semantics remained intact.
-
slab_alloc_minimal
Deprecated in favor of memtx_min_tuple_size. The parameter was only renamed, while the type, values and semantics remained intact.
-
snap_dir
Deprecated in favor of memtx_dir. The parameter was only renamed, while the type, values and semantics remained intact.
-
snapshot_period
Deprecated in favor of checkpoint_interval. The parameter was only renamed, while the type, values and semantics remained intact.
-
snapshot_count
Deprecated in favor of checkpoint_count. The parameter was only renamed, while the type, values and semantics remained intact.