Metadata-Version: 2.5
Name: django-watchman
Version: 2.0.0
Summary: django-watchman exposes a status endpoint for your backing services
Project-URL: Homepage, https://github.com/mwarkentin/django-watchman
Project-URL: Documentation, https://django-watchman.readthedocs.io
Project-URL: Repository, https://github.com/mwarkentin/django-watchman
Project-URL: Changelog, https://github.com/mwarkentin/django-watchman/blob/main/CHANGELOG.md
Author-email: Michael Warkentin <mwarkentin@gmail.com>
License-Expression: BSD-3-Clause
License-File: AUTHORS.md
License-File: LICENSE
Keywords: django,health-check,status,watchman
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: django>=4.2
Description-Content-Type: text/markdown

# django-watchman

[![PyPI version](https://img.shields.io/pypi/v/django-watchman.svg)](https://pypi.org/project/django-watchman/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-watchman.svg)](https://pypi.org/project/django-watchman/)
[![PyPI - Django Version](https://img.shields.io/pypi/frameworkversions/django/django-watchman.svg)](https://pypi.org/project/django-watchman/)
[![CI](https://github.com/mwarkentin/django-watchman/actions/workflows/ci.yml/badge.svg)](https://github.com/mwarkentin/django-watchman/actions/workflows/ci.yml)
[![Docs](https://readthedocs.org/projects/django-watchman/badge/?version=stable)](https://django-watchman.readthedocs.io/en/stable/)

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

![Ozymandias](https://mwarkentin-snaps.s3.amazonaws.com/Watchmen_The_One_Thing_Nobody_Says_about_Adrian_Veidt_aka_Ozymandias_2022-03-23_08-36-18.png)

## 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](https://django-watchman.readthedocs.io/en/latest/configuration/#custom-checks).

## Documentation

The full documentation is at [django-watchman.readthedocs.io](https://django-watchman.readthedocs.io).

## Used By

django-watchman is trusted in production by organizations including:

- [Mozilla](https://github.com/mozilla) -- [mozilla.org](https://github.com/mozilla/bedrock), [support.mozilla.org](https://github.com/mozilla/kitsune), [basket](https://github.com/mozmeao/basket), and more
- [Harvard University](https://github.com/Harvard-University-iCommons) -- LMS tools and course management
- [University of Michigan](https://github.com/tl-its-umich-edu) -- [My Learning Analytics](https://github.com/tl-its-umich-edu/my-learning-analytics), [Remote Office Hours Queue](https://github.com/tl-its-umich-edu/remote-office-hours-queue)
- [UNICEF](https://github.com/unicef-drp) -- [GeoRepo](https://github.com/unicef-drp/GeoRepo-OS)
- [Caluma](https://github.com/projectcaluma/caluma) -- Swiss government digital forms platform
- [Open Supply Hub](https://github.com/opensupplyhub/open-supply-hub) -- Global supply chain transparency
- [Azavea](https://github.com/azavea) -- Civic technology ([NYC Trees](https://github.com/azavea/nyc-trees), [DistrictBuilder](https://github.com/PublicMapping/districtbuilder-classic), climate tools)
- [PeopleForBikes](https://github.com/PeopleForBikes/pfb-network-connectivity) -- Bike network connectivity analysis
- [Worldcon Voting Systems](https://github.com/WorldconVotingSystems/nomnom) -- Hugo Awards nomination and voting platform

See the full list of [dependents on GitHub](https://github.com/mwarkentin/django-watchman/network/dependents).

## 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](https://vmfarms.com/).

## Quickstart

1. Install `django-watchman`:

    ```bash
    pip install django-watchman
    ```

    Or with [uv](https://docs.astral.sh/uv/):

    ```bash
    uv add django-watchman
    ```

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

    ```python
    INSTALLED_APPS = (
        ...
        'watchman',
    )
    ```

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

    ```python
    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:

    ```json
    {
        "databases": [
            {
                "default": {
                    "ok": true
                }
            }
        ],
        "caches": [
            {
                "default": {
                    "ok": true
                }
            }
        ],
        "storage": {"ok": true}
    }
    ```

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

    ```bash
    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](https://django-watchman.readthedocs.io/en/latest/configuration/) for details and examples.

## Contributing

Contributions are welcome! Please see the [contributing guide](https://github.com/mwarkentin/django-watchman/blob/main/CONTRIBUTING.md) for details on how to get started.

## License

BSD-3-Clause
