2015-06-21 16:41:38 -04:00
# stats
2023-01-06 13:04:05 -05:00
<!-- - MARKER_GEN_START -->
2016-07-07 14:43:18 -04:00
Display a live stream of container(s) resource usage statistics
2015-06-21 16:41:38 -04:00
2023-01-06 13:04:05 -05:00
### Aliases
`docker container stats` , `docker stats`
### Options
| Name | Type | Default | Description |
|:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2024-07-03 02:29:57 -04:00
| `-a` , `--all` | `bool` | | Show all containers (default shows just running) |
2023-01-06 13:04:05 -05:00
| [`--format` ](#format ) | `string` | | Format output using a custom template:< br > 'table': Print output in table format with column headers (default)< br > 'table TEMPLATE': Print output in table format using the given Go template< br > 'json': Print in JSON format< br > 'TEMPLATE': Print output using the given Go template.< br > Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
2024-07-03 02:29:57 -04:00
| `--no-stream` | `bool` | | Disable streaming stats and only pull the first result |
| `--no-trunc` | `bool` | | Do not truncate output |
2023-01-06 13:04:05 -05:00
cli: use custom annotation for aliases
Cobra allows for aliases to be defined for a command, but only allows these
to be defined at the same level (for example, `docker image ls` as alias for
`docker image list`). Our CLI has some commands that are available both as a
top-level shorthand as well as `docker <object> <verb>` subcommands. For example,
`docker ps` is a shorthand for `docker container ps` / `docker container ls`.
This patch introduces a custom "aliases" annotation that can be used to print
all available aliases for a command. While this requires these aliases to be
defined manually, in practice the list of aliases rarely changes, so maintenance
should be minimal.
As a convention, we could consider the first command in this list to be the
canonical command, so that we can use this information to add redirects in
our documentation in future.
Before this patch:
docker images --help
Usage: docker images [OPTIONS] [REPOSITORY[:TAG]]
List images
Options:
-a, --all Show all images (default hides intermediate images)
...
With this patch:
docker images --help
Usage: docker images [OPTIONS] [REPOSITORY[:TAG]]
List images
Aliases:
docker image ls, docker image list, docker images
Options:
-a, --all Show all images (default hides intermediate images)
...
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2022-06-28 04:52:25 -04:00
2023-01-06 13:04:05 -05:00
<!-- - MARKER_GEN_END -->
2015-06-21 16:41:38 -04:00
2017-02-07 18:42:48 -05:00
## Description
2020-04-19 09:43:08 -04:00
The `docker stats` command returns a live data stream for running containers. To
limit data to one or more specific containers, specify a list of container names
or ids separated by a space. You can specify a stopped container but stopped
containers do not return any data.
If you need more detailed information about a container's resource usage, use
the `/containers/(id)/stats` API endpoint.
2024-08-16 05:02:10 -04:00
> [!NOTE]
2020-04-19 09:43:08 -04:00
> On Linux, the Docker CLI reports memory usage by subtracting cache usage from
> the total memory usage. The API does not perform such a calculation but rather
> provides the total memory usage and the amount from the cache so that clients
> can use the data as needed. The cache usage is defined as the value of
> `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts.
>
> On Docker 19.03 and older, the cache usage was defined as the value of `cache`
> field. On cgroup v2 hosts, the cache usage is defined as the value of
> `inactive_file` field.
2024-08-16 05:02:10 -04:00
> [!NOTE]
2020-04-19 09:43:08 -04:00
> The `PIDS` column contains the number of processes and kernel threads created
> by that container. Threads is the term used by Linux kernel. Other equivalent
> terms are "lightweight process" or "kernel task", etc. A large number in the
> `PIDS` column combined with a small number of processes (as reported by `ps`
> or `top`) may indicate that something in the container is creating many threads.
2018-05-08 15:16:15 -04:00
2015-10-03 08:53:25 -04:00
## Examples
2016-09-07 19:08:51 -04:00
Running `docker stats` on all running containers against a Linux daemon.
2015-10-03 08:53:25 -04:00
2021-08-21 08:54:14 -04:00
```console
2017-02-07 18:42:48 -05:00
$ docker stats
2017-09-27 12:24:26 -04:00
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9
67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2
e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1
4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2
2017-02-07 18:42:48 -05:00
```
2015-06-21 16:41:38 -04:00
2023-01-06 11:26:24 -05:00
If you don't [specify a format string using `--format` ](#format ), the
2018-01-31 20:05:54 -05:00
following columns are shown.
| Column name | Description |
|---------------------------|-----------------------------------------------------------------------------------------------|
| `CONTAINER ID` and `Name` | the ID and name of the container |
| `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using |
| `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use |
2021-05-22 23:21:38 -04:00
| `NET I/O` | The amount of data the container has received and sent over its network interface |
| `BLOCK I/O` | The amount of data the container has written to and read from block devices on the host |
2018-01-31 20:05:54 -05:00
| `PIDs` | the number of processes or threads the container has created |
2016-09-07 19:08:51 -04:00
Running `docker stats` on multiple containers by name and id against a Linux daemon.
2015-06-21 16:41:38 -04:00
2021-08-21 08:54:14 -04:00
```console
2017-09-27 12:24:26 -04:00
$ docker stats awesome_brattain 67b2525d8ad1
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9
67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2
2017-02-07 18:42:48 -05:00
```
2016-09-07 19:08:51 -04:00
2023-12-13 18:06:16 -05:00
Running `docker stats` on container with name `nginx` and getting output in `json` format.
2021-12-12 17:39:33 -05:00
```console
$ docker stats nginx --no-stream --format "{{ json . }}"
{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"}
```
2023-12-13 18:06:16 -05:00
Running `docker stats` with customized format on all (running and stopped) containers.
2017-02-15 01:20:30 -05:00
2021-08-21 08:54:14 -04:00
```console
2023-02-14 05:06:30 -05:00
$ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 humble_visvesvaraya big_heisenberg
2017-09-27 12:24:26 -04:00
CONTAINER CPU % MEM USAGE / LIMIT
fervent_panini 0.00% 56KiB / 15.57GiB
5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB
2023-02-14 05:06:30 -05:00
humble_visvesvaraya 0.00% 0B / 0B
2017-09-27 12:24:26 -04:00
big_heisenberg 0.00% 0B / 0B
2017-02-15 01:20:30 -05:00
```
2023-02-14 05:06:30 -05:00
`humble_visvesvaraya` and `big_heisenberg` are stopped containers in the above example.
2017-02-15 01:20:30 -05:00
2016-09-07 19:08:51 -04:00
Running `docker stats` on all running containers against a Windows daemon.
2017-02-07 18:42:48 -05:00
```powershell
PS E:\> docker stats
2017-09-27 12:24:26 -04:00
CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O
2017-02-07 18:42:48 -05:00
09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB
9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB
3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB
```
2016-09-07 19:08:51 -04:00
Running `docker stats` on multiple containers by name and id against a Windows daemon.
2017-02-07 18:42:48 -05:00
```powershell
PS E:\> docker ps -a
2017-09-27 12:24:26 -04:00
CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES
3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky
9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson
09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley
2017-02-07 18:42:48 -05:00
PS E:\> docker stats 3f214c61ad1d mad_wilson
2017-09-27 12:24:26 -04:00
CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O
3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB
9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB
2017-02-07 18:42:48 -05:00
```
2016-09-25 10:07:15 -04:00
2023-01-06 13:28:29 -05:00
### <a name="format"></a> Format the output (--format)
2016-09-25 10:07:15 -04:00
The formatting option (`--format`) pretty prints container output
using a Go template.
Valid placeholders for the Go template are listed below:
2022-03-30 08:33:44 -04:00
| Placeholder | Description |
|--------------|----------------------------------------------|
| `.Container` | Container name or ID (user input) |
| `.Name` | Container name |
| `.ID` | Container ID |
| `.CPUPerc` | CPU percentage |
| `.MemUsage` | Memory usage |
| `.NetIO` | Network IO |
| `.BlockIO` | Block IO |
| `.MemPerc` | Memory percentage (Not available on Windows) |
| `.PIDs` | Number of PIDs (Not available on Windows) |
2016-09-25 10:07:15 -04:00
When using the `--format` option, the `stats` command either
outputs the data exactly as the template declares or, when using the
`table` directive, includes column headers as well.
The following example uses a template without headers and outputs the
2020-04-19 11:23:09 -04:00
`Container` and `CPUPerc` entries separated by a colon (`:`) for all images:
2016-09-25 10:07:15 -04:00
2021-08-21 08:54:14 -04:00
```console
2016-09-25 10:07:15 -04:00
$ docker stats --format "{{.Container}}: {{.CPUPerc}}"
09d3bb5b1604: 6.61%
9db7aa4d986d: 9.19%
3f214c61ad1d: 0.00%
```
To list all containers statistics with their name, CPU percentage and memory
usage in a table format you can use:
2021-08-21 08:54:14 -04:00
```console
2016-09-25 10:07:15 -04:00
$ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
CONTAINER CPU % PRIV WORKING SET
1285939c1fd3 0.07% 796 KiB / 64 MiB
9c76f7834ae2 0.07% 2.746 MiB / 64 MiB
d1ea048f04e4 0.03% 4.583 MiB / 64 MiB
```
2017-09-27 12:24:26 -04:00
The default format is as follows:
On Linux:
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}"
On Windows:
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"
