Skip to content

API Reference

This is the auto-generated reference for django-watchman's Python API. For a higher-level overview see the Getting Started guide and the Configuration page.

Views

The Django views that power watchman's HTTP endpoints.

watchman.views

Django views that expose watchman health-check endpoints.

The three main endpoints are:

  • status -- JSON response with the results of all configured checks.
  • dashboard -- HTML page summarising check results.
  • ping -- Lightweight pong response for simple uptime monitoring.

status(request)

Return JSON health-check results for all configured checks.

Protected by the configured WATCHMAN_AUTH_DECORATOR.

Example response:

{
    "caches": [{"default": {"ok": true}}],
    "databases": [{"default": {"ok": true}}],
    "storage": {"ok": true}
}
Query parameters

check: Run only the specified checks (repeatable). skip: Skip the specified checks (repeatable).

bare_status(request)

Return an empty text/plain response whose status code reflects overall health.

Unlike status, this view has no auth decorator and returns no body -- only the HTTP status code matters. Useful for load-balancer health checks that only inspect the status code.

ping(request)

Return a plain-text pong response.

This is the simplest possible liveness probe -- it does not run any backing-service checks. Useful for Kubernetes liveness probes or simple uptime pings.

dashboard(request)

Render an HTML dashboard showing the status of all configured checks.

Protected by the configured WATCHMAN_AUTH_DECORATOR.

Query parameters

check: Run only the specified checks (repeatable). skip: Skip the specified checks (repeatable).

run_checks(request)

Execute all configured health checks and return the aggregated results.

Reads check and skip query parameters from request to allow callers to filter which checks are executed.

Returns:

Type Description
dict[str, Any]

A (checks, ok) tuple where checks is a dictionary of check
bool

results and ok is False when any check reported an error
tuple[dict[str, Any], bool]

(and WATCHMAN_ERROR_CODE
tuple[dict[str, Any], bool]

is not 200).

Checks

Built-in health-check functions for Django backing services. Each function can be referenced by its dotted path in WATCHMAN_CHECKS.

watchman.checks

Built-in health check functions for Django backing services.

Each public function (e.g. caches, databases, email, storage) returns a dictionary suitable for inclusion in the watchman JSON response. They can be referenced by their dotted Python path in the WATCHMAN_CHECKS setting.

caches()

Check all configured caches by writing, reading, and deleting a key.

