Something broke at nine at night
docker inspect shows how a container was set up, and docker logs shows what its program said while it ran. Together they are how you find out why a container went wrong.
A shop's page shows an error at nine at night. The engineer who built it is asleep. You are the one on call, and you cannot ask her anything.
Everything you need is on the machine.
By the end of this lesson
Note
I can find out how a container was set up and what it has said.
Key words
| Word | What it means | Example |
|---|---|---|
| Inspect | to read the full settings of a container | |
| Log | the messages a program writes while it runs | |
| Exit code | the number a program gives when it stops; 0 means success | |
| Health check | a test Docker repeats to see if a service still answers | |
| Environment variable | a named setting handed to a program | NGINX_VERSION |
The cells students fill in are left blank in this preview.
docker inspect reads a container's setup
docker ps shows a few columns. docker inspect shows everything Docker knows about one container, as JSON.
You rarely read all of it. --format picks out one field, written between double curly braces. The next four commands read the image, the doors, the memory limit and one environment variable of web.
Which image does web run?
docker inspect --format '{{.Config.Image}}' webShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Which doors does it say it uses?
docker inspect --format '{{json .Config.ExposedPorts}}' webShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
How much memory may it use, in bytes?
docker inspect --format '{{.HostConfig.Memory}}' webShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Read one environment variable inside it
docker exec web printenv NGINX_VERSIONShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Worked example: who set each thing
| Thing | Who set it | How you read it |
|---|---|---|
| The image | whoever started the container | Config.Image |
| The doors (ports) | the image's author, in the Dockerfile | Config.ExposedPorts |
| The memory limit | the lab's compose file | HostConfig.Memory |
| NGINX_VERSION | the image's author, in the Dockerfile | docker exec web printenv NGINX_VERSION |
The cells students fill in are left blank in this preview.
A common mistake
Warning
Many people think docker ps shows everything about a container. It shows a summary. The user it runs as, its limits, its environment and its health are only in docker inspect. Use ps to find the container and inspect to ask it questions.
A log is what the program said
A container's log is everything its main program printed. docker logs shows it.
A busy service writes a lot. In this lab a health check calls web every few seconds, and each call is one line. So you filter. First, ask for a page that does not exist.
Ask web for a missing page
curl -s -o /dev/null -w "%{http_code}\n" http://web/missingShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Find that request in the log
docker logs web 2>&1 | grep "/missing"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Exit code and health say how it ended
A container is running, or it has stopped. When it stops, its exit code says how. Zero means it finished well. Any other number means it failed.
A health check is a test Docker repeats while the container runs. The result is healthy or unhealthy.
Is web running? What is its exit code?
docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' webShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Does web pass its health check?
docker inspect --format '{{.State.Health.Status}}' webShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
How much memory is web using now?
docker stats --no-stream --format "{{.Name}} {{.MemUsage}}" webShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Worked example: four questions for a failing container
| Question | Command | What a stopped "report" job might show |
|---|---|---|
| Is it running? | docker ps -a | Exited (137) a minute ago |
| How did it end? | docker inspect --format '{{.State.ExitCode}}' report | 137: it was killed |
| What did it say last? | docker logs --tail 5 report | a line about running out of memory |
| What was it told? | docker inspect --format '{{.HostConfig.Memory}}' report | a limit smaller than the job needs |
The cells students fill in are left blank in this preview.
Going further
The lab's worker has stopped. You now have the four questions for it: its status, its exit code, its log and its settings. The lab's own task is to answer them and fix it.
Before you do, run docker inspect web with no --format. Find the three big sections: Config, State and HostConfig.