Skip to main content

Health Check is an application that provides an API to check the health health_check of some parts and some utilities like ping requests. This application can works as standalone or included in a Django project.

Project description


José Antonio Perdiguero López

Health Check is an application that provides an API to check the health status of some parts and some utilities like ping requests. This application can works as standalone or included in a Django project.

This application defines the following terms:


Function that does a quick check or stats gathering and returns a json serializable value, such as dict, list or simple types.


A service or functionality whose status needs to be known.

Said this, providers are grouped by resources. So you can use resource as a simple group, or as a component of your application. E.g: A resource that represents your database with some checks over it, such as simple ping, check if your application tables are created, if it contains data…

Quick start

  1. Install this package using pip:

pip install health-check
  1. (Django) Add PROJECT_PATH to your django settings module.

  2. (Django) Add health_check to your INSTALLED_APPS settings like this:

  1. (Django) Add Health Check urls to your project urls:

urlpatterns = [
    url(r'^health/', include('health_check.urls')),

Check Providers

Health Check provides a mechanism to add new custom check functions through check providers. Each check provider will generate a new API method with an URL that uses the name of the provider. These functions must accept *args and **kwargs and will return a JSON-serializable object through json.dumps() method, for example a ping function:

def ping(*args, **kwargs):
    return {'pong': True}

By default Health Check provides the follow checks:


A ping to application.

URL: /api/health/ping


Check if databases are running.

URL: /api/health/databases


Check if caches are running.

URL: /api/health/caches


Check if celery workers defined in settings are running.

URL: /api/health/celery

Databases stats

Show stats for all databases.

URL: /api/stats/databases

Celery stats

Show celery worker stats.

URL: /api/stats/celery


Source code stats such as current active branch, last commit, if debug is active…

URL: /api/stats/code

Run providers

The main goal of this application is to provide an easy way to run checks over defined resources, so there are different ways to do it.


Health Check provides a command to query current health of a resource. This command can be call as:

health_check {resource} [options]

Call a specific provider from a resource:

health_check {resource} {provider} [options]

To get current status of health checks, and exit with an error if some check is failing:

health_check health -e

Each resource has its own set of options that can be displayed through command help:

health_check -h


To run all providers of a specific resource:

from health_check.providers import Resource

resource = Resource('resource_name')
providers_result = resource()

A single provider can be executed:

from health_check.providers import Provider

provider = Provider('')
provider_result = provider()


Health check adds some useful behavior to your Django application.

Health Check website

A website that shows Health Check data is available in this application. It’s possible access to follow URLs to get a detailed view of your system health status. Those three pages will show results of providers configured (as explained in settings section):

Health Check API

Health Check API can be used as a standalone application including only their urls:

urlpatterns = [
    url(r'^health/', include('health.api.urls')),

This API have a single url for each provider, that are grouped by resources. Each provider can be queried alone, returning his current health status:


Also there is a resource view that will return the health status of all providers:


For last, there is a root view that will return the health status of all providers from all resources:


Django management commands

Previous command can be used as Django management command:

python health_check {resource} {provider} [options]


Health check settings can be added directly to Django settings module or create an specific module for them. If a custom module (or class) is used, you must specify it through HEALTH_CHECK_SETTINGS environment variable.

To use a custom module for settings is necessary to specify the full path: project.package.settings. The same applies to objects: project.package.settings:SettingsObject.


List of additional check providers. Each provider consists in a tuple of name, function complete path, args and kwargs.


health_check_providers = {
    'resource': (
        ('test', 'application.module.test_function', [1, 2], {'foo': 'bar'}),


providers = getattr(settings, 'health_check_providers', {
    'health': (
        ('ping', '', None, None),
        ('databases', '', None, None),
        ('caches', '', None, None),
    'stats': (
        ('databases', 'health_check.providers.django.stats.databases', None, None),
        ('code', 'health_check.providers.stats.code', None, None),


List of hostname from celery workers to be checked. If any worker is defined, two additional providers listed previously will be added to default set.


health_check_celery_workers = ()

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

health-check-3.4.1.tar.gz (892.3 kB view hashes)

Uploaded Source

Built Distribution

health_check-3.4.1-py2.py3-none-any.whl (905.3 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page