Iterates over every cache defined in WATCHMAN_CACHES (defaults to Django's CACHES setting).

Returns:

Type Description
dict[str, list[CheckResult]]

A dictionary of the form:

{"caches": [{"default": {"ok": True}}, ...]}
Source code in watchman/checks.py 
87
88
89
90
91
92
93
94
95
96
97
98
99
def caches() -> dict[str, list[CheckResult]]:
    """Check all configured caches by writing, reading, and deleting a key.

    Iterates over every cache defined in
    [`WATCHMAN_CACHES`][watchman.settings.WATCHMAN_CACHES] (defaults to
    Django's `CACHES` setting).

    Returns:
        A dictionary of the form:

            {"caches": [{"default": {"ok": True}}, ...]}
    """
    return {"caches": _check_caches(watchman_settings.WATCHMAN_CACHES)}

databases()

Check all configured databases by executing a SELECT 1 query.

Iterates over every database defined in WATCHMAN_DATABASES (defaults to Django's DATABASES setting).

Returns:

Type Description
dict[str, list[CheckResult]]

A dictionary of the form:

{"databases": [{"default": {"ok": True}}, ...]}
Source code in watchman/checks.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
def databases() -> dict[str, list[CheckResult]]:
    """Check all configured databases by executing a ``SELECT 1`` query.

    Iterates over every database defined in
    [`WATCHMAN_DATABASES`][watchman.settings.WATCHMAN_DATABASES] (defaults to
    Django's `DATABASES` setting).

    Returns:
        A dictionary of the form:

            {"databases": [{"default": {"ok": True}}, ...]}
    """
    return {"databases": _check_databases(watchman_settings.WATCHMAN_DATABASES)}

email()

Check the email backend by sending a test message.

Only included when WATCHMAN_ENABLE_PAID_CHECKS is True or when explicitly listed in WATCHMAN_CHECKS.

Returns:

Type Description
dict[str, CheckResult]

A dictionary of the form:

{"email": {"ok": True}}
Source code in watchman/checks.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def email() -> dict[str, CheckResult]:
    """Check the email backend by sending a test message.

    Only included when
    [`WATCHMAN_ENABLE_PAID_CHECKS`][watchman.settings.WATCHMAN_ENABLE_PAID_CHECKS]
    is ``True`` or when explicitly listed in
    [`WATCHMAN_CHECKS`][watchman.settings.WATCHMAN_CHECKS].

    Returns:
        A dictionary of the form:

            {"email": {"ok": True}}
    """
    return {"email": _check_email()}

storage()

Check the default file storage backend.

Creates a temporary file, reads it back, and deletes it using Django's default storage.

Returns:

Type Description
dict[str, CheckResult]

A dictionary of the form:

{"storage": {"ok": True}}
Source code in watchman/checks.py 
133
134
135
136
137
138
139
140
141
142
143
144
def storage() -> dict[str, CheckResult]:
    """Check the default file storage backend.

    Creates a temporary file, reads it back, and deletes it using Django's
    default storage.

    Returns:
        A dictionary of the form:

            {"storage": {"ok": True}}
    """
    return {"storage": _check_storage()}

Settings

All settings are read from your Django settings module with sensible defaults. See the Configuration guide for usage details.

watchman.settings

Resolved watchman settings with their defaults.

All settings are read from your Django settings module via getattr with sensible defaults. See the Configuration guide for full usage details.

WATCHMAN_ENABLE_PAID_CHECKS = getattr(settings, 'WATCHMAN_ENABLE_PAID_CHECKS', False) module-attribute

Include paid checks (e.g. email) in the default check list. Default: False.

WATCHMAN_AUTH_DECORATOR = getattr(settings, 'WATCHMAN_AUTH_DECORATOR', 'watchman.decorators.token_required') module-attribute

Dotted path to a decorator applied to protected views. Set to None to disable authentication. Default: "watchman.decorators.token_required".

WATCHMAN_TOKENS = getattr(settings, 'WATCHMAN_TOKENS', None) module-attribute

Comma-separated list of accepted authentication tokens. Default: None (no token required).

WATCHMAN_TOKEN_NAME = getattr(settings, 'WATCHMAN_TOKEN_NAME', 'watchman-token') module-attribute

Name of the query-string parameter used to pass the token. Default: "watchman-token".

WATCHMAN_ERROR_CODE = getattr(settings, 'WATCHMAN_ERROR_CODE', 500) module-attribute

HTTP status code returned when a check fails. Default: 500.

WATCHMAN_EMAIL_SENDER = getattr(settings, 'WATCHMAN_EMAIL_SENDER', 'watchman@example.com') module-attribute

From address for the email check. Default: "watchman@example.com".

WATCHMAN_EMAIL_RECIPIENTS = getattr(settings, 'WATCHMAN_EMAIL_RECIPIENTS', ['to@example.com']) module-attribute

List of To addresses for the email check. Default: ["to@example.com"].

WATCHMAN_EMAIL_HEADERS = getattr(settings, 'WATCHMAN_EMAIL_HEADERS', {}) module-attribute

Extra headers added to the test email. Default: {}.

WATCHMAN_CACHES = getattr(settings, 'WATCHMAN_CACHES', settings.CACHES) module-attribute

Cache aliases to check. Defaults to Django's CACHES setting.

WATCHMAN_DATABASES = getattr(settings, 'WATCHMAN_DATABASES', settings.DATABASES) module-attribute

Database aliases to check. Defaults to Django's DATABASES setting.

WATCHMAN_DISABLE_APM = getattr(settings, 'WATCHMAN_DISABLE_APM', False) module-attribute

Suppress APM tracing (New Relic, Datadog) for watchman views. Default: False.

WATCHMAN_STORAGE_PATH = getattr(settings, 'WATCHMAN_STORAGE_PATH', settings.MEDIA_ROOT) module-attribute

Subdirectory within the default storage backend used for the storage check. Defaults to MEDIA_ROOT.

WATCHMAN_CHECKS = getattr(settings, 'WATCHMAN_CHECKS', _checks) module-attribute

Tuple of dotted paths to check functions that watchman will execute. Defaults to DEFAULT_CHECKS (plus PAID_CHECKS when WATCHMAN_ENABLE_PAID_CHECKS is True).

EXPOSE_WATCHMAN_VERSION = getattr(settings, 'EXPOSE_WATCHMAN_VERSION', False) module-attribute

Add an X-Watchman-Version header to responses. Default: False.

URLs

Include these in your root URL configuration with url(r'^watchman/', include('watchman.urls')).

URL pattern View Name
/ status status
/dashboard/ dashboard dashboard
/ping/ ping ping

Constants

watchman.constants

Default check tuples used to populate WATCHMAN_CHECKS.

DEFAULT_CHECKS = ('watchman.checks.caches', 'watchman.checks.databases', 'watchman.checks.storage') module-attribute

Checks included by default: caches, databases, and storage.

PAID_CHECKS = ('watchman.checks.email',) module-attribute

Checks that may incur cost (e.g. sending an email). Only included when WATCHMAN_ENABLE_PAID_CHECKS is True.

Decorators

watchman.decorators

Decorators used to protect and wrap watchman views and checks.

check(func)

Decorator that wraps a check function and converts exceptions into error results.

If the wrapped function raises, the exception is caught and returned as a CheckStatus with ok=False, the error message, and a stacktrace.

parse_auth_header(auth_header)

Parse the Authorization header and return the token value.

Expected format: WATCHMAN-TOKEN Token="ABC123"

Raises :exc:KeyError when no Token parameter is found.

token_required(view_func)

Decorator that enforces token-based authentication on a view.

When WATCHMAN_TOKENS is set, the request must supply a matching token via the Authorization header or a query parameter named by WATCHMAN_TOKEN_NAME.

Returns an HTTP 403 response when the token is missing or invalid.

auth(view_func)

Utils

watchman.utils

Utility helpers used internally by watchman checks and views.

get_cache(cache_name)

Return the Django cache backend for cache_name.

Source code in watchman/utils.py 
13
14
15
def get_cache(cache_name: str) -> BaseCache:
    """Return the Django cache backend for *cache_name*."""
    return django_cache.caches[cache_name]

get_checks(check_list=None, skip_list=None)

Yield callable check functions from WATCHMAN_CHECKS.

Parameters:

Name Type Description Default
check_list list[str] | None

If provided, only checks whose dotted path is in this list are yielded.

 None
skip_list list[str] | None

If provided, checks whose dotted path is in this list are excluded.

 None

Yields:

Type Description
Generator[Any]

Callable check functions resolved via import_string.
Source code in watchman/utils.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def get_checks(
    check_list: list[str] | None = None,
    skip_list: list[str] | None = None,
) -> Generator[Any]:
    """Yield callable check functions from [`WATCHMAN_CHECKS`][watchman.settings.WATCHMAN_CHECKS].

    Args:
        check_list: If provided, only checks whose dotted path is in this list
            are yielded.
        skip_list: If provided, checks whose dotted path is in this list are
            excluded.

    Yields:
        Callable check functions resolved via `import_string`.
    """
    if isinstance(WATCHMAN_CHECKS, str):
        raise TypeError(
            "WATCHMAN_CHECKS should be a list or tuple of dotted paths, not a "
            "string. If you have a single check, use a list: "
            "WATCHMAN_CHECKS = ['module.path.to.callable'] "
            "or a tuple with a trailing comma: "
            "WATCHMAN_CHECKS = ('module.path.to.callable',)"
        )

    checks_to_run = frozenset(WATCHMAN_CHECKS)

    if check_list is not None:
        checks_to_run = checks_to_run.intersection(check_list)
    if skip_list is not None:
        checks_to_run = checks_to_run.difference(skip_list)

    for python_path in checks_to_run:
        yield import_string(python_path)