📊 Monitoring Guide

Django-CFG provides built-in monitoring and logging capabilities that work seamlessly in both development and production environments.

Core Principles

Zero-Configuration Monitoring

Health checks work out of the box
System metrics automatically collected
Database monitoring for all configured databases
Smart logging with automatic level adjustment

Environment-Aware

Development: Verbose logging, detailed errors
Production: Structured logs, error tracking
Docker: Container-aware resource monitoring

Health Check Endpoints

Django-CFG includes built-in health check endpoints for monitoring service status.

Simple Health Check

Basic liveness probe for container orchestration:


GET /health/simple/

Response:


{
  "status": "ok",
  "timestamp": "2025-10-14T12:34:56.789Z"
}

Use cases:

Docker health checks
Kubernetes liveness probes
Load balancer health monitoring

Comprehensive Health Check

Detailed system status with metrics:


GET /health/

Response:


{
  "status": "healthy",
  "timestamp": "2025-10-14T12:34:56.789Z",
  "checks": {
    "database": {
      "status": "healthy",
      "databases": {
        "default": {
          "status": "healthy",
          "response_time_ms": 2.45,
          "engine": "django.db.backends.postgresql"
        }
      }
    },
    "cache": {
      "status": "healthy",
      "response_time_ms": 0.89,
      "backend": "django_redis.cache.RedisCache"
    },
    "system": {
      "status": "healthy",
      "cpu": {
        "usage_percent": 15.2,
        "status": "healthy"
      },
      "memory": {
        "usage_percent": 45.6,
        "total_gb": 16.0,
        "available_gb": 8.7,
        "status": "healthy"
      },
      "disk": {
        "usage_percent": 62.3,
        "total_gb": 500.0,
        "free_gb": 188.5,
        "status": "healthy"
      }
    },
    "configuration": {
      "status": "healthy",
      "django_cfg": {
        "version": "1.3.13",
        "debug": false,
        "environment": "production"
      }
    }
  }
}

Monitored components:

✅ Database connectivity and response times
✅ Cache availability and performance
✅ CPU, memory, disk usage
✅ System uptime and load average
✅ Configuration validation

System Monitoring

Django-CFG includes a system monitor that tracks real-time metrics.

Available Metrics

CPU Metrics:

Usage percentage
Core count (physical and logical)
Load average (1min, 5min, 15min)

Memory Metrics:

Usage percentage
Total, used, available memory
Memory breakdown by category

Disk Metrics:

Disk usage percentage
Total, used, free space
I/O statistics

Database Status:

Connection health per database
Response time tracking
Error detection

User Statistics:

Total users
Active users (30-day window)
Staff and superuser counts

Admin Dashboard Integration

The system monitor integrates with Django Admin (Unfold):


# Automatic integration - no configuration needed
# Access via Django Admin dashboard
 
# Real-time metrics displayed:
# - CPU usage graphs
# - Memory consumption
# - Database connection status
# - Active user statistics

Logging System

Django-CFG includes a built-in logging module that works out of the box.

Zero-Configuration Logging

Logging is automatically configured based on environment:

Development:

Console output with colors
DEBUG level messages
Rich tracebacks for errors

Production:

File logging with rotation
WARNING level and above
Structured log format

Basic Usage


from django_cfg.modules.django_logging import logger
 
# Standard logging methods
logger.info("User logged in")
logger.warning("Cache miss")
logger.error("Connection failed")
logger.success("Deployment complete")

That’s it! No configuration needed—the module handles everything automatically.

For detailed logging configuration, see Logging Configuration →

Docker Health Checks

Django-CFG health checks work seamlessly with Docker.

Docker Compose Configuration


services:
  django:
    image: your-django-app
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health/simple/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Kubernetes Probes


apiVersion: v1
kind: Pod
spec:
  containers:
  - name: django
    image: your-django-app
    livenessProbe:
      httpGet:
        path: /health/simple/
        port: 8000
      initialDelaySeconds: 30
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /health/
        port: 8000
      initialDelaySeconds: 10
      periodSeconds: 5

Production Monitoring Best Practices

1. External Monitoring

Integrate with external monitoring services:

Uptime Monitoring:

UptimeRobot
Pingdom
StatusCake

Configure to check /health/simple/ endpoint every 1-5 minutes.

Error Tracking:


# Add Sentry integration (optional)
# Django-CFG logging integrates with Sentry handlers
 
INSTALLED_APPS += ['sentry_sdk']
 
import sentry_sdk
sentry_sdk.init(
    dsn="your-sentry-dsn",
    environment="production",
)

2. Log Aggregation

Send logs to centralized service:

ELK Stack (Elasticsearch, Logstash, Kibana)
Datadog - Application monitoring
CloudWatch - AWS logging
Grafana Loki - Log aggregation

3. Alerting Rules

Set up alerts for:


# Example alerting thresholds
cpu_usage: > 80%
memory_usage: > 85%
disk_usage: > 90%
database_response_time: > 1000ms
error_rate: > 10 errors/minute

4. Metrics Export

Export metrics to monitoring systems:


# Prometheus metrics endpoint (optional)
# Django-CFG metrics can be exported via django-prometheus
 
INSTALLED_APPS += ['django_prometheus']
 
# Metrics available at /metrics/

Monitoring Checklist

Before deploying to production:

Health Checks

/health/simple/ endpoint returns 200 OK
/health/ shows all systems healthy
Database connectivity verified
Cache availability verified

Logging

Log directory exists and is writable
Log rotation configured (10MB files)
Error logs separated from info logs
Log level set to WARNING or higher

External Monitoring

Uptime monitoring configured
Error tracking service integrated
Log aggregation set up
Alert rules configured

Resource Monitoring

CPU usage tracking enabled
Memory monitoring active
Disk space alerts configured
Database performance tracked

Troubleshooting

Health Check Returns “unhealthy”

Check database connectivity:


# Test database connection
python manage.py dbshell
 
# Check database logs
docker logs postgres_container

Check cache connectivity:


# Test Redis connection
redis-cli ping
 
# Check cache configuration
python manage.py shell -c "from django.core.cache import cache; print(cache.get('test'))"

High Resource Usage Warnings

CPU usage > 90%:

Check for infinite loops
Review ReArq worker count
Optimize database queries
Enable query caching

Memory usage > 85%:

Check for memory leaks
Review queryset evaluation
Optimize image processing
Reduce worker memory limit

Disk usage > 90%:

Clean up old log files
Remove unused media files
Set up log rotation
Archive old backups

Logs Not Writing

Check permissions:


# Ensure log directory is writable
chmod 755 logs/
chown -R django-user:django-user logs/

Check disk space:


# Verify available disk space
df -h /path/to/logs

Check configuration:


# Verify logging config in settings
print(settings.LOGGING)