Debugging Containers
Logs, exec, inspect, stats — the complete toolkit for diagnosing containerised applications
Skills taught: docker.logs, docker.exec, docker.inspect, docker.stats, docker.debugging
Reading container logs
# View all logs since container started
docker logs my-api
# Follow (stream) logs in real time
docker logs -f my-api
# Show only last 50 lines
docker logs --tail 50 my-api
# Show logs with timestamps
docker logs -t my-api
# Show logs since a specific time
docker logs --since 1h my-api # last hour
docker logs --since 2024-01-15 my-api
# Combine: tail + follow with timestamps
docker logs -f -t --tail 100 my-api
# With Docker Compose:
docker compose logs -f api
docker compose logs -f --tail 50 api postgres
exec — run commands inside a running container
# Open an interactive shell (bash)
docker exec -it my-api bash
# Alpine-based images use sh not bash
docker exec -it my-api sh
# Run a single command and exit
docker exec my-api node --version
docker exec my-api cat /app/config.json
docker exec my-api env | sort # see all environment variables
# Connect to PostgreSQL inside its container
docker exec -it my-postgres psql -U postgres myapp
# Connect to Redis CLI
docker exec -it my-redis redis-cli
# With Compose:
docker compose exec api sh
docker compose exec postgres psql -U postgres myapp
# Debugging: what processes are running inside?
docker exec my-api ps aux
# Check disk usage inside container
docker exec my-api df -h
inspect and stats — container internals
# Full JSON dump of a container's config
docker inspect my-api
# Extract specific fields with --format (Go template)
docker inspect my-api --format '{{.State.Status}}'
docker inspect my-api --format '{{.State.ExitCode}}'
docker inspect my-api --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'
docker inspect my-api --format '{{json .HostConfig.PortBindings}}'
# Live resource usage for all containers
docker stats
# CONTAINER CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O
# my-api 2.3% 128MiB / 512MiB 25% 1.2MB/... 0B
# my-postgres 0.1% 67MiB / 1GiB 6.5% ...
# One-shot snapshot (no live update)
docker stats --no-stream
Debugging a crashed container
# See ALL containers including stopped ones
docker ps -a
# STATUS: Exited (1) 2 minutes ago ← non-zero exit = crash
# Read the crash logs
docker logs my-api
# Error: ECONNREFUSED — database not ready yet
# Check exit code
docker inspect my-api --format '{{.State.ExitCode}}'
# 1 = general error, 137 = OOM killed, 143 = SIGTERM (clean stop)
# Common exit codes:
# 0 = clean exit
# 1 = application error
# 137 = OOM kill (increase --memory limit)
# 139 = segfault
# 143 = SIGTERM received
# Debug a container that exits immediately:
# Override the CMD to keep it open
docker run --rm -it --entrypoint sh myapp
# Now you're inside — diagnose manually
Tip: Add a /health endpoint to every service. A simple GET /health route that returns 200 gives you a compose healthcheck target, lets load balancers route traffic away from unhealthy instances, and is the first thing to check when debugging: docker exec my-api curl -s localhost:3000/health
Frequently Asked Questions
How do I debug a container that doesn't have bash or sh installed?
Use 'docker run --pid=container:<id> --network=container:<id> --privileged nicolaka/netshoot' — a debug container that shares the target container's PID and network namespace, giving you curl, dig, tcpdump, and many other tools without modifying your production image. Or use 'docker debug' (Docker Desktop feature) which attaches a debug shell to any container.