Inspecting Containers (inspect, stats, logs)
Containers may be lightweight, but when something goes wrong, you need visibility into what’s happening inside them. Is a container consuming too much memory? Is a process crashing? Are errors being written to the logs?
Docker gives us several built-in tools to answer these questions and troubleshoot containers effectively. Let’s explore the most useful ones.
Why Inspect Containers
Inspecting containers is useful for monitoring their resource usage, troubleshooting problems, checking logs and processes, and retrieving configuration/runtime details.
Common things you may want to inspect include:
- CPU and memory usage
- Network and disk I/O
- Container logs
- Processes running inside the container
- Container configuration and runtime metadata
- Environment variables, mounts, ports, networks, and other settings
View Stats
To get details about CPU, Memory Usage, I/O, etc. of all running containers, use the stats command:
docker container statsTip
By default, it streams the output continuously. Use Ctrl+C to stop it, or use --no-stream to get a single snapshot. You can also pass a container ID or name to inspect a specific container.
To view the output in JSON format, use the --format option with a JSON template:
docker container stats --no-stream --format '{{json .}}'This is particularly useful when the output needs to be consumed by scripts or other programs.
View Logs
To demonstrate container logs, let’s run an ubuntu container in interactive mode:
docker container run -i ubuntuNote the container ID it provides. You can also find it with:
docker container ls -aFrom another terminal, start viewing the logs:
docker container logs <container-id>You may see no output because no logs have been emitted to STDOUT yet. To continuously watch for new logs, use --follow:
docker container logs --follow <container-id>Now, in the terminal where you are already inside the container, run:
echo "I emit the log"If you go back to the terminal where you are following the logs, you should see:
I emit the logImportant
This is just a simple demonstration of how container logs are emitted. Real applications can produce logs continuously. For example, an nginx container may emit a log entry for every HTTP request:
172.17.0.1 - - [08/Aug/2026:06:08:58 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.5.0" "-"
172.17.0.1 - - [08/Aug/2026:06:09:05 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.5.0" "-"
172.17.0.1 - - [08/Aug/2026:06:09:06 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.5.0" "-"You can also retrieve only the most recent logs:
docker container logs --tail 100 <container-id>Or include timestamps:
docker container logs --timestamps <container-id>These options can be combined:
docker container logs --follow --tail 100 --timestamps <container-id>View Processes
To see the processes currently running inside a container:
docker container top <container-id>Sample output:
UID PID PPID C STIME TTY TIME CMD
root 17267 17242 0 11:48 ? 00:00:00 nginx: master process nginx -g daemon off;
message+ 17328 17267 0 11:48 ? 00:00:00 nginx: worker process
message+ 17329 17267 0 11:48 ? 00:00:00 nginx: worker processThe command supports options for customizing the process listing. For example:
docker container top <container-id> auxThis passes aux to the underlying process-listing command and can provide additional process information when supported by the container’s runtime environment.
Note
docker container top shows processes from the Docker host’s perspective. It is therefore not exactly the same as running ps inside the container.
Inspecting
The inspect command provides detailed information about a container:
docker container inspect <container-id>This produces a large JSON document containing information such as:
- Container ID and name
- Image
- Entrypoint and command
- Environment variables
- Port configuration
- Network settings
- Mounted volumes
- Resource limits
- Restart policy
- Container state
- IP addresses
- Creation and start times
The output can be quite long. That’s fine for one-off investigations, but if you need a specific value, use Go-template formatting.
For example, to get the container’s IP address:
docker container inspect --format '{{.NetworkSettings.IPAddress}}' <container-id>To get the container name:
docker container inspect --format '{{.Name}}' <container-id>To get the image used by the container:
docker container inspect --format '{{.Config.Image}}' <container-id>To get the container’s current state:
docker container inspect --format '{{.State.Status}}' <container-id>You can also extract multiple values at once:
docker container inspect \
--format 'Name={{.Name}} Image={{.Config.Image}} Status={{.State.Status}}' \
<container-id>For scripts, --format is especially useful because it avoids having to parse the entire JSON output.
Use this table as reference.
--format example | What it gives you |
|---|---|
{{.Name}} | Container name |
{{.Config.Image}} | Image used by the container |
{{.State.Status}} | Current status (running, exited, etc.) |
{{.State.Pid}} | Container’s main process PID |
{{.Created}} | Container creation timestamp |
{{.Config.Cmd}} | Command configured for the container |
{{.Config.Entrypoint}} | Container entrypoint |
{{.NetworkSettings.IPAddress}} | Container IP address |
{{.HostConfig.RestartPolicy.Name}} | Restart policy |
{{json .Config.Env}} | Environment variables as JSON |
For more formatting options, refer the docs.
Quick Reference
| What you want to inspect | Command |
|---|---|
| Resource usage | docker container stats |
| One-time resource snapshot | docker container stats --no-stream |
| Logs | docker container logs <container> |
| Follow logs | docker container logs --follow <container> |
| Processes | docker container top <container> |
| Full container details | docker container inspect <container> |
| Specific container detail | docker container inspect --format '...' <container> |
Together, stats, logs, top, and inspect cover many of the basic container-inspection tasks you’ll need when monitoring and troubleshooting Docker containers.