healthcheck

a very simple Django health check app

• easy to use
• no migration
• no extra dependency. only Django and Python 3.6+

install

pip install git+https://github.com/ahmadly/healthcheck/archive/refs/heads/main.zip

usage

1. add healthcheck to INSTALLED_APPS in settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    
    'healthcheck',

]
    

2. add healthcheck.urls to urlpatterns in urls.py

urlpatterns = [
    ...
    path('health/', include('healthcheck.urls')),
    ...
]

3. setting HEALTHCHECK in settings.py

HEALTH_CHECK_TOKEN = None
HEALTH_CHECK_VIEW = 'healthcheck.views.HealthCheckView'
HEALTH_CHECK_FAIL_STATUS_CODE = 500
HEALTH_CHECK_SUCCESS_STATUS_CODE = 200
HEALTH_CHECK_FORBIDDEN_STATUS_CODE = 403

HEALTH_CHECK = [
    'healthcheck.checks.check_database_connection',
    'healthcheck.checks.check_cache_connection',
    'healthcheck.checks.check_internet_connection',
]

4. run server and go to http://localhost:8000/health/

{
    "uuid": "8f45499108cf4407bd3533d08fe68b26",
    "timestamp": "2023-01-20T16:25:51.374452+00:00",
    "hostname": "Ahmads-MBP",
    "total_checks": 3,
    "failed_checks": 0,
    "results": [
        {
            "check": "healthcheck.checks.check_database_connection",
            "status": true,
            "message": "Database is reachable"
        },
        {
            "check": "healthcheck.checks.check_cache_connection",
            "status": true,
            "message": "Cache is reachable"
        },
        {
            "check": "healthcheck.checks.check_internet_connection",
            "status": true,
            "message": "Internet is reachable"
        }
    ]
}

options

• HEALTH_CHECK_TOKEN is optional, if you want to use token for health check, set it to a string. set Authorization header to Bearer <HEALTH_CHECK_TOKEN> in request header.

• HEALTH_CHECK_VIEW is optional, if you want to use your own view, set it to a string. inherit from healthcheck.views.HealthCheckView

• HEALTH_CHECK_FAIL_STATUS_CODE is optional, if you want to use your own status code for fail, set it to an integer.

• HEALTH_CHECK_SUCCESS_STATUS_CODE is optional, if you want to use your own status code for success, set it to an integer.

• HEALTH_CHECK_FORBIDDEN_STATUS_CODE is optional, if you want to use your own status code for forbidden, set it to an integer.

• HEALTH_CHECK is optional, if you want to use your own checks, set it to a list of strings. each string is a path to a function. the function should return a tuple of two items. the first item is a boolean, the second item is a string. the boolean is the status of the check, the string is the message of the check.

def check_database_connection() -> tuple[bool, str]:
    """
    check must return a tuple of (status, message)
    check must handle exceptions internally
    check must handle timeouts internally
    """

    return True, 'Database is reachable'

contribute

if you have any idea, please open an issue or a pull request.

todo

• add more checks
• add more tests
• add documentation
• add badges
• setup release workflow
• setup pypi.org