github.com/AliyunContainerService/cli@v0.0.0-20181009023821-814ced4b30d0/docs/reference/commandline/stats.md (about) 1 --- 2 title: "stats" 3 description: "The stats command description and usage" 4 keywords: "container, resource, statistics" 5 --- 6 7 <!-- This file is maintained within the docker/cli GitHub 8 repository at https://github.com/docker/cli/. Make all 9 pull requests against that repo. If you see this file in 10 another repository, consider it read-only there, as it will 11 periodically be overwritten by the definitive file. Pull 12 requests which include edits to this file in other repositories 13 will be rejected. 14 --> 15 16 # stats 17 18 ```markdown 19 Usage: docker stats [OPTIONS] [CONTAINER...] 20 21 Display a live stream of container(s) resource usage statistics 22 23 Options: 24 -a, --all Show all containers (default shows just running) 25 --format string Pretty-print images using a Go template 26 --help Print usage 27 --no-stream Disable streaming stats and only pull the first result 28 --no-trunc Don't truncate output 29 ``` 30 31 ## Description 32 33 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. 34 35 If you want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint. 36 37 > **Note**: On Linux, the Docker CLI reports memory usage by subtracting page 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 page cache so that clients can use the data as needed. 38 39 > **Note**: 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. 40 41 ## Examples 42 43 Running `docker stats` on all running containers against a Linux daemon. 44 45 ```bash 46 $ docker stats 47 48 CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS 49 b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 50 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 51 e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1 52 4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2 53 ``` 54 55 If you don't [specify a format string using `--format`](#formatting), the 56 following columns are shown. 57 58 | Column name | Description | 59 |---------------------------|-----------------------------------------------------------------------------------------------| 60 | `CONTAINER ID` and `Name` | the ID and name of the container | 61 | `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using | 62 | `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use | 63 | `NET I/O` | The amount of data the container has sent and received over its network interface | 64 | `BLOCK I/O` | The amount of data the container has read to and written from block devices on the host | 65 | `PIDs` | the number of processes or threads the container has created | 66 67 Running `docker stats` on multiple containers by name and id against a Linux daemon. 68 69 ```bash 70 $ docker stats awesome_brattain 67b2525d8ad1 71 72 CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS 73 b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 74 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 75 ``` 76 77 Running `docker stats` with customized format on all (Running and Stopped) containers. 78 79 ```bash 80 $ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 drunk_visvesvaraya big_heisenberg 81 82 CONTAINER CPU % MEM USAGE / LIMIT 83 fervent_panini 0.00% 56KiB / 15.57GiB 84 5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB 85 drunk_visvesvaraya 0.00% 0B / 0B 86 big_heisenberg 0.00% 0B / 0B 87 ``` 88 89 `drunk_visvesvaraya` and `big_heisenberg` are stopped containers in the above example. 90 91 Running `docker stats` on all running containers against a Windows daemon. 92 93 ```powershell 94 PS E:\> docker stats 95 CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O 96 09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB 97 9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB 98 3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB 99 ``` 100 101 Running `docker stats` on multiple containers by name and id against a Windows daemon. 102 103 ```powershell 104 PS E:\> docker ps -a 105 CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES 106 3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky 107 9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson 108 09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley 109 110 PS E:\> docker stats 3f214c61ad1d mad_wilson 111 CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O 112 3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB 113 9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB 114 ``` 115 116 ### Formatting 117 118 The formatting option (`--format`) pretty prints container output 119 using a Go template. 120 121 Valid placeholders for the Go template are listed below: 122 123 Placeholder | Description 124 ------------ | -------------------------------------------- 125 `.Container` | Container name or ID (user input) 126 `.Name` | Container name 127 `.ID` | Container ID 128 `.CPUPerc` | CPU percentage 129 `.MemUsage` | Memory usage 130 `.NetIO` | Network IO 131 `.BlockIO` | Block IO 132 `.MemPerc` | Memory percentage (Not available on Windows) 133 `.PIDs` | Number of PIDs (Not available on Windows) 134 135 136 When using the `--format` option, the `stats` command either 137 outputs the data exactly as the template declares or, when using the 138 `table` directive, includes column headers as well. 139 140 The following example uses a template without headers and outputs the 141 `Container` and `CPUPerc` entries separated by a colon for all images: 142 143 ```bash 144 $ docker stats --format "{{.Container}}: {{.CPUPerc}}" 145 146 09d3bb5b1604: 6.61% 147 9db7aa4d986d: 9.19% 148 3f214c61ad1d: 0.00% 149 ``` 150 151 To list all containers statistics with their name, CPU percentage and memory 152 usage in a table format you can use: 153 154 ```bash 155 $ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" 156 157 CONTAINER CPU % PRIV WORKING SET 158 1285939c1fd3 0.07% 796 KiB / 64 MiB 159 9c76f7834ae2 0.07% 2.746 MiB / 64 MiB 160 d1ea048f04e4 0.03% 4.583 MiB / 64 MiB 161 ``` 162 163 The default format is as follows: 164 165 On Linux: 166 167 "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}" 168 169 On Windows: 170 171 "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" 172 173 174 > **Note**: On Docker 17.09 and older, the `{{.Container}}` column was used, in 175 > stead of `{{.ID}}\t{{.Name}}`.