django-watchman

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

Features

• Status endpoint -- JSON response with the health of all backing services
• Human-friendly dashboard -- HTML dashboard at /watchman/dashboard/
• Built-in checks -- Databases, caches, storage, and email out of the box
• Custom checks -- Write your own checks and plug them in
• Token-based authentication -- Protect the endpoint with configurable tokens
• Management command -- Run checks from the CLI via python manage.py watchman
• Ping endpoint -- Lightweight /watchman/ping/ endpoint returning pong
• Bare status view -- Minimal HTTP 200/500 response for load balancers
• APM integration -- Suppress tracing for health check endpoints (Datadog, New Relic)

Endpoints

Including watchman.urls gives you three endpoints. The bare status view is added separately in your own urls.py.

Endpoint	Description	Auth
/watchman/	JSON response with full check results	Yes
/watchman/dashboard/	Human-friendly HTML dashboard	Yes
/watchman/ping/	Returns pong -- no checks run, just a liveness probe	No
/watchman/bare/	Empty response, HTTP 200 or 500 -- wire up manually via watchman.views.bare_status	No

Built-in Checks

Check	Module path	Default	Description
Databases	watchman.checks.databases	Yes	Verifies connectivity for each database in DATABASES
Caches	watchman.checks.caches	Yes	Sets, gets, and deletes a test key in each cache from CACHES
Storage	watchman.checks.storage	Yes	Writes, reads, and deletes a test file using default_storage
Email	watchman.checks.email	No	Sends a test email -- disabled by default since it may incur costs with third-party providers

Enable email and other paid checks with WATCHMAN_ENABLE_PAID_CHECKS = True, or customize the full list with the WATCHMAN_CHECKS setting. You can also write custom checks.

Documentation

The full documentation is at django-watchman.readthedocs.io.

Used By

django-watchman is trusted in production by organizations including:

• Mozilla -- mozilla.org, support.mozilla.org, basket, and more
• Harvard University -- LMS tools and course management
• University of Michigan -- My Learning Analytics, Remote Office Hours Queue
• UNICEF -- GeoRepo
• Caluma -- Swiss government digital forms platform
• Open Supply Hub -- Global supply chain transparency
• Azavea -- Civic technology (NYC Trees, DistrictBuilder, climate tools)
• PeopleForBikes -- Bike network connectivity analysis
• Worldcon Voting Systems -- Hugo Awards nomination and voting platform

See the full list of dependents on GitHub.

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

1. Install django-watchman:

   pip install django-watchman
   

   Or with uv:

   uv add django-watchman
   

2. Add watchman to your INSTALLED_APPS setting:

   INSTALLED_APPS = (
       ...
       'watchman',
   )
   

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

   re_path(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
               }
           }
       ],
       "caches": [
           {
               "default": {
                   "ok": true
               }
           }
       ],
       "storage": {"ok": true}
   }
   

5. You can also run checks from the command line:

   python manage.py watchman
   

   Use -v 2 for verbose output, -c to run specific checks, or -s to skip checks.

Configuration Highlights

Setting	Description
WATCHMAN_TOKENS	Comma-separated tokens to protect the endpoint
WATCHMAN_TOKEN_NAME	Custom GET parameter name for the token (default: watchman-token)
WATCHMAN_AUTH_DECORATOR	Dotted path to a custom auth decorator (default: watchman.decorators.token_required)
WATCHMAN_CHECKS	Tuple of dotted paths to the checks to run
WATCHMAN_ENABLE_PAID_CHECKS	Enable paid checks like email (default: False)
WATCHMAN_DATABASES	Subset of DATABASES to check
WATCHMAN_CACHES	Subset of CACHES to check
WATCHMAN_EXPOSE_ERROR_DETAILS	Include exception messages and stacktraces of failed checks in responses (default: False)
WATCHMAN_ERROR_CODE	HTTP status code for failing checks (default: 500)
WATCHMAN_DISABLE_APM	Suppress APM tracing on watchman views (default: False)
EXPOSE_WATCHMAN_VERSION	Include X-Watchman-Version response header (default: False)

See the full configuration documentation for details and examples.

Contributing

Contributions are welcome! Please see the contributing guide for details on how to get started.

License

BSD-3-Clause