Merge pull request #26892 from ripcurld00d/stats_format_docs

Add documentation for docker stats --format

docs/admin/formatting.md

@@ -20,6 +20,7 @@ list of elements they support in their templates:
 - [Docker Log Tag formatting](logging/log_tags.md)
 - [Docker Network Inspect formatting](../reference/commandline/network_inspect.md)
 - [Docker PS formatting](../reference/commandline/ps.md#formatting)
+- [Docker Stats formatting](../reference/commandline/stats.md#formatting)
 - [Docker Volume Inspect formatting](../reference/commandline/volume_inspect.md)
 - [Docker Version formatting](../reference/commandline/version.md#examples)
 

docs/reference/commandline/stats.md

@@ -23,7 +23,7 @@ Options:
 
 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 want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint. 
+If you want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint.
 
 ## Examples
 
@@ -38,7 +38,7 @@ Running `docker stats` on all running containers against a Linux daemon.
 Running `docker stats` on multiple containers by name and id against a Linux daemon.
 
     $ docker stats fervent_panini 5acfcb1b4fd1
-    CONTAINER           CPU %               MEM USAGE/LIMIT     MEM %               NET I/O
+    CONTAINER           CPU %               MEM USAGE/LIMIT       MEM %               NET I/O
     5acfcb1b4fd1        0.00%               115.2 MiB/1.045 GiB   11.03%              1.422 kB/648 B
     fervent_panini      0.02%               11.08 MiB/1.045 GiB   1.06%               648 B/648 B
 
@@ -57,8 +57,53 @@ Running `docker stats` on multiple containers by name and id against a Windows d
     3f214c61ad1d        nanoserver          "cmd"               2 minutes ago       Up 2 minutes                            big_minsky
     9db7aa4d986d        windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            mad_wilson
     09d3bb5b1604        windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            affectionate_easley
-   
+
     PS E:\> docker stats 3f214c61ad1d mad_wilson
     CONTAINER           CPU %               PRIV WORKING SET    NET I/O             BLOCK I/O
     3f214c61ad1d        0.00%               46.25 MiB           76.3 kB / 7.92 kB   10.3 MB / 14.7 MB
-    mad_wilson          9.59%               40.09 MiB           27.6 kB / 8.81 kB   17 MB / 20.1 MB	
+    mad_wilson          9.59%               40.09 MiB           27.6 kB / 8.81 kB   17 MB / 20.1 MB
+
+## Formatting
+
+The formatting option (`--format`) pretty prints container output
+using a Go template.
+
+Valid placeholders for the Go template are listed below:
+
+Placeholder  | Description
+------------ | --------------------------------------------
+`.Container` | Container name or 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)
+
+
+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
+`Container` and `CPUPerc` entries separated by a colon for all images:
+
+```bash
+$ 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:
+
+```bash
+$ 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
+```

man/docker-stats.1.md

@@ -9,6 +9,7 @@ docker-stats - Display a live stream of one or more containers' resource usage s
 [**-a**|**--all**]
 [**--help**]
 [**--no-stream**]
+[**--format[="*TEMPLATE*"]**]
 [CONTAINER...]
 
 # DESCRIPTION
@@ -25,6 +26,17 @@ Display a live stream of one or more containers' resource usage statistics
 **--no-stream**=*true*|*false*
   Disable streaming stats and only pull the first result, default setting is false.
 
+**--format**="*TEMPLATE*"
+   Pretty-print containers statistics using a Go template.
+   Valid placeholders:
+      .Container - Container name or 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).
+
 # EXAMPLES
 
 Running `docker stats` on all running containers