django-watchman 0.3.0

django-watchmen exposes a status endpoint for your backing services

=============================
django-watchman
=============================

.. image:: http://img.shields.io/pypi/v/django-watchman.svg
:target: http://badge.fury.io/py/django-watchman

.. image:: http://img.shields.io/travis/mwarkentin/django-watchman/master.svg
:target: https://travis-ci.org/mwarkentin/django-watchman

.. image:: http://img.shields.io/coveralls/mwarkentin/django-watchman.svg
:target: https://coveralls.io/r/mwarkentin/django-watchman?branch=master

django-watchman exposes a status endpoint for your backing services like
databases, caches, etc.

.. image:: https://s3.amazonaws.com/snaps.michaelwarkentin.com/watchmenozy.jpg

Documentation
-------------

The full documentation is at http://django-watchman.rtfd.org.

Quickstart
----------

1. Install ``django-watchman``::

pip install django-watchman

2. Add ``watchman`` to your ``INSTALLED_APPS`` setting like this::

INSTALLED_APPS = (
...
'watchman',
)

3. Include the watchman URLconf in your project ``urls.py`` like this::

url(r'^watchman/', include('watchman.urls')),

4. Start the development server and visit ``http://127.0.0.1:8000/watchman/`` to
get a JSON response of your backing service statuses::

{
"databases": [
{
"default": {
"ok": true
}
}
],
"email": {
"ok": true
},
"caches": [
{
"default": {
"ok": true
}
}
]
}

Features
--------

Token based authentication
**************************

If you want to protect the status endpoint, you can add a ``WATCHMAN_TOKEN`` to
your settings. When this setting is added, you must pass that value in as the
``watchman-token`` **GET** parameter::

GET http://127.0.0.1:8000/watchman/?watchman-token=:token

If you want to change the token name, you can set the ``WATCHMAN_TOKEN_NAME``.
The value of this setting will be the **GET** parameter that you must pass in::

WATCHMAN_TOKEN_NAME = 'custom-token-name'

GET http://127.0.0.1:8000/watchman/?custom-token-name=:token

Custom checks
*************

django-watchman allows you to customize the checks which are run by modifying
the ``WATCHMAN_CHECKS`` setting. In ``settings.py``::

WATCHMAN_CHECKS = (
'module.path.to.callable',
'another.module.path.to.callable',
)

Checks now have the same contract as context processors: they consume a
``request`` and return a ``dict`` whose keys are applied to the JSON response::

def my_check(request):
return {'x': 1}

In the absence of any checks, a 404 is thrown, which is then handled by the
``json_view`` decorator.

Run a subset of available checks
********************************

A subset of checks may be run, by passing ``?check=module.path.to.callable&check=...``
in the request URL. Only the callables given in querystring, which are in the
``WATCHMAN_CHECKS`` should be run, eg::

curl -XGET http://127.0.0.1:8080/watchman/?check=watchman.checks.caches_status

Default checks
--------------

By default, django-watchman will run checks against your databases
(``watchman.checks.databases_status``), caches (``watchman.checks.caches_status``),
and email (``watchman.checks.email_status``).




History
-------

0.3.0 (2014-09-05)
++++++++++++++++++

* New check - email (``watchman.checks.email_status``)! django-watchman will now
check that your email settings are working too!
* Fix a few small issues in the readme
* Rearrange some of the code in checks.py

0.2.2 (2014-09-05)
++++++++++++++++++

* Fix and run tests on Python 2.7 and 3.4
* Bump django-jsonview dependency to latest
* Update tox envlist and travis config to test 2.7 / 3.4

0.2.1 (2014-09-04)
++++++++++++++++++

* Initialize django during tests to prevent app loading issue for Django >= 1.7
* Suppress ``MIDDLEWARE_CLASSES`` warning for Django >= 1.7
* Reorganize test imports
* Fix ``make test``, ``make coverage``, ``make release`` commands
* Add htmlcov/ directory to .gitignore
* Test django 1.4, 1.6, 1.7

0.2.0 (2014-09-04)
++++++++++++++++++

* Custom checks can now be written and run using the ``WATCHMAN_CHECKS`` setting
* A subset of the available checks can be run by passing the ``check`` GET param
when hitting the watchman url

0.1.2 (2014-02-21)
++++++++++++++++++

* Move package requirements out of requirements.txt and into setup.py

0.1.1 (2014-02-09)
++++++++++++++++++

* Remove ``django>=1.5.5`` version specification
* Remove ``wheel`` requirement


0.1.0 (2014-02-08)
++++++++++++++++++

* First release on PyPI.