Documentation updates.
authorStanislaw Klekot <dozzie@jarowit.net>
Tue, 16 May 2017 20:42:18 +0000 (22:42 +0200)
committerStanislaw Klekot <dozzie@jarowit.net>
Tue, 16 May 2017 20:42:18 +0000 (22:42 +0200)
Main changes are documented operating StateTip (quick start guide and data
model), descriptions of a few possible StateTip uses, and project description
in README.

README.md
doc/ideas.rst [new file with mode: 0644]
doc/index.rst
doc/manpages/client.rst
doc/manpages/daemon.rst
doc/operations.rst [new file with mode: 0644]

index 74c4152..39a2659 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,19 +1,15 @@
 StateTip recent state registry
 ==============================
 
-StateTip is an application intended for remembering most recent values for
-different variables collected by a monitoring system.
+StateTip is a data store that works with streams of messages and remembers the
+most recent one from each of the streams. The streams can be enumerated and
+their (current) state retrieved.
 
-This allows monitoring probe to simply read the current state of the thing
-being monitored (e.g. network link status) in regular intervals and send the
-result out. StateTip receives such a state, remembers it, and allows some
-dashboard to read what was the most recent state.
+StateTip can be used as a backend for dashboards or work as a simple inventory
+(which is also useful for dashboards, as a list of items to display).
 
