StateTip daemon


statetipd [options] start [--debug] [--config <path>] [--pidfile <path>]
statetipd [options] status [--wait [--timeout <seconds>]]
statetipd [options] stop [--timeout <seconds>] [--print-pid]
statetipd [options] reload
statetipd [options] compact
statetipd [options] reopen-logs
statetipd [options] dist-erl-start
statetipd [options] dist-erl-stop
statetipd [options] list [<name> [<origin> [<key>]]]
statetipd [options] delete <name> [<origin> [<key>]]
statetipd log-dump <logfile> [--read-block <bytes>] [--read-tries <count>]
statetipd log-replay <logfile> [--read-block <bytes>] [--read-tries <count>]
statetipd log-restore <logfile> <dump-file>
statetipd log-compact <logfile> [--read-block <bytes>] [--read-tries <count>]


statetipd is a service to help build monitoring systems, especially for dashboards. statetipd remembers the last values of events sent to it and can serve as an inventory of sorts. For example, a sysadmin may collect status of servers (e.g. “up” or “down”) in his network. statetipd allows to list all the servers that status was collected for, and then for each server display its status and/or some graphs.


To receive values and list them statetipd uses a protocol defined in statetip-protocol(7). Python module that already implements the protocol is provided, as well as a command line tool statetip(1). statetip(1) is intended mainly for manual data inspection and for writing small pipelines to feed statetipd with data, so it’s not as flexible as Python API, but should be enough for most use cases.

To run and control the statetipd daemon, there are several commands that are described below.


Commands that are issued to a daemon instance (all except start and log-*) use the path to control socket specified with --socket option as the target daemon’s address. Similarly, start uses --socket as the address that these commands can be sent to.

statetipd start [--debug] [--config <path>] [--pidfile <path>]

Start the statetipd daemon. It doesn’t detach from the terminal, so the caller is responsible for that, e.g. using start-stop-daemon(8).

statetipd status [--wait [--timeout <seconds>]]

Check if the daemon is running. Status is both printed to STDOUT and indicated with exit code (0 means the daemon is running, 1 means it’s stopped).

With --wait option the command will wait for daemon to start listening on the control socket (useful for initscripts), timing out after <seconds> (default is to wait indefinitely).

statetipd stop [--timeout <seconds>] [--print-pid]

Shutdown the daemon. With --print-pid option, PID of the daemon is printed to STDOUT, so the caller may wait until the process really terminates (it may happen that nothing is printed; in such case, the process already terminated).

Command waits at most <seconds> (default is infinity), and then reports an error.

statetipd reload

Reload the daemon’s configuration. See also Configuration.

statetipd compact

Start the state log file compaction outside its usual schedule.

This command is executed in the daemon instance, unlike similar command statetipd log-compact.

statetipd reopen-logs

Reopen log files, both state log and Erlang log.

statetipd dist-erl-start

Configure Erlang networking as a distributed node. This usually will be a debugging channel.

See [erlang] config file section for configuration details.

statetipd dist-erl-stop

Deconfigure Erlang networking.

statetipd list [<name> [<origin> [<key>]]]

List known value group names, origins, keys, or specific value.

null origin in arguments is encoded as an empty string, so the command is statetipd list <name> "" [<key>]. In statetipd list <name>, null origin is printed as "<null>".

The same information can be extracted using statetip(1) tool.

statetipd delete <name> [<origin> [<key>]]

Delete value group, origin in a value group, or specific value.

null origin is encoded as an empty string, so the command is statetipd delete <name> "" [<key>].

statetipd log-dump <logfile> [--read-block <bytes>] [--read-tries <count>]

Print the content of a state log file to STDOUT as a sequence of JSON objects, one per line. A log file can be restored from such a dump with statetipd log-restore command.

Any problems (e.g. damaged records) encountered during dumping a log file are printed to STDERR.

statetipd log-replay <logfile> [--read-block <bytes>] [--read-tries <count>]

Replay a state log file and print the end result to STDOUT as a sequence of JSON objects, one per line. This command is similar to statetipd log-dump, except it only prints the most recent values.

Problems (e.g. damaged records) encountered during replaying a log file that the procedure recovered from are suppressed. To get a detailed report, use statetipd log-dump command.

statetipd log-restore <logfile> <dump-file>

Create a state log file from a dump that was created with statetipd log-dump or statetipd log-replay.

