Add documentation for docker stats --format

Signed-off-by: Boaz Shuster <ripcurld.github@gmail.com>

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

@@ -62,3 +62,48 @@ Running `docker stats` on multiple containers by name and id against a Windows d
     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
+
+## 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