-StateTip can also recombine stream of messages back into a list. For instance,
-it makes sense to collect hosts availability as a separate message for each
-host, but sometimes it's necessary to get a list of monitored hosts back from
-the events stream. StateTip again allows to collect data in simplest form,
-rebuilding the list from the stream.
+StateTip is part of a larger project [Seismometer](http://seismometer.net/),
+monitoring system of modern architecture and flexibility.
 
 Contact and License
 -------------------
diff --git a/doc/ideas.rst b/doc/ideas.rst
new file mode 100644 (file)
index 0000000..075e5b7
--- /dev/null
@@ -0,0 +1,44 @@
+***********
+Usage ideas
+***********
+
+StateTip is designed as a data backend for dashboards in monitoring system.
+The consequence is that data sent to StateTip in real time as a stream, but
+retrieved on request. This operation mode comes handy in a number of
+scenarios.
+
+
+Monitoring display
+==================
+
+The most obvious is the original need: monitoring. Let's assume a StateTip
+instance receives from a monitoring system data from probes, like server
+availability, CPUs, or filesystems. This StateTip allows to build a dashboard
+with all known servers along with their status (*up*/*down*) and another one
+that for a specified server displays disk space usage for server's
+filesystems (disk usage graphs need to be retrieved from somewhere else, but
+list of what needs to be retrieved is read from StateTip).
+
+A similar use is to make StateTip to remember result of a task job is run not
+too often. Some good examples include a cron script that finds X.509
+certificates in :file:`/etc` and lists their expiry time and backup jobs.
+These can be then displayed on a dashboard.
+
+In the above examples a dashboard is supposed to query StateTip to discover
+objects to display. This allows sysadmin to avoid registering any new server
+or service in the dashboard.
+
+
+Inventory
+=========
+
+StateTip can be used to keep an inventory of system elements, like status of
+OS updates or versions of software running on servers. The status would be
+collected by a cron script and sent to StateTip, which then can be queried at
+later time.
+
+Inventory can also be generated indirectly. Identity of VPN clients can be
+extracted VPN gateway logs, or MAC+IP can be extracted from DHCP leases. Once
+these are sent to StateTip, sysadmin can check in a single place where
+a specific VPN client or device is connected to.
+
index 9dc9002..9e9a7f8 100644 (file)
@@ -2,12 +2,26 @@
 StateTip
 ********
 
+StateTip is a data store that works with streams of messages and remembers the
+most recent one from each of the streams. The streams can be enumerated and
+their (current) state retrieved.
+
+StateTip can be used as a backend for dashboards or work as a simple inventory
+(which is also useful for dashboards, as a list of items to display).
+
+StateTip is part of a larger project `Seismometer <http://seismometer.net/>`_,
+monitoring system of modern architecture and flexibility.
+
+
 Table of contents
 =================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
+   :titlesonly:
 
+   operations
+   ideas
    manpages/client
    manpages/daemon
    python-api
index 0dd0842..4aecff5 100644 (file)
@@ -30,6 +30,8 @@ Usage
 There are several "top-level" options, which work regardless of the selected
 mode (or that select the client mode):
 
+.. program:: statetip
+
 .. option:: --reader
 
     Select reader mode. This is the default.
index cf21b7d..a45c6ca 100644 (file)
@@ -49,6 +49,8 @@ that are described below.
 Commands
 --------
 
+.. program:: statetipd
+
 Commands that are issued to a daemon instance (all except ``start`` and
 ``log-*``) use the path to control socket specified with :option:`--socket`
 option as the target daemon's address. Similarly, ``start`` uses
@@ -158,6 +160,8 @@ option as the target daemon's address. Similarly, ``start`` uses
 Options
 -------
 
+.. program:: statetipd
+
 .. option:: --socket <path>
 
     Location of an administrative socket, where a command will be sent (or on
diff --git a/doc/operations.rst b/doc/operations.rst
new file mode 100644 (file)
index 0000000..9cfc557
--- /dev/null
@@ -0,0 +1,153 @@
+******************
+Operating StateTip
+******************
+
+.. _quick-start-guide:
+
+Quick start guide
+=================
+
+In this guide we'll assume that StateTip has already been installed, likely
+from RPM or DEB package.
+
+Running :program:`statetipd`
+----------------------------
+
+The first thing to do is to create a config file :file:`statetip.toml`:
+
+.. code-block:: ini
+
+    #[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:
+
+.. code-block:: none
+
+    /usr/sbin/statetipd start --config ./statetip.toml --socket /tmp/statetip.sock
+
+By default, :program:`statetipd` uses :file:`/etc/statetip/statetip.toml` as
+config and :file:`/var/run/statetip/control` as control socket path.
+
+:program:`statetipd` is shut down with following command:
+
+.. code-block:: none
+
+    /usr/sbin/statetipd stop --socket /tmp/statetip.sock
+
+:program:`statetipd` can also accept a number of administrative commands on
+its control socket. See :doc:`manpages/daemon` for details.
+
+Sending data to :program:`statetipd`
+------------------------------------
+
+The easiest way to send data to StateTip is to use :doc:`command line client
+<manpages/client>`:
+
+.. code-block:: none
+
+    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 :ref:`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:
+
+.. code-block:: none
+
+    $ statetip
+    health
+    $ statetip health
+    <null>
+    $ statetip health ""
+    myhost
+    $ statetip health "" `hostname`
+    healthy
+
+Full record can be viewed with :option:`--all <statetip --all>` option (lines
+wrapped for reading convenience):
+
+.. code-block:: none
+
+    $ statetip health "" `hostname` --all
+    {"info": null, "key": "alojzy", "name": "health", "origin": null,
+      "severity": "expected", "state": "healthy"}
+
+Equally important to command line client are :ref:`sender <sender-protocol>`
+and :ref:`reader <reader-protocol>` 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 :doc:`manpages/protocols`. For documentation about their Python
+implementation, see :doc:`python-api`.
+
+
+.. _data-model:
+
+Data model
+==========
+
+StateTip is designed to work with data streams, remembering the latest value
+from each. These streams are grouped by their meaning into :term:`value groups
+<value group>`, and such a group has a :term:`name <group 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`` :term:`origin <group 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 :term:`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 :term:`values <value>`.
+
+A :term:`value` can carry three fields:
+
+* :term:`state` describes status of the item
+* :term:`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 :term:`value` doesn't need to carry a :term:`state`, it can also
+be used for just keeping an inventory of known items.
+
+:term:`Values <value>` used for inventory only are often collected at
+a particular :term:`origin <group origin>` at the same time and can be thought
+of as a set. In such case, marking this :term:`value group` as a group of
+:term:`related values` results in all the :term:`keys <key>` being replaced at
+the next data batch. If the group is marked as :term:`unrelated values`, each
+:term:`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 :term:`state log file` to store stream
+data. The log file records changes to the values and is :term:`replayed <log
+replaying>` after restart. Log file is automatically :term:`compacted <log
+compaction>` when it reaches configured size, to both preserve disk space and
+to keep restart time sensible.
+
+A typical :term:`record <log record>` in the log file uses around 100-150
+bytes of space, which is comparable to a single JSON in :ref:`sender protocol
+<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.
+