statetipd log-compact <logfile> [--read-block <bytes>] [--read-tries <count>]

Compact the specified state log file. Similar in effect to statetipd log-replay followed by statetipd log-restore.

This command is executed in the calling process, not in the daemon instance, unlike similar command statetipd compact.


--socket <path>

Location of an administrative socket, where a command will be sent (or on which commands will be received, in case of statetipd start). Defaults to /var/run/statetip/control.

--config <path>

Path to a configuration file (see Configuration). Defaults to /etc/statetip/statetip.toml.

Used by statetipd start.


Verbose start of statetipd (starts sasl Erlang application before anything else).

Used by statetipd start.

--pidfile <path>

Path to a file where daemon’s PID will be written to. If not specified, no pidfile will be written.

Used by statetipd start.


Flag to make statetipd stop command print PID of the daemon, so the caller may wait until the process terminates.

NOTE: statetipd stop may still print nothing if the daemon terminates before the command returns.

--timeout <seconds>

Timeout for statetipd stop and statetipd status --wait commands. Defaults to infinity.


Flag to make statetipd status command to wait for control socket to appear instead of telling immediately that the daemon is stopped. Option intended for use in initscripts.

--read-block <bytes>

Size of a maximum block that is read from a log file. A single record needs to fit in this block. It will also be used to search for a valid record if a damaged entry is encountered.

The block size must be a multiple of 8.

Default is 4096 bytes. For comparison, records with a small info field take around 150-200 bytes.

--read-tries <count>

Number of consequent read blocks (--read-block) that will be tried if a damaged entry is encountered.

Default is 3 blocks.


Config file for statetipd is a TOML file. It specifies where statetipd listens for clients (e.g. statetip(1)), where state log is saved, and how to configure Erlang networking for debugging.

Configuration file could look like this:

listen = ["localhost:3012"]
default_expiry = 43200

listen = ["localhost:3082"]

directory = "/var/lib/statetip"
compaction_size = 10485760

handlers = ["statip_syslog_h"]

node_name = "statetip"
name_type = "longnames"
cookie_file = "/etc/statetip/cookie.txt"
distributed_immediate = false
log_file = "/var/log/statetip/erlang.log"


Section relevant to sender clients, which send values.

listen = ["<address>:<port>", ...]

List of addresses to listen for sender clients. If <address> is specified as *, statetipd accepts connections on any address.

Default value is ["localhost:3012"].

default_expiry = <seconds>

Expiry age that will be set for values that didn’t provide one.

Default value is 43200 (12 hours).


Section relevant to reader clients.

listen = ["<address>:<port>", ...]

List of addresses to listen for reader clients. If <address> is specified as *, statetipd accepts connections on any address.

Default value is ["localhost:3082"].


Section for state logging. State log is a file that records all the changes to the value groups.

If no state logging is configured, statetipd looses all the received values (until they are sent again). Typically this shouldn’t be a problem, as monitoring usually sends updates in intervals counted in minutes, but for the cases when a value is collected rarely, state log comes handy.

NOTE: It is always safe to delete contents of when statetipd is shut down.

directory = "<path>"

Directory to store state log. If set, then changes in all value groups will be recorded and restored on daemon start.

If the option is not set, no state log is written and all values are lost on restart.

compaction_size = <bytes>

A size limit for state log, after which the log is compacted (old entries are removed and a new log file that only contains fresh entries is written in its place).

Default value is 10485760 (10 MB).


handlers = ["<handler>", ...]

List of destinations for statetipd‘s internal logging. Currently supported values are "statip_syslog_h" and "statip_stdout_h".

Default is [] (no logging).


Section to configure Erlang VM running statetipd as distributed node. This exposes a channel for debugging StateTip.

node_name = "<node>"

Node name for Erlang VM running statetipd.

name_type = "shortnames" | "longnames"

Type of names for distributed Erlang. Either "shortnames" or "longnames".

cookie_file = "<path>"

Path to a file that contains cookie for distributed Erlang. If not specified, Erlang’s default procedure for setting cookie takes place.

distributed_immediate = true | false

Whether to start Erlang networking immediately or wait until an appropriate command (statetipd dist-erl-start) is issued.

Default is false.

log_file = "<path>"

File to write Erlang’s internal messages to (error_logger(3)). Default is not set.

See Also

Table Of Contents

Previous topic

StateTip client

Next topic

Python API

This Page