Docker Compose Debugging Guide

Effective debugging is essential for maintaining containerized applications. This guide covers various debugging techniques for Docker Compose.

Basic Debugging Configuration

services:
  app:
    image: myapp:latest
    environment:
      - DEBUG=1
      - LOG_LEVEL=debug
      - ${DEBUG_ENV:-DEBUG}=true
    volumes:
      - ./debug:/debug
    cap_add:
      - SYS_PTRACE
    labels:
      - "com.example.debug=true"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Docker Compose 3.x Features

Extended Debugging Configuration

services:
  app:
    environment:
      DEBUG: ${DEBUG_LEVEL:-info}
      LOG_FORMAT: ${LOG_FORMAT:-json}
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M

Conditional Debugging

services:
  app:
    environment:
      - DEBUG=${DEBUG_ENABLED:-false}
      - LOG_LEVEL=${LOG_LEVEL:-info}
    profiles:
      - debug

Debug Templates

services:
  app:
    environment:
      DEBUG_${SERVICE_NAME:-app}: true
      LOG_${SERVICE_NAME:-app}: debug

Debugging Tools and Techniques

Log Inspection

# Follow logs
docker compose logs -f

# View specific service
docker compose logs app

# Filter logs
docker compose logs | grep "error"

# View structured logs
docker compose logs --format json

Container Access

# Access container shell
docker compose exec app sh

# Run debug commands
docker compose exec app ps aux

# Debug with custom tools
docker compose exec app strace -p 1

Network Debugging

# Check network connectivity
docker compose exec app ping db

# Test ports
docker compose exec app nc -zv localhost 8080

# Network traffic analysis
docker compose exec app tcpdump -i eth0

Common Debugging Patterns

1. Service Inspection

# Check service status
docker compose ps

# Inspect service details
docker compose inspect app

# View service logs
docker compose logs app

# Check service health
docker compose ps --format json

2. Resource Monitoring

# Monitor resource usage
docker stats

# Check container processes
docker compose top

# Monitor system metrics
docker compose exec app top

3. Network Troubleshooting

# List networks
docker network ls

# Inspect network
docker network inspect app_default

# Network diagnostics
docker compose exec app netstat -tulpn

Docker Swarm Mode Considerations

Service Debugging

services:
  app:
    deploy:
      mode: replicated
      replicas: 3
      update_config:
        failure_action: rollback
      restart_policy:
        condition: on-failure

Distributed Debugging

services:
  app:
    deploy:
      placement:
        constraints:
          - node.role == manager
      resources:
        limits:
          cpus: '0.50'
          memory: 512M

Service Discovery

services:
  app:
    deploy:
      endpoint_mode: dnsrr
      update_config:
        order: start-first

Best Practices

Logging
- Use appropriate log levels
- Implement structured logging
- Configure log rotation
- Use log aggregation
- Implement log correlation
Monitoring
- Set up health checks
- Monitor resource usage
- Track performance metrics
- Implement alerting
- Use distributed tracing
Documentation
- Document common issues
- Create troubleshooting guides
- Maintain runbooks
- Share debugging procedures
- Update documentation regularly
Security
- Limit debug access
- Secure debug endpoints
- Monitor debug activities
- Implement audit logging
- Use secure debugging tools

Debugging Operations

1. Service Debugging

# Restart service
docker compose restart app

# Rebuild service
docker compose up -d --build app

# View service configuration
docker compose config

# Debug service startup
docker compose up --abort-on-container-exit

2. Container Debugging

# Access container
docker compose exec app sh

# Copy files
docker compose cp app:/path/to/file ./local/path

# View container details
docker compose inspect app

# Debug container processes
docker compose exec app strace -p 1

3. Network Debugging

# Test connectivity
docker compose exec app curl -v http://db:5432

# Check DNS
docker compose exec app nslookup db

# Network analysis
docker compose exec app tcpdump -i eth0

Advanced Debugging Features

1. Debug Containers

services:
  debug:
    image: busybox
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: sleep infinity
    cap_add:
      - NET_ADMIN
    environment:
      - DEBUG=true

2. Debug Networks

services:
  debug:
    networks:
      - app_network
    command: ping db
    cap_add:
      - NET_RAW
    environment:
      - NETWORK_DEBUG=true

3. Debug Volumes

services:
  debug:
    volumes:
      - app_data:/data
    command: ls -la /data
    environment:
      - VOLUME_DEBUG=true
    cap_add:
      - SYS_ADMIN

Troubleshooting

Startup Issues

# Check startup logs
docker compose logs --tail=100 app

# Debug startup sequence
docker compose up --abort-on-container-exit

Connection Problems

# Test service connectivity
docker compose exec app curl -v http://db:5432

# Network diagnostics
docker compose exec app netstat -tulpn

Resource Issues

# Check resource usage
docker stats

# Monitor system metrics
docker compose exec app top

Integration with Debugging Tools

Logging Tools
- ELK Stack
- Fluentd
- Graylog
- Loki
- Promtail
Monitoring Tools
- Prometheus
- Grafana
- cAdvisor
- Node Exporter
- Blackbox Exporter
Debugging Tools
- strace
- tcpdump
- netstat
- gdb
- perf
Tracing Tools
- Jaeger
- Zipkin
- OpenTelemetry
- OpenTracing
- SkyWalking

Remember to document your debugging procedures and share knowledge with your team to improve overall troubleshooting efficiency. Regularly review and update your debugging strategies as your application evolves.