Debugging and Operations

Operational Docker work starts with asking the container runtime what is happening. Do not guess. Inspect the image, the container, the logs, the network, and the resource usage.

Container state

List running and stopped containers.

1docker ps
2docker ps --all

Inspect the complete container configuration.

1docker inspect api
2docker inspect --format '{{json .State.Health}}' api

Check the process list inside a running container.

1docker top api

Logs

Containers should write logs to stdout and stderr. Docker captures those streams.

1docker logs api
2docker logs --follow --tail 100 api
3docker logs --since 30m api

Configure logging drivers at the daemon or container level when logs need to go to a platform-specific system.

1docker run \
2    --log-driver json-file \
3    --log-opt max-size=10m \
4    --log-opt max-file=3 \
5    nginx:alpine

Shell access

Use docker exec when the image has a shell.

1docker exec -it api sh

Many production images should be slim and may not include a shell or package manager. For those images, use docker debug when it is available in your environment. It creates a debugging shell with tools without permanently changing the target image.

1docker debug api

Resource usage

Check live resource usage.

1docker stats
2docker stats api

Check Docker events while reproducing a problem.

1docker events

Health checks

A health check tells Docker and Compose whether the application is actually ready.

1HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
2    CMD wget -qO- http://127.0.0.1:8080/health || exit 1

Inspect health status.

1docker inspect --format '{{.State.Health.Status}}' api
2docker inspect --format '{{range .State.Health.Log}}{{println .Output}}{{end}}' api

Image inspection

Check image metadata and history.

1docker image inspect api:local
2docker history api:local

Use this to catch unexpected users, commands, ports, labels, and large layers.

Network debugging

Inspect networks and test from inside the same network namespace.

1docker network ls
2docker network inspect appnet
3docker exec -it api sh
4getent hosts db
5nc -vz db 3306

Compose debugging

Compose scopes commands to the project.

1docker compose ps
2docker compose logs -f api
3docker compose exec api sh
4docker compose events
5docker compose config

Cleanup

Clean up deliberately. Avoid broad prune commands on shared machines unless you know what they will remove.

1docker container prune
2docker image prune
3docker volume ls
4docker volume rm <volume-name>

Practical checklist

  • Start with docker ps --all and docker logs.

  • Inspect health status before restarting a service.

  • Use docker inspect to verify ports, mounts, networks, user, and entrypoint.

  • Use docker stats for CPU and memory symptoms.

  • Debug networking from a container on the same network.

  • Use docker debug for slim images that do not include shells.

  • Write logs to stdout and stderr.

References