Operating StateTip

Quick start guide

In this guide we’ll assume that StateTip has already been installed, likely from RPM or DEB package.

Running statetipd

The first thing to do is to create a config file statetip.toml:

#[senders]
#listen = [":3012"]

#[readers]
#listen = [":3082"]

The commented sections show default values of the options. An empty file will work just as well, but this one gives a little structure for future changes.

Now we’re ready to run StateTip daemon:

/usr/sbin/statetipd start --config ./statetip.toml --socket /tmp/statetip.sock

By default, statetipd uses /etc/statetip/statetip.toml as config and /var/run/statetip/control as control socket path.

statetipd is shut down with following command:

/usr/sbin/statetipd stop --socket /tmp/statetip.sock

statetipd can also accept a number of administrative commands on its control socket. See StateTip daemon for details.

Sending data to statetipd

The easiest way to send data to StateTip is to use command line client:

echo "`hostname` healthy" | statetip --sender --name=health --null-origin

StateTip stores values that are textual representation of state of some object. The values are addressed with a triplet of name, origin, and key. See Data model section for detailed reference.

The example above creates a group of values called "health" with a single value under origin null and key being the local host name. State carried by the value equals to "healthy".

Data kept by StateTip can be inspected like this:

$ statetip
health
$ statetip health
<null>
$ statetip health ""
myhost
$ statetip health "" `hostname`
healthy

Full record can be viewed with --all option (lines wrapped for reading convenience):

$ statetip health "" `hostname` --all
{"info": null, "key": "alojzy", "name": "health", "origin": null,
  "severity": "expected", "state": "healthy"}

Equally important to command line client are sender and reader client protocols, as they are intended for programmatic access to StateTip. In fact, statetip --sender only allows for simplified data compared to sender protocol. For protocols description, see Client protocols. For documentation about their Python implementation, see Python API.

Data model

StateTip is designed to work with data streams, remembering the latest value from each. These streams are grouped by their meaning into value groups, and such a group has a name.

Different streams are often collected at different places, which may or may not be important distinction. For the cases when it is important, a stream can have non-null origin. Name of the host where the stream comes from usually makes a good origin.

Object or resource whose state a stream describes is specified as key. Mount point of a filesystem is an example of a key.

Together, a triplet of name, origin, and key identify a particular stream of values.

A value can carry three fields:

  • state describes status of the item
  • severity ("expected", "warning", or "error") describes if an operator should pay attention to the resource
  • additional information about the item in the form of an arbitrary JSON value, opaque to StateTip daemon

Note that a value doesn’t need to carry a state, it can also be used for just keeping an inventory of known items.

Values used for inventory only are often collected at a particular origin at the same time and can be thought of as a set. In such case, marking this value group as a group of related values results in all the keys being replaced at the next data batch. If the group is marked as unrelated values, each key expires individually, so old items may linger for some time.

State log file

StateTip, being a memory-first data store, on restart loses its knowledge about states of all streams. For monitoring system this is not usually a problem, since the streams will repopulate StateTip in a few minutes after restart.

On the other hand, if StateTip is used to keep status of jobs that are running less often, it’s useful to configure state log file to store stream data. The log file records changes to the values and is replayed after restart. Log file is automatically compacted when it reaches configured size, to both preserve disk space and to keep restart time sensible.

A typical record in the log file uses around 100-150 bytes of space, which is comparable to a single JSON in sender protocol. If the values arrive at an average rate of rate 6kB/s (40 messages per second), a log file should reach 10MB after about 30 minutes.

Table Of Contents

Previous topic

StateTip

Next topic

Usage ideas

This Page