Docker container health and restart investigation cheat sheet
Inspect container exit state, health checks, bounded logs, resource usage and published ports during a restart incident.
Docker Engine CLI; examples use a container named web. Health fields exist only when a health check is configured.
Updated · Docker · 6 min read
| Command | What it does |
|---|---|
docker context show | Confirm the selected Docker context |
docker ps -a --filter name=web | Find the container and its status |
docker inspect --format "{{json .State}}" web | Inspect exit and health state |
docker logs --since 30m --tail 100 --timestamps web | Read bounded application logs |
docker stats --no-stream web | Take one resource-usage sample |
docker port web | Inspect published host port mappings |
Walkthrough
Confirm your Docker context and replace web with the affected container. Use authorized daemon access. No command here restarts, removes or executes code inside a container.
Step 1: Confirm the selected Docker context
docker context show
Record the context before collecting evidence. The same container name may exist on a local workstation and a remote daemon. Also check whether DOCKER_HOST or command-line endpoint flags override where your investigation is directed.
Step 2: Find the container and its status
docker ps -a --filter name=web
Inspect the container ID, image, status and published ports. The name filter can match multiple names; select the exact ID for follow-up queries. A running state does not prove application readiness or a passing health check.
Step 3: Inspect exit and health state
docker inspect --format "{{json .State}}" web
Read Status, ExitCode, OOMKilled, Error and timestamps. When present, Health includes probe results. OOMKilled supports a memory-kill investigation; exit code 137 alone does not prove an OOM kill because other SIGKILL paths can produce it.
Step 4: Read bounded application logs
docker logs --since 30m --tail 100 --timestamps web
Correlate the first application error with the start and finish timestamps. Logs generally reflect stdout and stderr, and availability depends on the logging driver. Redact tokens and connection strings before attaching excerpts to an incident.
Step 5: Take one resource-usage sample
docker stats --no-stream web
Record memory use, limit, CPU and block I/O for a running container. A single sample cannot establish the peak immediately before a crash. Compare multiple timed samples with host monitoring and the recorded exit state.
Step 6: Inspect published host port mappings
docker port web
Compare the container port and host binding with the URL users reach. A published mapping does not prove that the process is listening inside the container or that the host firewall and upstream load balancer permit traffic.
WORKED INCIDENT
Practical case: A web container repeatedly exits during peak traffic
Fictional teaching scenario; observations are examples, not captured production output.
Situation
Users see intermittent failures and the web container repeatedly starts and exits under load.
Investigation sequence
1. Confirm the selected Docker context
docker context showConfirm that the CLI targets the production daemon named in the incident.
2. Find the container and its status
docker ps -a --filter name=webCapture the exact container ID and image so a replacement is not confused with the original container.
3. Inspect exit and health state
docker inspect --format "{{json .State}}" webRead the stored exit state. This example has OOMKilled = true and ExitCode = 137.
4. Read bounded application logs
docker logs --since 30m --tail 100 --timestamps webCompare the last logs with the exit timestamp; missing shutdown logs are consistent with a forced kill but do not explain memory growth.
5. Take one resource-usage sample
docker stats --no-stream webIf the container is running, sample its memory and correlate with host metrics. If stopped, record that stats cannot show its previous peak.
Example findings
Illustrative findings: OOMKilled = true; ExitCode = 137; monitoring records memory approaching the configured limit before each exit.
Interpret the findings
The evidence supports a memory kill. It does not distinguish a leak, insufficient sizing or a traffic spike. Increasing limits without checking host capacity can move the failure to the host.
Verify the outcome
After an approved application or resource change, observe the same traffic window. Confirm stable uptime, passing health checks if configured, memory headroom and successful requests through the published service.
Escalation handoff
Send container/image IDs, exit timestamps, configured limits and monitoring graphs to the application/platform owners. Do not include a full inspect dump containing environment secrets.