Installation

pip install django_healthchecks

Usage

Add the following to your urls.py:

url(r'^healthchecks/', include('django_healthchecks.urls')),

Add a setting with the available healthchecks:

HEALTH_CHECKS = {
    'postgresql': 'django_healthchecks.contrib.check_database',
    'cache_default': 'django_healthchecks.contrib.check_cache_default',
    'solr': 'your_project.lib.healthchecks.check_solr',
}

You can also include healthchecks over http. This is useful when you want to monitor if depending services are up:

HEALTH_CHECKS = {
    ...
    'my_microservice': 'https://my-service.services.internal/healthchecks/',
    ...
}

By default, http health checks will time out after 500ms. You can override this as follows:

HEALTH_CHECKS_HTTP_TIMEOUT = 0.5

By default the status code is always 200, you can change this to something else by using the HEALTH_CHECKS_ERROR_CODE setting:

HEALTH_CHECKS_ERROR_CODE = 503

You can also add some simple protection to your healthchecks via basic auth. This can be specified per check or a wildcard can be used *.

HEALTH_CHECKS_BASIC_AUTH = {
    '*': [('admin', 'pass')],
    'solr': [],
}

Using heartbeats

Heartbeats give a periodic update, to see whether an service was recently active. When the service doesn’t report back within timeout, a healthcheck can be triggered. To use heartbeats, add the application to the INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_healthchecks",
]

Include one of these checks:

HEALTH_CHECKS = {
    ...
    'heartbeats': 'django_healthchecks.contrib.check_heartbeats'
    ...
    'expired_heartbeats': 'django_healthchecks.contrib.check_expired_heartbeats',
    ...
}

Optionally, define an initial timeout:

HEALTHCHECKS_DEFAULT_HEARTBEAT_TIMEOUT = timedelta(days=1)

Let your code track the beats:

from datetime import timedelta
from django_healthchecks.heartbeats import update_heartbeat

update_heartbeat("myservice.name", default_timeout=timedelta(days=2))

Or use the decorator:

from django_healthchecks.heartbeats import update_heartbeat_on_success

@update_heartbeat_on_success("myservice.name", default_timeout=...)
def long_running_task():
    ....

Each time update_heartbeat() is called, the heartbeat is reset. When a heartbeat didn’t receive an update before it’s timeout, the service name be mentioned in the check_expired_heartbeats check.

Releasing

Changes are tracked with changie. Add a changelog entry to every pull request with a user-facing change:

changie new

When entries are merged to the default branch, a release pull request is opened (or updated) automatically. Merging that pull request tags the release, creates the GitHub release and publishes the package to PyPI.