🔍 Container Debugging Guide¶

🎯 Quick Diagnosis Flow¶

Container issue?
    ↓
1. Check logs → docker logs <container>
    ↓
2. Check status → docker ps -a
    ↓
3. Inspect → docker inspect <container>
    ↓
4. Interactive shell → docker exec -it <container> /bin/bash
    ↓
5. Test isolated → docker run --rm -it <image> /bin/bash

🔎 Inspección Básica¶

Ver containers corriendo¶

# Todos los containers
docker ps -a

# Con formato custom
docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}"

# Filtrar por status
docker ps -a --filter status=exited

# Últimos N containers
docker ps -n 5

Shell en container corriendo¶

# Bash interactivo
docker exec -it <container> /bin/bash

# Como root (para debug)
docker exec -it --user root <container> /bin/bash

# Ejecutar comando único
docker exec <container> ls -la /workspace

# Ver procesos
docker exec <container> ps aux

# Ver variables de entorno
docker exec <container> env

Inspeccionar volumes¶

# Listar volumes
docker volume ls

# Inspeccionar volume específico
docker volume inspect <volume_name>

# Ver contenido de volume
docker run --rm -v <volume_name>:/data alpine ls -la /data

# Backup volume
docker run --rm -v <volume_name>:/data -v $(pwd):/backup \
  alpine tar czf /backup/volume-backup.tar.gz -C /data .

# Restore volume
docker run --rm -v <volume_name>:/data -v $(pwd):/backup \
  alpine tar xzf /backup/volume-backup.tar.gz -C /data

Ver logs¶

# Logs completos
docker logs <container>

# Follow (real-time)
docker logs -f <container>

# Últimas N líneas
docker logs --tail 100 <container>

# Con timestamps
docker logs -t <container>

# Desde tiempo específico
docker logs --since 2024-01-01T10:00:00 <container>

# Entre tiempos
docker logs --since 10m --until 5m <container>

Inspeccionar image layers¶

# Ver todas las layers y tamaños
docker history <image>

# Formato human-readable
docker history --human --no-trunc <image>

# Ver qué hace cada layer
docker history --format "{{.CreatedBy}}" <image>

# Analizar image size
docker images <image> --format "{{.Size}}"

🌐 Network Debugging¶

Listar y inspeccionar networks¶

# Listar networks
docker network ls

# Inspeccionar network
docker network inspect <network>

# Ver qué containers están en network
docker network inspect <network> | grep -A 5 Containers

# Crear network para testing
docker network create --driver bridge test-net

Test conectividad¶

# Ping entre containers
docker exec <container1> ping <container2>

# Verificar DNS
docker exec <container> nslookup <hostname>

# Test port
docker exec <container> nc -zv <host> <port>

# Curl desde container
docker exec <container> curl http://other-service:8080

# Install debug tools en container
docker exec -u root <container> apt-get update && apt-get install -y iputils-ping curl netcat

Ver puertos¶

# Ver port mappings
docker port <container>

# Ver todos los puertos expuestos
docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' <container>

# Verificar port en uso en host
netstat -tulpn | grep <port>

🔬 Deep Inspection¶

Inspeccionar container completo¶

# Toda la info
docker inspect <container>

# Filtrar campos específicos
docker inspect --format='{{.State.Status}}' <container>
docker inspect --format='{{.RestartCount}}' <container>
docker inspect --format='{{.NetworkSettings.IPAddress}}' <container>

# Mounts
docker inspect --format='{{json .Mounts}}' <container> | jq

# Environment variables
docker inspect --format='{{range .Config.Env}}{{println .}}{{end}}' <container>

# Exit code
docker inspect --format='{{.State.ExitCode}}' <container>

Resource usage¶

# Stats en tiempo real
docker stats

# Stats para container específico
docker stats <container>

# Una vez (no streaming)
docker stats --no-stream

# Custom format
docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"

Process debugging¶

# Ver procesos en container
docker top <container>

