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.

Built-in Checks

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

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