Inspecting a docker container

In this post, we'll learn how to use the docker container inspect command. I will summarize how to check docker container IP, port, name, status, internal path, capacity, logs, and network.

1. Verify Docker Container Command

There are two commands that you can use to check the general information of a Docker container.

1.1. inspect command for detailed information

The first command is the inspect command to view the details of a container. You can use it like this to get the details of one or more containers in JSON format.

$ docker container inspect [OPTIONS] CONTAINER [CONTAINER...]

If you type the command directly, you'll get a lot of stuff to scroll through. Here are the big ones

[
    {
        "id": "72256fae4d38ad302a4788771e0155b03c315a8389fe4327af3912d9e2ae0415",
        "Created": "2023-05-27T01:32:38.177055001Z",
        "Path": "/docker-entrypoint.sh",
        "Args": [
            "nginx",
            "-g",
            "daemon off;"
        ],
        "State": {
        "Status": "running",
        "Running": true,
        "Paused": false,
        ...
        "Pid": 3403,
        "ExitCode": 0,
        "Error": "",
        "StartedAt": "2023-05-27T01:32:38.380814543Z",
        "FinishedAt": "0001-01-01T00:00:00Z"        },
        "Image": "sha256:c42efe0b54387756e68d167a437aef21451f63eebd9330bb555367d67128386c",
        "Name": "/pedantic_cray",
        "ResolvConfPath": "/var/lib/docker/containers/72256fae4d38ad302a4788771e0155b03c315a8389fe4327af3912d9e2ae0415/resolv.conf"
        ,        "HostnamePath": "/var/lib/docker/containers/72256fae4d38ad302a4788771e0155b03c315a8389fe4327af3912d9e2ae0415/hostname",
        "HostsPath": "/var/lib/docker/containers/72256fae4d38ad302a4788771e0155b03c315a8389fe4327af3912d9e2ae0415/hosts",
        ...
        "HostConfig": {},
        "GraphDriver": {},
        "Mount": [],
        "Config": {},
        "NetworkSettings": {}
    }
]

The Id and Name items are the unique ID and name of the container, and the Path and Args items are the files or commands executed when the container is created, The State entry indicates the current state of the container. The ResolveConfPath, HostnamePath, HostsPath, and HostConfig items contain file paths or configuration statements that configure the Docker host environment, The Image, NetworkSettings, and GraphDriver items display the container's image, network, and storage environment.

Because the Docker inspect command is designed to show everything about a container, it can be overwhelming to use when you want to see specific information. For this reason, it provides the --format option, which allows you to use the Go language's `text/template' package to output only the information you want.

1.2. Using Go templates for the --format option

Because Docker is written in the Go language, which is excellent for controlling concurrency, you'll notice some borrowing of Go syntax. The --format option of the inspect command is one such example of Go syntax borrowing.

Below is a simple example of a text/template in Go, but don't try to understand it, just look at it. The key part is the line t, _ = t.Parse("Name: { {.Name} }, Age: { {.Age} }\n"). You can see that the Go template gets each property of the Person structure with two curly braces and a single dot.

package main
 
import (
    "os"
    "text/template"
)
 
type Person struct {
    Name string
    Age  int
}
 
func main() {
    t := template.New("person template")
 
    t, _ = t.Parse("Name: { {.Name} }, Age: { {.Age} }\n")
    p := Person{Name: "Alice", Age: 30}
 
    t.Execute(os.Stdout, p)
}
 

Docker uses the same syntax. You can set up a template by thinking of the output JSON file as a large structure, and each field as a property of that structure.

For example, let's print the container's Status record. The Status element is inside the top-level State field. So we might type something like this

$ docker container inspect --format='{ {.State.Status} }' CONTAINER

command, it will return the following result

$ docker container inspect --format='{ {.State.Status} }' 7225
running

As you can see, you can customize the output by using the Go template syntax.

To customize the output, see the Formatting commands and log output page (opens in a new tab) in the official Docker documentation. It is explained intuitively, so you should be able to understand it right away.

1.3. stats command to check real-time information

The stats command displays the CPU, memory usage, and number of processes of all running containers in real time, as well as cumulative I/O over the network or block interface.

To use it, type the following command

$ docker container stats [OPTIONS] [CONTAINER...]

You'll be taken to a separate screen that displays real-time information, as shown below.

CONTAINER ID   NAME            CPU %  ...
72256fae4d38   pedantic_cray   0.00%  ...

If you only want to print the current information and not the information that is updated in real time, add the --no-stream option. You'll notice that the prompt returns after the information is printed.

Now let's see how to output specific information based on these two commands in turn.

2. Getting the name and status

You can print the name and status of a container using the ls command and the inspect command. The former expresses relative time and the latter absolute time, so you can choose one or the other depending on your needs.

2.1. ls showing relative time

