syscheck
========

syscheck is a simple dashboard for monitoring the go/no go state of
arbitrary systems and powered by Tornado_. A series of "checkers" can
be defined to periodically check the status of distributed systems and
display the results in a browser. It was originally developed to
monitor laser frequencies, optical cavities, and other components for
quantum physics experiments, but can be used for getting a quick
visual overview of the up or down status of assorted systems.

syscheck comes with a number of built-in checkers to handle some
common use cases. These include checkers for:

* HTTP: see that an HTTP(S) endpoint is accessible
* JSON: check that a given HTTP request results in specific JSON
  values
* Redis: like JSON checkers, but with Redis_!
* Supervisor: see if a process started by Supervisor_ is up

.. _Tornado: http://www.tornadoweb.org/en/stable/
.. _Redis: http://redis.io/
.. _Supervisor: http://supervisord.org/

Syscheck is licensed under the BSD license. The source code can be
found on Bitbucket__.

__ https://bitbucket.org/mivade/syscheck

Getting started
---------------

Install using pip::

  $ pip install syscheck

To start checking systems with syscheck, create a Python file and
create a new ``SystemsMonitor``::

  from syscheck.monitor import SystemsMonitor

  monitor = SystemsMonitor()

Now say you want to monitor that the web server on ``localhost`` is
up. This requires creating a new ``Checker`` and registering it with
the ``SystemsMonitor``::

  from syscheck.checker import HttpChecker

  monitor.register(
      HttpChecker('http://localhost'),
      description='localhost Apache')

Categories are also supported so that you can group systems based on
type or function::

  from syscheck.checker import PortChecker, SupervisorChecker

  monitor.register_category(
      'Servers',
      [
          (PortChecker('localhost', 1234), 'My cool service'),
	  (SupervisorChecker('localhost:9001/RPC2', 'thing', 'Another thing'))
      ]
  )

Now it's time to start checking::

  from tornado.ioloop import IOLoop
  from syscheck.web import CheckerApp

  app = CheckerApp(monitor)
  app.listen(8080)
  IOLoop.instance().start()

Point your browser to ``http://localhost:8080`` and see it in action!

Creating custom checkers
------------------------

From time to time, it may be useful to create custom checkers. For
example, say you have a wavelength meter and want to ensure that a
given laser has a frequency within certain limits. If you have an HTTP
service running which can be queried to return this status, you could
define a ``LaserChecker``:

.. literalinclude:: laserchecker.py

Web frontend
------------

The included web frontend provides a simple dashboard for checking the
status of all your systems at a glance. Running the
:class:`CheckerApp` instance automatically injects the following
command-line options:

.. literalinclude:: cli.txt

Additional options exist to configure logging. See the
:mod:`tornado.options` documentation for details.

Endpoints
^^^^^^^^^

The index route (``http://localhost:<port>/``) serves the default
dashboard template and static files. Updates are sent via server-sent
events at the ``/stream`` route. If desired, these can be monitored
with, for example, curl_. The server can also be polled by external
services at ``/status`` to return all statuses from the most recent
check in JSON format.

.. _curl: http://curl.haxx.se/

Warnings
^^^^^^^^

.. versionadded:: 0.3.0

Sometimes, a system that you want to monitor is not critical. In this
case, upon registration, a checker can be set to indicate a warning in
the event of a failed check rather than an outright failure. This
manifests as a different color in the web interface.

API documentation
-----------------

Systems monitor
^^^^^^^^^^^^^^^

.. autoclass:: syscheck.monitor.SystemsMonitor
   :members:

Checkers
^^^^^^^^

.. automodule:: syscheck.checker
   :members:

Web
^^^

.. autoclass:: syscheck.web.CheckerApp
   :members: