About
=====

`purest` is a simple implementation of a WSGI application geared towards easy
implementation of REST based applications. Each REST application implements a
concrete strategy by mapping URI paths and HTTP methods to callables. It does
basicaly two things:

1) For each incoming HTTP request serialize the WSGI environment and call the
   :py:meth:`URIHandler.parse` callable. This method parses the path and
   determines the right application handler.
2) A mechanism for applications to register url+method to handler mappings.
   Applications should export a list of dictionaries containing a triple of
   URI, http method and the callable as endpoint. The
   :py:meth:`URIHandler.map` method rebuilds an internal :py:class:`Map`
   objects, that is a list of these tripels.

License
=======

This software is under the GPLv3 license. See the file `License` that comes
with this distribution for a copy of it.

Install
=======

But you can try it the following way on your laptop::

    $ sudo apt-get install couchdb collectd-core
    $ couchdb                                       # -> runs in foreground
    $ sudo pip install gunicorn
    $ git clone git://github.com/crito/purest.git
    $ cd purest
    $ python2.7 setup.py install

Start the wsgi application::

    $ gunicorn --debug -b 127.0.0.1:9797 purest.core:WSGI

This is a minimal config file for collectd::

    FQDNLookup true
    Interval 30
    LoadPlugin syslog

    <Plugin syslog>
            LogLevel info
    </Plugin>

    LoadPlugin battery
    LoadPlugin cpu
    LoadPlugin df
    LoadPlugin disk
    LoadPlugin entropy
    LoadPlugin interface
    LoadPlugin irq
    LoadPlugin load
    LoadPlugin memory
    LoadPlugin processes
    LoadPlugin rrdtool
    LoadPlugin swap
    LoadPlugin users
    LoadPlugin write_http

    <Plugin "write_http">
      <URL "http://127.0.0.1:9797/collectd/data">
         Format "JSON"
         #User "collectd"
         #Password "weCh3ik0"
      </URL>
    </Plugin>

    <Plugin disk>
            Disk "/sda[1-9]/"
    </Plugin>

Run the collectd daemon::

    $ sudo collectd -C /etc/collectd/collectd.conf -f
    
Thats it. It should start to fill the db with documents. Each collection is
stored in a seperate database. Each collection is identified by the following
five parts::

    hostname-plugin-plugin_instance-type-type_instance

    eg: fenix_30loops_net-df--df-boot  

        fenix_30loops_net   ==> Hostname
        df                  ==> Plugin
                            ==> Plugin Instance (If not set, it stays empty
        df                  ==> Type
        boot                ==> Type Instance

With the creation of each database a basic catch all view is added alongside::

    curl -X GET http://127.0.0.1:5984/fenix_30loops_net-df--df-boot/_design/basic/_view/all 

The `startkey` and `endkey` parameters can be aplied to the URI. See the
couchdb documentation for more information.

URI Strategies
==============

Currently there are 2 strategies implemented:

#) **collectd** - Collectd can post its values as json messages
#) **metrics** - Retrieve collections as key/value tables.

URI's
=====

:: 

    POST /collectd/data/  -> Parse a list of collected values and store them in the
                             backend
    GET /metrics/all_dbs/ -> Retrieve the collection structure in a
                             hierarchical JSON object
    GET /metrics/<host>/<plugin>/<plugin_instance>/<type>/<type_instance>/
                          -> Retrieve a specific collection. Return type can
                             also be a list of collections. If a part of the
                             URI is replaced with a 'x', all sub nodes of its
                             parent node are added to the return list. If this token 
                             is not set use 'x' to substitute it.


    ## Get the whole collection structure as a nested dictionary

    [crito@fenix.30loops.net:~] (0) % curl -X GET http://127.0.0.1:9797/metrics/all_dbs 
    {"fenix.30loops.net": 
         "processes": 
            {"-": 
                {"fork_rate": 
                    {"-": []}, 
                 "ps_state": 
                    {"running": [], "sleeping": [], "paging": [], "stopped": [], "zombies": [], "blocked": []}
                 }
            }, 
         "memory": 
            {"-": 
                {"memory": 
                    {"cached": [], "buffered": [], "used": [], "free": []}
                }
            }, 
         "interface": 
            {"-": 
                {"if_packets": 
                    {"lo": [], "pan0": [], "irda0": [], "wlan0": [], "eth0": []}, 
                 "if_errors": 
                    {"lo": [], "pan0": [], "irda0": [], "wlan0": [], "eth0": []}, 
                 "if_octets": 
                    {"lo": [], "pan0": [], "irda0": [], "wlan0": [], "eth0": []}
                }
            }, 
         "disk": 
            {"sda5": 
                {"disk_merged": 
                    {"-": []}, 
                 "disk_ops": 
                    {"-": []}, 
                 "disk_time": 
                    {"-": []}, 
                 "disk_octets": 
                    {"-": []}
                }, 
             }, 
          "cpu": 
            {"1": 
                {"cpu": 
                    {"softirq": [], "system": [], "idle": [], "user": [], "interrupt": [], "nice": [], "steal": [], "wait": []}
                }, 
             "0": 
                {"cpu": 
                    {"softirq": [], "system": [], "idle": [], "user": [], "interrupt": [], "wait": [], "steal": [], "nice": []}
                }
            }
        }
    }


    ## Retrieve a single Database

    crito@mystique:~$ curl -X GET http://127.0.0.1:9797/metrics/mystique/cpu/0/cpu/wait/
    {"rows": [{"value": [20992], "id": "ed9dac01-e579-4daa-9b2b-653f7c361889", "key": 1301489147}, {"value": [21286], "id": "0bd1c456-a5df-4c75-9e9b-d0ae49e17457", "key": 1301489177}, {"value": [21381], "id": "7e30f0e5-2523-4773-ad7f-28989daa9b82", "key": 1301489207}, {"value": [21628], "id": "c8cab314-53f8-4dfe-9a9f-7ce7faf96744", "key": 1301489237}, {"value": [22045], "id": "10cf5b42-b4cb-4e09-8f33-7801d9dfb04b", "key": 1301492194}, {"value": [22249], "id": "0469e15a-820b-4cdf-9a03-6aab8d52ac70", "key": 1301492457}, {"value": [22387], "id": "acda25a8-160a-469e-b8f1-a1fe1b2cd70c", "key": 1301492515}, {"value": [22505], "id": "f20eca6f-ceee-482d-a949-6f3cbd7dabe7", "key": 1301492726}, {"value": [22638], "id": "84ea6b5c-3386-43c8-90a2-403b5552afd7", "key": 1301492756}, {"value": [22776], "id": "c3904dbc-4399-43e8-8e48-3e78b74a4170", "key": 1301492786}], "total_rows": 10, "offset": 0}

    crito@mystique:~$ curl -X GET http://127.0.0.1:9797/metrics/mystique/disk/md0/disk_ops/x/
    {"rows": [{"value": [616792, 3372855], "id": "9dc73b9b-0d63-4ea1-966f-f4f7db7b0a19", "key": 1301489208}, {"value": [616792, 3373058], "id": "ea51ff99-02f9-480b-b45d-4e7c083ca25a", "key": 1301489237}, {"value": [617188, 3401497], "id": "6768af77-80fb-49f0-8c81-4bb5d15e2d9a", "key": 1301492786}], "total_rows": 3, "offset": 0}