# Con formato custom
docker top <container> -o pid,comm,args

# Desde dentro del container
docker exec <container> ps aux
docker exec <container> ps -ef

# Ver threads
docker exec <container> ps -eLf

🛠️ Advanced Debugging¶

Attach to running container¶

# Attach a stdout/stderr (solo lectura)
docker attach --sig-proxy=false <container>

# Detach: Ctrl+C (con --sig-proxy=false no mata container)

Copy files para debug¶

# Copy desde container a host
docker cp <container>:/path/to/file ./local-path

# Copy desde host a container
docker cp ./local-file <container>:/path/in/container

# Copy directorio completo
docker cp <container>:/var/log ./logs

Debug build process¶

# Build con output verbose
docker build --progress=plain --no-cache .

# Build hasta stage específico
docker build --target build-stage .

# Ejecutar shell en stage intermedio
docker build --target build-stage -t debug-image .
docker run --rm -it debug-image /bin/bash

# Ver BuildKit cache
docker buildx du

Crear snapshot para debug¶

# Commit container a image
docker commit <container> debug-snapshot

# Ejecutar snapshot
docker run --rm -it debug-snapshot /bin/bash

# Comparar filesystem changes
docker diff <container>

Audio-specific debugging¶

# Verificar audio devices
docker exec <container> ls -la /dev/snd

# Test ALSA
docker exec <container> aplay -l
docker exec <container> arecord -l

# Test PulseAudio
docker exec <container> pactl info
docker exec <container> pactl list sinks

# Test JACK
docker exec <container> jack_lsp
docker exec <container> jack_wait -c

📊 Performance Analysis¶

CPU profiling¶

# Top processes en container
docker exec <container> top -bn1

# CPU usage específico
docker stats --format "{{.Container}}: {{.CPUPerc}}"

# Usar perf (requiere capabilities)
docker run --cap-add=SYS_ADMIN <image>

Memory analysis¶

# Memory usage
docker stats --format "{{.Container}}: {{.MemUsage}}"

# Inside container
docker exec <container> free -h
docker exec <container> cat /proc/meminfo

# OOM killer logs
docker inspect <container> | grep OOMKilled

Disk I/O¶

# Ver disk usage
docker system df
docker system df -v

# Container disk usage
docker exec <container> df -h

# Ver I/O stats
docker stats --format "{{.Container}}: {{.BlockIO}}"

🔧 Cleanup Debugging¶

# Ver qué se limpiará (dry-run)
docker system prune --dry-run

# Limpiar con confirmación
docker system prune
docker image prune
docker container prune
docker volume prune
docker network prune

# Limpiar todo (CUIDADO)
docker system prune -a --volumes

# Ver espacio recuperable
docker system df

📝 Debugging Checklist¶

🚨 Emergency Commands¶

# Parar todos los containers
docker stop $(docker ps -q)

# Remover todos los containers stopped
docker rm $(docker ps -a -q -f status=exited)

# Forzar kill container que no responde
docker kill <container>

# Restart Docker daemon (Linux)
sudo systemctl restart docker

# Restart Docker daemon (Windows)
Restart-Service docker

# Limpiar todo y empezar de cero (DESTRUCTOR)
docker system prune -a --volumes -f
docker network prune -f

📚 Useful One-Liners¶

# Container más viejo
docker ps -a --format "{{.CreatedAt}}\t{{.Names}}" | sort | head -1

# Container usando más CPU
docker stats --no-stream --format "{{.Container}}\t{{.CPUPerc}}" | sort -k2 -rn | head -1

# Container usando más memoria
docker stats --no-stream --format "{{.Container}}\t{{.MemPerc}}" | sort -k2 -rn | head -1

# Volumes huérfanos
docker volume ls -qf dangling=true

# Images sin tag
docker images -f "dangling=true" -q

# Containers exited recientemente
docker ps -a --filter "status=exited" --format "{{.Names}}\t{{.Status}}"