There are several ways to get the name and state of a container. The first is the docker container ls (--all) command, which we've already seen in Run a container and Stop/Exit a container.

As shown below, you can get a simple list of container names and statuses. Just look at the STATUS entry and the NAMES'entry.

$ docker container ls
CONTAINER ID   ...   STATUS       NAMES
72256fae4d38   ...   Up 5 hours   pedantic_cray

The ls command can also take the --format option, which we learned about in Section 1.2. Below is a command that outputs only the container name and status as a list.

$ docker container ls --format='table { {.Names} }\t{ {.Status} }'
NAMES           STATUS
pedantic_cray   Up 6 hours

The keywords table and \t are commands that output like a table. See Section 1.2 .

2.2. inspect to output absolute times

If the 1ls1 command outputs relative times as shown above, the inspect command can be used to output the exact status, name, creation time, start time, etc. of a single container.

$ docker container inspect --format ' Container name: { {println .Name}} } State: { {println .State.Status} } Created at: { {println .Created}} } Started at: { { {println .State.StartedAt}} }' 7225
Container name: /pedantic_cray
State: running
Created at: 2023-05-27T01:32:38.177055001Z
Started at: 2023-05-27T01:32:38.380814543Z

The println keyword adds a line break after the current entry.

3. Check IP, Port

3.1. Checking the container IP

Checking the container IP uses the inspect command.

docker container inspect --format='{ {range $network, $config := .NetworkSettings.Networks} }[{ {$network} }]: { {println $config.IP Address} }{ {end} }' 7225
[bridge]: 172.17.0.2

The range keyword and the { {end} } keyword act as a loop in the Go template. Since Docker containers have multiple IP addresses depending on the network they are connected to, we use the range keyword to print them all. The default IP can be found by checking the IPAddress entry in the network, usually called bridge.

3.2. Checking container ports

The command to check container ports is provided, so you can easily check them as follows.

$ docker container port 7225
80/tcp -> 0.0.0.0:8000

As shown in Section 3.1, you can produce the same output using the inspect command and a Go template. Try it if you have time.

4. Checking the path inside the container

There are two ways to check the path inside a container: from outside the container and from inside the container.

4.1. Checking the internal path from outside the container

The docker container exec command provides a way to issue the desired command to the container shell from outside the container.

For example, the following command will print the path to the working directory of the current container.

$ docker container exec 7225 pwd
/

You can also browse through the files and directories you want.

$ docker container exec -u root 7225 ls /usr/share/nginx/html
50x.html
index.html

Adding the -u root option will run the command with root privileges.

4.2. Checking the internal path inside a container

If you want to access the inside of a container to see its internal paths, run the container shell with the -it option.

$ docker container exec -it 7225 /bin/sh
# pwd
/
# ls /usr/share/nginx/html
50x.html  index.html
# exit

Like the last prompt in the example above, type exit to exit the shell.

5. Checking Capacity

The command to check the total capacity of all containers in your local environment is below

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          2         2         181.8MB   0B (0%)
Containers      3         1         3.281kB   2.186kB (66%)
Local Volumes   0         0         0B        0B
Build Cache     0         0         0B        0B

It displays the amount of space currently occupied by all images, containers, volumes, and caches in the Docker environment, with the RECLAIMABLE entry indicating the amount of space for each object that is not in use.

6. Checking logs

The command to check the logs of a container is as follows. If you want to check the logs in real time, use the -f (--follow) option. If you want to see only recent logs and output from old containers, you can specify a number with the -n (--tail) option. The --since option is also useful to print only logs for the last 50 s (seconds), 30 m (minutes), and 5 h (hours).

$ docker container logs --since 10h --tail 5 --follow 7225
2023/05/27 01:32:38 [notice] 1#1: start worker processes
2023/05/27 01:32:38 [notice] 1#1: start worker process 29
2023/05/27 01:32:38 [notice] 1#1: start worker process 30
2023/05/27 01:32:38 [notice] 1#1: start worker process 31
2023/05/27 01:32:38 [notice] 1#1: start worker process 32

7. Verifying the Network

The process of checking a container's network is as follows. First, check the list of networks connected to the container, and then check the details of these networks.

The command for checking the list of networks connected to a container

$ docker container inspect --format='{ {range $network, $config := .NetworkSettings.Networks} }{ {println $network}  }{ {end} }' 7225
bridge
db-net

This command prints a list of network names, as shown above. Now, use the Network Name with command as follows to view its details.

$ docker network inspect db-net
[
    {
        "Name": "db-net",
        "Id": "74b2026af3ee7d328aab14d33894d1c9fc31cd21176051c7c90cab1440342ae7",
        ...

A more detailed discussion of network information will be covered in a future Docker Network post.

8. Final Thoughts

In this post, we learned about the Docker container verification commands. I hope this helps you when you need to know how to verify a Docker container's IP, port, name, status, internal path, capacity, logs, and network.