Skip to Content

Debugging & Logs

When to use

investigate a failing container: read logs, exec in, inspect filesystem, attach debugger.

Analogy

debugging a container is like a detective at a crime scene - check what happened (logs), confirm what’s there (exec), look at every clue.

Data-flow diagram

  docker logs web            # stdout / stderr of PID 1
  docker exec -it web bash   # interactive shell
  docker top web             # processes
  docker stats web           # cpu / mem / net
  docker diff web            # filesystem changes vs image
  docker cp web:/path ./path # copy file out

Deep explanation

Containers are opaque by default - they look like processes with their own filesystem. docker logs shows stdout/stderr of PID 1 (you cannot see logs of other processes unless you explicitly forward them). docker exec starts a new process inside the container’s namespaces. docker inspect gives full config (env, mounts, network). docker stats shows live resource consumption. docker system events shows daemon-level events. Compose adds docker compose logs -f web and docker compose exec web bash.

Examples

Example 1

docker logs --tail 200 --since 5m web
docker logs --follow web 2>&1 | grep -i error

shows last 200 lines from last 5 minutes; follows live; filters for errors.

Example 2

docker exec -u root -it web /bin/sh
# if no shell: debug side-car image
docker run --rm --network container:web nicolaka/netshoot nslookup db

opens a shell in container; or runs a debug side-car in same network as web.

Example 3

docker stats --no-stream
docker top web
docker diff web

quick snapshot of resource usage, process tree, filesystem changes vs base image.

Common mistake

Using docker logs to debug a service that runs as PID 1 but logs to a file (only stdout is captured). Not configuring log rotation (Docker fills host disk).

Key takeaway

Always log to stdout; configure log rotation (--log-opt max-size=10m --log-opt max-file=3); use exec for ad-hoc investigation; consider a debug side-car image.

Production Failure Playbook

Failure scenario 1: host-disk-full-from-logs

Failure scenario 2: cannot-exec-into-minimal-image