Docker Container Health Monitoring with Python: Status, Logs & Cleanup (2026)

Docker containers make deployment easy, but monitoring dozens or hundreds of containers across multiple hosts introduces new challenges. Containers crash silently, health checks fail without alerts, images pile up consuming disk space, and resource limits get exceeded. You need visibility into container health without relying solely on orchestration platforms.

dargslan-docker-health provides lightweight Docker monitoring that works from the command line and Python scripts — perfect for single-host Docker setups, dev environments, and CI/CD pipelines.

Installing dargslan-docker-health

pip install dargslan-docker-health

# Or install the complete 15-tool toolkit
pip install dargslan-toolkit

CLI Usage

# Full health report
dargslan-docker-health report

# List all containers with status
dargslan-docker-health list

# Find unhealthy/restarting containers
dargslan-docker-health unhealthy

# Resource usage statistics
dargslan-docker-health stats

# Image management info
dargslan-docker-health images

# Find dangling images
dargslan-docker-health dangling

# JSON output
dargslan-docker-health json

Python API

from dargslan_docker_health import DockerHealth

dh = DockerHealth()

# Full report
dh.print_report()

# List all containers
containers = dh.list_containers()
for c in containers:
    print(f"  [{c['status']:10s}] {c['name']:30s} {c['image']}")

# Find unhealthy containers
unhealthy = dh.get_unhealthy()
if unhealthy:
    print(f"WARNING: {len(unhealthy)} unhealthy containers!")
    for c in unhealthy:
        print(f"  {c['name']}: {c['status']} ({c.get('health_status', 'unknown')})")

# Resource usage
stats = dh.container_stats()
for s in stats:
    print(f"  {s['name']:30s} CPU: {s['cpu_percent']:5.1f}%  MEM: {s['mem_usage_human']}")

# Image analysis
images = dh.list_images()
dangling = dh.dangling_images()
print(f"Images: {len(images)}, Dangling: {len(dangling)}")

total_size = sum(i['size'] for i in dangling)
print(f"Reclaimable: {total_size / 1024**3:.1f} GB")

Docker Health Checks

Dockerfile HEALTHCHECK

# HTTP health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

# TCP port check
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD nc -z localhost 3000 || exit 1

# Process check
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD pgrep -f "my-process" || exit 1

# Custom script
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD /usr/local/bin/health-check.sh

Docker Compose Health Check

services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

Essential Docker Commands

# Container management
docker ps -a                         # All containers
docker ps --filter status=exited     # Stopped containers
docker ps --filter health=unhealthy  # Unhealthy containers
docker inspect            # Full details
docker logs  --tail 100   # Last 100 log lines
docker logs  -f           # Follow logs

# Resource monitoring
docker stats --no-stream             # One-time stats
docker top                # Process list

# System management
docker system df                     # Disk usage breakdown
docker system prune -a               # Remove all unused data
docker image prune                   # Remove dangling images
docker volume prune                  # Remove unused volumes
docker network prune                 # Remove unused networks

# Container lifecycle
docker restart 
docker stop 
docker start 
docker kill               # Force stop

Common Docker Issues

1. Container Restart Loops

# Check exit code and logs
docker inspect --format='{{.State.ExitCode}}' 
docker logs  --tail 50

# Common causes:
# - Exit code 137: OOM killed (increase memory limit)
# - Exit code 1: Application error (check logs)
# - Exit code 126: Permission denied on entrypoint
# - Exit code 127: Command not found

2. Disk Space Issues

# Check Docker disk usage
docker system df -v

# Clean up everything
docker system prune -a --volumes

# Remove old images
docker images --filter "dangling=true" -q | xargs docker rmi

# Configure log rotation
# /etc/docker/daemon.json
{
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "10m",
        "max-file": "3"
    }
}

3. Resource Limits

# Set memory and CPU limits
docker run -d --name app \
  --memory=512m \
  --memory-swap=1g \
  --cpus=1.5 \
  myapp:latest

# Docker Compose limits
services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.5'
        reservations:
          memory: 256M
          cpus: '0.5'

Automated Docker Monitoring

#!/usr/bin/env python3
# /opt/scripts/docker-check.py
from dargslan_docker_health import DockerHealth

dh = DockerHealth()

# Check for unhealthy containers
unhealthy = dh.get_unhealthy()
if unhealthy:
    print(f"DOCKER ALERT: {len(unhealthy)} unhealthy containers!")
    for c in unhealthy:
        print(f"  {c['name']}: {c['status']}")

# Check resource usage
for s in dh.container_stats():
    if s['cpu_percent'] > 80:
        print(f"CPU WARNING: {s['name']} at {s['cpu_percent']:.0f}%")
    if s['mem_percent'] > 85:
        print(f"MEM WARNING: {s['name']} at {s['mem_percent']:.0f}%")

# Check for dangling images
dangling = dh.dangling_images()
if len(dangling) > 10:
    total = sum(i['size'] for i in dangling) / 1024**3
    print(f"CLEANUP: {len(dangling)} dangling images ({total:.1f} GB)")

Docker container monitoring closes the gap between "containers are running" and "containers are healthy." dargslan-docker-health gives you instant visibility into container status, resource usage, and image management — all from the command line.

Install now: pip install dargslan-docker-health — or get all 15 tools: pip install dargslan-toolkit

Download our free Docker Health Checker Cheat Sheet for quick reference.