Django HealthCheck

Warnings

• breaking Version 4.x introduced significant changes, particularly affecting custom integrations and the overall API. Review the 'Migration to v4.x' guide in the official documentation when upgrading from versions prior to 4.0.
  Fix: Consult the official migration guide for `django-health-check` when upgrading.
• gotcha Many specific health checks (`health_check.contrib.*`) require additional Python packages to be installed (e.g., `psutil` for disk/memory, `celery` for Celery, `redis` for Redis). Simply adding the contrib app to `INSTALLED_APPS` without the underlying package will cause errors.
  Fix: Install optional dependencies using `pip install django-health-check[extra_package_name]` (e.g., `pip install django-health-check[psutil]`) or install the specific package directly (e.g., `pip install psutil`).
• deprecated The `health_check.contrib.migrations` check, which verified applied database migrations, was removed in version 3.23+.
  Fix: If you relied on this check, you may need to implement a custom check or find an alternative monitoring solution for database migrations.
• gotcha For security, it is highly recommended to protect your health check endpoint, especially in production environments. If using a token-based approach, do NOT use Django's `SECRET_KEY`.
  Fix: Generate a separate, strong secret token for the health check URL (e.g., using `secrets.token_urlsafe()`) and configure your URL accordingly. Ensure HTTPS is enabled.
• gotcha In high-availability environments with load balancers, be aware that checks like disk and memory usage will return responses specific to the individual node selected by the load balancer, not an aggregated status of the entire cluster.
  Fix: Account for node-specific responses in your monitoring strategy or consider aggregate metrics from a dedicated monitoring system.

Install

• pip install django-health-check Install core package
• pip install django-health-check[psutil,celery,redis] Install with common optional dependencies

Imports

• health_check

  INSTALLED_APPS = [
      # ...
      'health_check', # required
      'health_check.db', # database check
      'health_check.cache', # cache check
      'health_check.storage', # storage check
      'health_check.contrib.celery', # optional, for Celery
      'health_check.contrib.psutil', # optional, for disk/memory
      # ...
  ]

  The core app name for django-health-check is 'health_check', not 'django_healthchecks' which is a different library or older package structure.
• include

  from django.urls import include, path
  
  urlpatterns = [
      # ...
      path('health/', include('health_check.urls')), # or any desired path
      # ...
  ]

• plugin_dir.register

  from django.apps import AppConfig
  from health_check.plugins import plugin_dir
  from myapp.checks import MyCustomHealthCheck
  
  class MyAppConfig(AppConfig):
      name = 'myapp'
      def ready(self):
          plugin_dir.register(MyCustomHealthCheck)

  Registering custom health checks, typically in your app's ready() method.

Quickstart

To quickly integrate Django HealthCheck, add the 'health_check' core app and any desired `health_check.contrib.*` plugins to your `INSTALLED_APPS`. Then, include the health check URLs in your project's `urls.py`. Remember to install extra dependencies for specific checks (e.g., `psutil` for disk/memory checks).

# settings.py
INSTALLED_APPS = [
    # ... other Django apps ...
    'health_check',
    'health_check.db', # Checks database connection
    'health_check.cache', # Checks cache backend
    'health_check.storage', # Checks default file storage
    'health_check.contrib.psutil', # Checks disk/memory usage (requires psutil)
    'health_check.contrib.celery', # Checks Celery workers (requires celery)
    # Add more health_check.contrib.* apps as needed for your services
]

# urls.py
from django.urls import include, path

urlpatterns = [
    # ... other url patterns ...
    path('health/', include('health_check.urls')),
]