paulla.checkplanetdiff 0.4
A nagios|icinga plugin to check diff delay with the official OpenStreetMap Planet.
License: bsd
Keywords: Nagios Icinga OSM

.. contents::

Introduction
============


check_planet.diff is a 'Nagios like' (Nagios|Icinga|Centreon|Shinken) probe checking the delay of your OSM Planet with offical, based on minute-diff state files.

More infos here http://wiki.openstreetmap.org/wiki/Minutely_Mapnik

- Code repository: https://github.com/paulla/paulla.checkplanetdiff


Install
-------

easy_install | pip witthin or not a virtualenv::
    
    pip install | easy_install paulla.check_planetdiff

zc.buildout users just add paulla.check_planetdiff to your eggs list as usual.

You could simply run install or tests with::
     
     bin/python setup.py install
     bin/python setup.py test

Mayba add a symbolic link from bin/check_planetdiff to your nagios/plugins/ directory



Nagios like configuration
---------------------------

check_planetdiff could be called localy or remotely via check_by_ssh or NRPE.

here a sample definition to check remotely by ssh 

Command definition ::
    
    # 'check_ssh_planetdiff' command definition
    define command {
            command_name    check_ssh_planetdiff
            command_line    $USER1$/check_by_ssh -H $HOSTADDRESS$ -C "/usr/lib/nagios/plugins/check_planetdiff -w $ARG1$ -c $ARG2$ --state-file $ARG3$ -p" 
    }

Notice the last -p arg for performance data is optionnal, remove it if don't needed.

the service itself::
    
     # planet diff delay
     define service {
            use                             paulla-service
            service_description             delay planet diff
            check_command                   check_ssh_planetdiff!0.0:3600.0!0.0:21600.0!/home/mapnik/.osmosis/state.txt
            host_name                       biscaou
     }




Nagios like' synchronise delay OSM Planet check
=================================================


Use case


The check is simple and robust, no database query.

Delay is just datetime.datetime.utcnow() - OSM timestamp in state.txt (usaualy /home/mapnik.osmosis/state.txt)

More infos here http://wiki.openstreetmap.org/wiki/Minutely_Mapnik

We fake 3 state files with three different timestamp (see tests/ directory). 

We have to fake now according to tests files states.

now = datetime(2012, 10, 23, 20, 4, 30) # see test function

Real check is datetime.datetime.utcnow()

Warning and critical thresholds are respectively 3600 and 21600 seconds (1 and 6 hours)

Time to work

necessary stuff::
    
    >>> import glob
    >>> import subprocess
    >>> from datetime import datetime
    >>> from pprint import pprint

a funtion to get lines from fake state files::
    
    >>> def get_lines_from_file(filename):
    ...     with open(filename) as state_file:
    ...         return state_file.read().splitlines()
    ...
    

Usage
------

-h option ::
    
    >>> cmd_h = "bin/test_check_planetdiff -h"
    >>> p_help = subprocess.Popen(cmd_h.split(), stdout=subprocess.PIPE)
    >>> pprint(p_help.stdout.readlines())
    ['Usage: test_check_planetdiff [options]\n',
     '\n',
     'Options:\n',
     '  --state-file=STATEFILE\n',
     '  -p                    return performance data\n',
     '  -v, --verbose         \n',
     '  -H HOSTNAME, --hostname=HOSTNAME\n',
     '  -w WARNING, --warning=WARNING\n',
     '  -c CRITICAL, --critical=CRITICAL\n',
     '  -t TIMEOUT, --timeout=TIMEOUT\n',
     '  -h, --help            show this help message and exit\n']


Checks
--------

Less than 1 hour returns OK::
    
    >>> state_file_ok = "src/paulla/checkplanetdiff/tests/state_ok.txt"
    >>> pprint(get_lines_from_file(state_file_ok))
    ['#Tue Oct 23 22:05:12 CEST 2012',
     'sequenceNumber=59592',
     'timestamp=2012-10-23T20\\:04\\:02Z']

    >>> cmd_ok = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file %s" % state_file_ok
    >>> p_ok = subprocess.Popen(cmd_ok.split(), stdout=subprocess.PIPE)

Status code is 0 -> OK::
    
    >>> p_ok.wait()
    0

String output::
    
    >>> p_ok.stdout.read()
    'OK: delay : 28, sequence number : 59592\n'

