Skip to main content

django-alive 🕺

tests coverage PyPI Python Versions

Provides two healthcheck endpoints for your Django application:

Alive

Verifies the WSGI server is responding.

  • Default URL: /-/alive/
  • Success:
    • status code: 200
    • content: ok
  • Failure: This view never returns a failure. A failure would mean your WSGI server is not running.

Health

Verifies services are ready.

  • Default URL: /-/health/
  • Success:
    • status_code: 200
    • content: {"healthy": true}
  • Failure:
    • status_code: 503
    • content: {"healthy": false, "errors": ["error 1", "error 2"]}

By default the health endpoint will test the database connection, but can be configured to check the cache, staticfiles, or any additional custom checks.

Supports Django 1.10+ on both Python 2 & 3.

Install

pip install django-alive

Configure

Add this to your project's urlpatterns:

path("-/", include("django_alive.urls"))

For versions before Django 2.0, use:

url(r"-/", include("django_alive.urls"))

If you wish to use the healthcheck management command, add django_alive to the INSTALLED_APPS.

Enabling Checks

The default "health" endpoint will test a simple SELECT 1 query on the database. Additional checks can be enabled in your Django settings.

Use the ALIVE_CHECKS setting to configure the checks to include. It is a dictionary with the path to a Python function as a key and any keyword arguments to pass to that function as a value. A full example:

ALIVE_CHECKS = {
    "django_alive.checks.check_database": {},
    "django_alive.checks.check_staticfile": {
        "filename": "img/favicon.ico",
    },
    "django_alive.checks.check_cache": {
        "cache": "session",
        "key": "test123",
    },
    "django_alive.checks.check_migrations": {},
}

Built-in Checks

Defined in django_alive.checks.

def check_cache(key="django-alive", cache="default")

Fetch a cache key against the specified cache.

Parameters:

  • key (str): Cache key to fetch (does not need to exist)
  • cache (str): Cache alias to execute against

def check_database(query="SELECT 1", database="default")

Run a SQL query against the specified database.

Parameters:

  • query (str): SQL to execute
  • database (str): Database alias to execute against

def check_migrations(alias=None)

Verify all defined migrations have been applied

Parameters:

  • alias (str): An optional database alias (default: check all defined databases)

def check_staticfile(filename)

Verify a static file is reachable

Parameters:

  • filename (str): static file to verify

Management Command

In addition to the view, the configured healthchecks can also be run via a management command with manage.py healthcheck. This will exit with an error code if all the healthchecks do not pass.

Custom Checks

django-alive is designed to easily extend with your own custom checks. Simply define a function which performs your check and raises a django_alive.HealthcheckFailure exception in the event of a failure. See checks.py for some examples on how to write a check.

Disabling ALLOWED_HOSTS for Healthchecks

Often, load balancers will not pass a Host header when probing a healthcheck endpoint. This presents a problem for Django's host header validation. A middleware is included that will turn off the host checking only for the healthcheck endpoints. This is safe since these views never do anything with the Host header.

Enable the middleware by inserting this at the beginning of your MIDDLEWARE:

MIDDLEWARE = [
    "django_alive.middleware.healthcheck_bypass_host_check",
    # ...
]

Handling SECURE_SSL_REDIRECT

If your load balancer is doing HTTPS termination and you have SECURE_SSL_REDIRECT=True in your settings, you want to make sure that your healtcheck URLs are not also redirected to HTTPS. In that case, add the following to your settings:

SECURE_REDIRECT_EXEMPT = [r"^-/"]  # django-alive URLs

1.2.0 (2021-07-23)

  • Updated test matrix. Python 2 no longer "officially" supported.
  • Prevent Traceback in middleware if URLs are not setup

1.1.0 (2019-11-06)

  • Added healthcheck management command
  • Added optional check_migrations healthcheck

1.0.1 (2018-09-10)

  • Documentation improvements
  • Python 3.7 support

1.0.0 (2018-08-21)

  • Initial release

Metadata

Release files for django-alive 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-alive 1.2.0
File Size Uploaded Provenance Actions
django-alive-1.2.0.tar.gz 10.0 kB Without provenance Details for django-alive-1.2.0.tar.gz

Release files / django-alive-1.2.0.tar.gz

Download URL django-alive-1.2.0.tar.gz
Size 10.0 kB
Tags Source
SHA-256 checksum
How to use checksums
51ac1fd6cd9b7e81721b9cd1a754d499ebebb48872ad91ca91812b75adf46f2c
BLAKE2b-256 checksum
How to use checksums
61d5957aeb9d715c40cb184440e41fa7fe58cd9d14f131759c52af866e7edd3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.2

Security for django-alive 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page