StateTip client


statetip [--reader] [options] [<name> [<origin> [<key>]]]
events-stream ... | statetip --sender --name=<name> [options]


statetip is a command line client for StateTip. It can be used to inspect and read data collected by statetipd(8) (this mode is called reader mode), or to send new data from STDIN to statetipd(8) (sender mode).

statetip aims at simplifying some common use cases, like manual data inspection or writing a small monitoring data pipeline with just shell tools. If you need more advanced features (e.g. sorting value group’s keys in order different than lexicographical or recording additional data), use Python API or directly statetip-protocol(7).


There are several “top-level” options, which work regardless of the selected mode (or that select the client mode):


Select reader mode. This is the default.


Select sender mode. This mode requires --name to be specified as well.


Select the address that statetipd(8) listens on. Default is localhost.


Select the port that statetipd(8) listens on. Default is 3082 for reader mode and 3012 for sender mode.

Reader mode

Reader mode is used to list data already recorded by statetipd(8). Sub-commands typically print a list of elements, each element in its own line. This can be changed with --json option, which causes statetip to print a single line with JSON list.

statetip --reader

List names of all value groups.

statetip --reader <name>

List origins of a specific value group.

Null origin is printed as <null> (in JSON mode it’s null, as one would expect).

statetip --reader <name> <origin>

List keys in a specific origin of a value group.

Null origin is specified as "" (empty string), for example:

$ statetip --reader servers ""

Option --all changes the mode from listing just keys to listing all values. This is similar to listing them one by one with consequent calls to statetip, except this is a single operation.

--all with --json results in printing the values as a single JSON list instead of printing them as JSON objects one per line.

statetip --reader <name> <origin> <key>

List fields (one or several or all) of a specific value.

By default, only state is printed. This can be changed by specifying a combination of --state, --severity, and --info options.

When --all is specifed, whole value is printed to STDOUT as a JSON object.

Following options work in reader mode:


Instead of printing list of elements line by line, print them as a single JSON list.


Print whole value (or values) when listing keys of specific origin or when reading a specific value.


Print state field of a value.


Print severity field of a value.


Print info field of a value (always a valid JSON).

Sender mode

Sender mode simplifies writing monitoring data to StateTip. Sender mode reads a sequence of space-separated records from its STDIN and sends them to statetipd(8), which is a shell-friendly behaviour, but the protocol is simpler than statetip-protocol(7), so it doesn’t support all the cases. If you need full control over sent data, see Python API documentation or statetip-protocol(7).

To make statetipd(8) remember a set of values, you can use a following command:

printf 'key1 value1\nkey2 value2\nkey3 value3\n' | \
  statetip --sender --name=myname --origin=myorigin
statetip --reader myname myorigin --all
> {"key":"key1","state":"value1", ...}
> {"key":"key2","state":"value2", ...}
> {"key":"key3","state":"value3", ...}

Sender mode only allows sending one value group, which name must be specified with --name option. Origin may either be pre-defined with --origin or --null-origin option or be provided along with value’s key.


Value group is a group of unrelated values (i.e. collected independently and ageing each on its own). This is the default.

Value group is a group of related values (i.e. collected in a single operation, and the new collection replaces the old one immediately).


Value group name.


Origin of the value group. If not specified in advance, each entry has to specify its origin.


Set the origin of the value group to null. Useful for cases when there values are collected in a single place, so there’s no natural and meaningful origin.


Expiration age for values. Values older than <seconds> are removed from listing by statetipd(8).

Sender mode input protocol

Input protocol is a sequence of non-empty lines, each having up to four whitespace-separated fields.

If values’ origin was pre-defined with --origin or --null-origin, then statetip expects one of the following line formats:

key state
key state severity

If neither of the options were specified, statetip expects the origin as an additional first field (this allows to send values of several origins):

origin key
origin key state
origin key state severity

Name, origin, key, and state are non-empty strings that consist of letters, digits, ".", "_", "-". Key and state can also contain "/" characters.

If severity is specified, it should be either expected, warning, or error.

See Also

Table Of Contents

Previous topic

Usage ideas

Next topic

StateTip daemon

This Page