django-watchman exposes a status endpoint for your backing services
Project description
django-watchman
django-watchman exposes a status endpoint for your backing services like databases, caches, etc.
Documentation
The full documentation is at http://django-watchman.rtfd.org.
Testimonials
We’re in love with django-watchman. External monitoring is a vital part of our service offering. Using django-watchman we can introspect the infrastructure of an application via a secure URL. It’s very well written and easy to extend. We’ve recommended it to many of our clients already.
— Hany Fahim, CEO, VM Farms.
Quickstart
Install django-watchman:
pip install django-watchman
Add watchman to your INSTALLED_APPS setting like this:
INSTALLED_APPS = ( ... 'watchman', )
Include the watchman URLconf in your project urls.py like this:
url(r'^watchman/', include('watchman.urls')),
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 } } ], "caches": [ { "default": { "ok": true } } ], "storage": {"ok": true} }
Pycon Canada Presentation (10 minutes)
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
Or by setting the Authorization: WATCHMAN-TOKEN header on the request:
curl -X GET -H "Authorization: WATCHMAN-TOKEN Token=\":token\"" http://127.0.0.1:8000/watchman/
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 take no arguments, and must return a dict whose keys are applied to the JSON response. Use the watchman.decorators.check decorator to capture exceptions:
from watchman.decorators import check @check def my_check(): 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 the querystring which are also in WATCHMAN_CHECKS should be run, eg:
curl -XGET http://127.0.0.1:8080/watchman/?check=watchman.checks.caches
Skip specific checks
You can skip any number of checks, by passing ?skip=module.path.to.callable&skip=... in the request URL. Only the checks in WATCHMAN_CHECKS which are not in the querystring should be run, eg:
curl -XGET http://127.0.0.1:8080/watchman/?skip=watchman.checks.email
Django management command
You can also run your checks without starting the webserver and making requests. This can be useful for testing your configuration before enabling a server, checking configuration on worker servers, etc. Run the management command like so:
python manage.py watchman
By default, successful checks will not print any output. If all checks pass successfully, the exit code will be 0. If a check fails, the exit code will be 1, and the error message including stack trace will be printed to stderr.
If you’d like to see output for successful checks as well, set verbosity to 2 or higher:
python manage.py watchman -v 2 {"storage": {"ok": true}} {"caches": [{"default": {"ok": true}}]} {"databases": [{"default": {"ok": true}}]}
If you’d like to run a subset of checks, use -c and a comma-separated list of python module paths:
python manage.py watchman -c watchman.checks.caches,watchman.checks.databases -v 2 {"caches": [{"default": {"ok": true}}]} {"databases": [{"default": {"ok": true}}]}
If you’d like to skip certain checks, use -s and a comma-separated list of python module paths:
python manage.py watchman -s watchman.checks.caches,watchman.checks.databases -v 2 {"storage": {"ok": true}}
Use -h to see a full list of options:
python manage.py watchman -h
Custom response code
By default, watchman will return a 200 HTTP response code, even if there’s a failing check. You can specify a different response code for failing checks using the WATCHMAN_ERROR_CODE setting:
WATCHMAN_ERROR_CODE = 500
Available checks
caches
For each cache in django.conf.settings.CACHES:
Set a test cache item
Get test item
Delete test item
databases
For each database in django.conf.settings.DATABASES:
Verify connection by calling connections[database].introspection.table_names()
Send a test email to to@example.com using django.core.mail.send_mail.
If you’re using a 3rd party mail provider, this check could end up costing you money, depending how aggressive you are with your monitoring. For this reason, this check is not enabled by default.
For reference, if you were using Mandrill, and hitting your watchman endpoint once per minute, this would cost you ~$5.60/month.
Custom Settings
WATCHMAN_EMAIL_RECIPIENTS (default: [to@example.com]): Specify a list of email addresses to send the test email
WATCHMAN_EMAIL_HEADERS (default: {}): Specify a dict of custom headers to be added to the test email
storage
Using django.core.files.storage.default_storage:
Write a test file
Check the test file’s size
Read the test file’s contents
Delete the test file
Default checks
By default, django-watchman will run checks against your databases (watchman.checks.databases), caches (watchman.checks.caches), and storage (watchman.checks.storage).
Paid checks
Currently there is only one “paid” check - watchman.checks.email. You can enable it by setting the WATCHMAN_ENABLE_PAID_CHECKS to True, or by overriding the WATCHMAN_CHECKS setting.
Trying it out with Vagrant
A sample project is available along with a Vagrantfile to make it easy to try out django-watchman.
Requirements
Instructions
Launch vagrant box: vagrant up
SSH into vagrant: vagrant ssh
Activate the virtualenv: workon watchman
Launch the development server: python manage.py runserver 0.0.0.0:8000
Visit watchman json endpoint in your browser: http://127.0.0.1:8000/watchman/
Visit watchman dashboard in your browser: http://127.0.0.1:8000/watchman/dashboard/
History
0.10.0 (2016-05)
[#75] Enable header-based authentication * Set a header instead of passing the token via GET param: "Authorization: WATCHMAN-TOKEN Token=\":token\"" * Improves security by keeping tokens out of logs
[#79] Enable customization of email check * Add WATCHMAN_EMAIL_RECIPIENTS setting - pass a list of recipients the email should be sent to * Add WATCHMAN_EMAIL_HEADERS setting - pass a dict of custom headers to be set on the email
0.9.0 (2015-12-16)
[#51] Update TravisCI Python / Django versions
[#52] Fix deprecated url_patterns
[#53] Change default error response code to 500
[#56] Add @check decorator and refactor existing checks to use it (thanks @benwebber!)
[#57] Sort caches / databases in response for more consistent responses
[#59] Add .editorconfig for improved consistency in contributions
[#61] Add Vagrantfile and docs for how to run and develop on Vagrant instance
[#65] Include assets in source tarball for Debian packaging (thanks @fladi)
[#71] Unpin django-jsonview in setup.py
[#72] Fix stacktrace on dashboard modal and increase width for better readability
0.8.0 (2015-10-03)
[#46] Allow custom response codes with the WATCHMAN_ERROR_CODE setting
0.7.1 (2015-08-14)
Update headers in HISTORY.rst to attempt to fix localshop parsing issues
0.7.0 (2015-08-14)
[#40] Bump django-jsonview for improved Django 1.8 compatibility * Also brought travis Django test versions in line with currently supported Django versions (1.4.x, 1.7.x, 1.8.x)
0.6.0 (2015-07-02)
[#30] Allow users to specify a custom authentication/authorization decorator * Override the @auth decorator by setting WATCHMAN_AUTH_DECORATOR to a dot-separated path to your own decorator * eg. WATCHMAN_AUTH_DECORATOR = 'django.contrib.admin.views.decorators.staff_member_required' * Token-based authentication remains the default
[#31], [#34] Add a human-friendly status dashboard * Available at <watchman url>/dashboard/ * ?check & ?skip GET params work on the dashboard as well
[#35] Add X-Watchman-Version header to responses
0.5.0 (2015-01-25)
Add watchman management command * Exit code of 0 if all checks pass, 1 otherwise * Print json stacktrace to stderr if check fails * Handles --verbosity option to print all status checks * -c, --checks, -s, --skips options take comma-separated list of python paths to run / skip
Improve identifiability of emails sent from a django-watchman endpoint * From: watchman@example.com * Subject: django-watchman email check * Body: This is an automated test of the email system. * Add X-DJANGO-WATCHMAN: True custom header
Add new default check: storage check * Checks that files can be both written and read with the current Django storage engine * Add WATCHMAN_ENABLE_PAID_CHECKS setting to enable all paid checks without modifying WATCHMAN_CHECKS
Remove email_status from default checks
Refactor utils.get_checks to allow reuse in management command * get_checks now performs the optional check inclusion / skipping * status refactored to pull check_list / skip_list from GET params and pass them to get_checks
Namespace cache keys
Update documentation
0.4.0 (2014-09-08)
Add the ability to skip certain checks by passing one or more skip=path.to.callable GET params when hitting the watchman URL
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django-watchman-0.10.0rc0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | da4011453aa2a6469598770fd604efa51041a69f590235e131a9b9f42dc5b90b |
|
MD5 | d15f6928489e08a213e772637ae0c41f |
|
BLAKE2b-256 | 4e02efc3ae1246b2cdabf3d5847bf4847ca6781170e35338f304f95bdeee175e |
Hashes for django_watchman-0.10.0rc0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 453fc78a20cc815d6c7568e78c3b3b675bc00007a88b91d0bde7f5f104aa6a7a |
|
MD5 | 28f98295273c6c3116056c5a7d09ea76 |
|
BLAKE2b-256 | 60d0efeeb24c6841e51cb42a08b9a557806d7a0651334f3bd4f5da247b6d6291 |