with perfdata option::
    
    >>> cmd_ok = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file %s -p" % state_file_ok 
    >>> p_ok = subprocess.Popen(cmd_ok.split(), stdout=subprocess.PIPE)
    >>> p_ok.stdout.read()
    'OK: delay : 28, sequence number : 59592|delayed=28s;3600;21600;;\n'

Delay between 1 hour and 6 returns WARNING::
    
    >>> state_file_warn = "src/paulla/checkplanetdiff/tests/state_warning.txt"
    >>> pprint(get_lines_from_file(state_file_warn))
    ['#Tue Oct 23 18:25:07 CEST 2012',
     'sequenceNumber=59372',
     'timestamp=2012-10-23T16\\:24\\:03Z']

    >>> cmd_warn = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file %s" % state_file_warn
    >>> p_warn = subprocess.Popen(cmd_warn.split(), stdout=subprocess.PIPE)

Status code is 1 -> WARNING::
    
    >>> p_warn.wait()
    1

String output::
    
    >>> p_warn.stdout.read()
    'WARN: delay : 13227, sequence number : 59372\n'

with perfdata option::
    
    >>> cmd_warn = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file %s -p" % state_file_warn
    >>> p_warn = subprocess.Popen(cmd_warn.split(), stdout=subprocess.PIPE)
    >>> p_warn.stdout.read()
    'WARN: delay : 13227, sequence number : 59372|delayed=13227s;3600;21600;;\n'

More than 6 hours returns CRITICAL::
    
    >>> state_file_crit = "src/paulla/checkplanetdiff/tests/state_critical.txt"
    >>> pprint(get_lines_from_file(state_file_crit))
    ['#Tue Oct 23 12:25:07 CEST 2012',
     'sequenceNumber=59012',
     'timestamp=2012-10-23T10\\:24\\:03Z']
    
    >>> cmd_crit = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file %s" % state_file_crit
    >>> p_crit = subprocess.Popen(cmd_crit.split(), stdout=subprocess.PIPE)

Status code is 2 -> CRITICAL::
    
    >>> p_crit.wait()
    2

String output::
    
    >>> p_crit.stdout.read()
    'CRIT: delay : 34827, sequence number : 59012\n'

with perfdata option::
    
    >>> cmd_crit = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file %s -p" % state_file_crit
    >>> p_crit = subprocess.Popen(cmd_crit.split(), stdout=subprocess.PIPE)
    >>> p_crit.stdout.read()
    'CRIT: delay : 34827, sequence number : 59012|delayed=34827s;3600;21600;;\n'

Non existant state file returns CRITICAL::
    
    >>> cmd_crit_non_exist_file = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file src/non_existant.txt"
    >>> p_crit_nonexist = subprocess.Popen(cmd_crit_non_exist_file.split(), stdout=subprocess.PIPE)

Status code is 2 -> CRITICAL::
    
    >>> p_crit_nonexist.wait()
    2

String output::
    
    >>> p_crit_nonexist.stdout.read()
    'CRIT: delay : 21601, sequence number : 0\n'

with perfdata option::
    
    >>> cmd_crit_non_exist_file = "bin/test_check_planetdiff -w 0.0:3600.0 -c 0.0:21600.0 --state-file src/non_existant.txt -p"
    >>> p_crit_nonexist = subprocess.Popen(cmd_crit_non_exist_file.split(), stdout=subprocess.PIPE)
    >>> p_crit_nonexist.stdout.read()
    'CRIT: delay : 21601, sequence number : 0|delayed=21601s;3600;21600;;\n'



Changelog
=========


0.4 (2012-10-27)
----------------

- fix README error


0.3 (2012-10-27)
----------------

- Nothing changed yet.


0.2 (2012-10-27)
----------------

-  improve help usage and corresponding tests


0.1 (2012-10-26)
----------------

- Firts version used in production at http://www.paulla.asso.org
  [Jean-Philippe Camguilhem]



Credits
========
|paulla|_

  * `PauLLA <http://www.paulla.asso.fr>`_
  * `Contact us <mailto:contact@paulla.asso.fr>`_

.. |paulla| image:: http://www.paulla.asso.fr/logo.png
.. _paulla:  http://www.paulla.asso.fr


Contributors
=============
Jean-Philippe Camguilhem, Author