Debugging & Logging

Container Logs

Docker captures stdout and stderr from the container main process. View logs with docker logs. Follow in real time with -f. Limit output with --tail and --since.

Applications should log to stdout/stderr, not files inside the container. File-based logs are lost when containers are removed. Structured JSON logging enables parsing by log aggregation tools.

• Configure logging driver in daemon.json for centralized logging
• json-file driver supports max-size and max-file rotation
• Use structured logging (JSON) for machine-parseable output

docker logs web
docker logs -f --tail 100 web
docker logs --since 30m web
docker logs -t web  # Include timestamps

Exec and Debug Access

docker exec runs commands in a running container without stopping it. Open a shell with docker exec -it container sh. Run one-off commands like docker exec web npm test.

Install debugging tools in a separate debug stage or sidecar container rather than bloating production images. Copy files out with docker cp container:/path ./local-path.

docker exec -it web sh
docker exec web cat /app/config.json
docker exec web ps aux
docker cp web:/app/logs/error.log ./error.log

Inspect and Metadata

docker inspect returns detailed JSON metadata about containers, images, networks, and volumes. Filter with --format using Go templates for specific fields.

Useful inspect queries: container IP address, mount points, environment variables, and network settings. Script these queries for automated health checks and monitoring.

# Get container IP
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web

# Get all environment variables
docker inspect --format='{{range .Config.Env}}{{println .}}{{end}}' web

# Check container state
docker inspect --format='{{.State.Status}}' web

Resource Monitoring

docker stats shows real-time CPU, memory, network, and disk I/O for running containers. Use it to identify resource-hungry containers and validate limit settings.

For production monitoring, export container metrics to Prometheus with cAdvisor or the Docker metrics endpoint. Grafana dashboards visualize trends and alert on thresholds.

docker stats              # All running containers
docker stats web api db     # Specific containers
docker stats --no-stream    # Single snapshot

# Prometheus metrics endpoint
curl http://localhost:9323/metrics

Common Debugging Scenarios

Container exits immediately: check logs and run interactively without -d. Cannot connect to service: verify network, port mapping, and that the app binds to 0.0.0.0 not 127.0.0.1. Permission denied: check volume mount permissions and user IDs.

Create a debug compose profile with tools like curl, netcat, and database clients pre-installed for troubleshooting without modifying production images.

# Debug exiting container
docker run -it --rm myapp sh
# Then manually run: node server.js

# Check what listens inside container
docker exec web netstat -tlnp