Health Check Module
Django-CFG includes a health check system that provides monitoring of your application’s critical components including databases, cache, system resources, and configuration status.
Features
- Database Connectivity - Multi-database connection monitoring with response times
- Cache Availability - Redis and cache backend testing
- System Resources - CPU, memory, disk usage monitoring (requires
psutil) - Configuration Validation - Django-CFG configuration status
Quick Start
Add Health Check URLs
# urls.py
from django.urls import path
from django_cfg.modules.django_health.service import HealthCheckView, SimpleHealthView
urlpatterns = [
path('health/', HealthCheckView.as_view(), name='health_check'),
path('health/simple/', SimpleHealthView.as_view(), name='simple_health'),
]
# Or use the built-in URL patterns
from django_cfg.modules.django_health.service import get_health_urls
urlpatterns += get_health_urls()Import views from django_cfg.modules.django_health.service, not from the module root. The module __init__.py only exports the DjangoHealth service class.
Response Format
GET /health/ - Comprehensive health check:
{
"status": "healthy",
"timestamp": "2025-01-15T10:30:00.123456",
"checks": {
"database": {
"status": "healthy",
"databases": {
"default": {
"status": "healthy",
"response_time_ms": 2.34,
"engine": "django.db.backends.postgresql"
}
}
},
"cache": {
"status": "healthy",
"response_time_ms": 0.45,
"backend": "django_redis.cache.RedisCache"
},
"system": {
"status": "healthy",
"cpu": {
"usage_percent": 45.2,
"status": "healthy"
},
"memory": {
"usage_percent": 62.8,
"total_gb": 16.0,
"available_gb": 5.95,
"status": "healthy"
},
"disk": {
"usage_percent": 78.1,
"total_gb": 500.0,
"free_gb": 109.5,
"status": "healthy"
},
"load_average": {
"1min": 1.23,
"5min": 1.45,
"15min": 1.67
}
},
"configuration": {
"status": "healthy",
"django_cfg": {
"version": "1.3.13",
"debug": false,
"environment": "production",
"project_name": "My Project"
}
}
}
}GET /health/simple/ - Simple OK response:
{
"status": "ok",
"timestamp": "2025-01-15T10:30:00.123456"
}Status Values
The health check returns one of three statuses:
| Status | Description |
|---|---|
healthy | All checks passed |
degraded | Some checks have warnings (e.g., high CPU) |
unhealthy | At least one check failed |
Component Thresholds
System resource thresholds that trigger warnings:
| Resource | Warning Threshold |
|---|---|
| CPU | > 80% |
| Memory | > 80% |
| Disk | > 80% |
Views Reference
HealthCheckView
Comprehensive health check that validates:
- Database - Tests connection to all configured databases with
SELECT 1 - Cache - Tests cache read/write operations
- System - CPU, memory, disk usage (requires
psutil) - Configuration - Django-CFG settings validation
from django_cfg.modules.django_health.service import HealthCheckView
# Add to URLconf
path('health/', HealthCheckView.as_view(), name='health_check'),SimpleHealthView
Lightweight health check that just returns OK. Useful for load balancer probes.
from django_cfg.modules.django_health.service import SimpleHealthView
path('health/simple/', SimpleHealthView.as_view(), name='simple_health'),get_health_urls()
Convenience function to get all health check URL patterns:
from django_cfg.modules.django_health.service import get_health_urls
# Returns URL patterns for:
# - /health/ -> HealthCheckView
# - /health/simple/ -> SimpleHealthView
urlpatterns += get_health_urls()Extending Health Checks
Create a custom view by subclassing HealthCheckView:
from django_cfg.modules.django_health.service import HealthCheckView
from django.http import JsonResponse
class CustomHealthView(HealthCheckView):
"""Custom health check with additional checks"""
def get(self, request):
# Get base health data
response = super().get(request)
health_data = response.json() if hasattr(response, 'json') else {}
# Add custom checks
health_data["checks"]["custom_service"] = self._check_custom_service()
return JsonResponse(health_data)
def _check_custom_service(self):
"""Check external service"""
try:
import requests
response = requests.get('https://api.example.com/health', timeout=5)
return {
"status": "healthy" if response.ok else "error",
"response_time_ms": response.elapsed.total_seconds() * 1000
}
except Exception as e:
return {"status": "error", "error": str(e)}Docker/Kubernetes Integration
Use the simple health endpoint for container probes:
# docker-compose.yml
services:
web:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health/simple/"]
interval: 30s
timeout: 10s
retries: 3# kubernetes deployment
livenessProbe:
httpGet:
path: /health/simple/
port: 8000
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /health/
port: 8000
initialDelaySeconds: 5
periodSeconds: 5Testing
from django.test import TestCase, Client
class HealthCheckTest(TestCase):
def setUp(self):
self.client = Client()
def test_health_check_returns_200(self):
"""Test health check endpoint returns 200"""
response = self.client.get('/health/')
self.assertEqual(response.status_code, 200)
data = response.json()
self.assertIn('status', data)
self.assertIn('checks', data)
self.assertIn('database', data['checks'])
def test_simple_health_check(self):
"""Test simple health endpoint"""
response = self.client.get('/health/simple/')
self.assertEqual(response.status_code, 200)
data = response.json()
self.assertEqual(data['status'], 'ok')Related Documentation
- Configuration Guide - DjangoConfig setup
- Deployment Guide - Docker health checks
Last updated on
Django-CFG