Add documentation for stats feature

Signed-off-by: Michael Crosby <crosbymichael@gmail.com>

api/client/commands.go

@@ -2687,7 +2687,7 @@ func (s *containerStats) Display(w io.Writer) {
 }
 
 func (cli *DockerCli) CmdStats(args ...string) error {
-	cmd := cli.Subcmd("stats", "CONTAINER", "Stream the stats of a container", true)
+	cmd := cli.Subcmd("stats", "CONTAINER", "Display live container stats based on resource usage", true)
 	cmd.Require(flag.Min, 1)
 	utils.ParseFlags(cmd, args, true)
 

docker/flags.go

@@ -98,7 +98,7 @@ func init() {
 			{"save", "Save an image to a tar archive"},
 			{"search", "Search for an image on the Docker Hub"},
 			{"start", "Start a stopped container"},
-			{"stats", "Receive container stats"},
+			{"stats", "Display live container stats based on resource usage"},
 			{"stop", "Stop a running container"},
 			{"tag", "Tag an image into a repository"},
 			{"top", "Lookup the running processes of a container"},

docs/man/docker-stats.1.md

@@ -0,0 +1,32 @@
+% DOCKER(1) Docker User Manuals
+% Docker Community
+% JUNE 2014
+# NAME
+docker-stats - Display live container stats based on resource usage.
+
+# SYNOPSIS
+**docker top**
+[**--help**]
+[CONTAINERS]
+
+# DESCRIPTION
+
+Display live container stats based on resource usage.
+
+# OPTIONS
+**--help**
+  Print usage statement
+
+# EXAMPLES
+
+Run **docker stats** with multiple containers.
+
+    $ sudo docker stats redis1 redis2
+    CONTAINER           CPU %               MEM USAGE/LIMIT     MEM %               NET I/O
+    redis1              0.07%               796 KiB/64 MiB      1.21%               788 B/648 B
+    redis2              0.07%               2.746 MiB/64 MiB    4.29%               1.266 KiB/648 B
+
+# HISTORY
+April 2014, Originally compiled by William Henry (whenry at redhat dot com)
+based on docker.com source material and internal work.
+June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>

docs/sources/reference/api/docker_remote_api.md

@@ -68,6 +68,12 @@ New endpoint to rename a container `id` to a new name.
 (`ReadonlyRootfs`) can be passed in the host config to mount the container's
 root filesystem as read only.
 
+`GET /containers/(id)/stats`
+
+**New!**
+This endpoint returns a stream of container stats based on resource usage.
+
+
 ## v1.16
 
 ### Full Documentation

docs/sources/reference/api/docker_remote_api_v1.17.md

@@ -514,6 +514,94 @@ Status Codes:
 -   **404** – no such container
 -   **500** – server error
 
+### Get container stats based on resource usage
+
+`GET /containers/(id)/stats`
+
+Returns a stream of json objects of the container's stats
+
+**Example request**:
+
+        GET /containers/redis1/stats HTTP/1.1
+
+**Example response**:
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {
+           "read" : "2015-01-08T22:57:31.547920715Z",
+           "network" : {
+              "rx_dropped" : 0,
+              "rx_bytes" : 648,
+              "rx_errors" : 0,
+              "tx_packets" : 8,
+              "tx_dropped" : 0,
+              "rx_packets" : 8,
+              "tx_errors" : 0,
+              "tx_bytes" : 648
+           },
+           "memory_stats" : {
+              "stats" : {
+                 "total_pgmajfault" : 0,
+                 "cache" : 0,
+                 "mapped_file" : 0,
+                 "total_inactive_file" : 0,
+                 "pgpgout" : 414,
+                 "rss" : 6537216,
+                 "total_mapped_file" : 0,
+                 "writeback" : 0,
+                 "unevictable" : 0,
+                 "pgpgin" : 477,
+                 "total_unevictable" : 0,
+                 "pgmajfault" : 0,
+                 "total_rss" : 6537216,
+                 "total_rss_huge" : 6291456,
+                 "total_writeback" : 0,
+                 "total_inactive_anon" : 0,
+                 "rss_huge" : 6291456,
+                 "hierarchical_memory_limit" : 67108864,
+                 "total_pgfault" : 964,
+                 "total_active_file" : 0,
+                 "active_anon" : 6537216,
+                 "total_active_anon" : 6537216,
+                 "total_pgpgout" : 414,
+                 "total_cache" : 0,
+                 "inactive_anon" : 0,
+                 "active_file" : 0,
+                 "pgfault" : 964,
+                 "inactive_file" : 0,
+                 "total_pgpgin" : 477
+              },
+              "max_usage" : 6651904,
+              "usage" : 6537216,
+              "failcnt" : 0,
+              "limit" : 67108864
+           },
+           "blkio_stats" : {},
+           "cpu_stats" : {
+              "cpu_usage" : {
+                 "percpu_usage" : [
+                    16970827,
+                    1839451,
+                    7107380,
+                    10571290
+                 ],
+                 "usage_in_usermode" : 10000000,
+                 "total_usage" : 36488948,
+                 "usage_in_kernelmode" : 20000000
+              },
+              "system_cpu_usage" : 20091722000000000,
+              "throttling_data" : {}
+           }
+        }
+
+Status Codes:
+
+-   **200** – no error
+-   **404** – no such container
+-   **500** – server error
+
 ### Resize a container TTY
 
 `POST /containers/(id)/resize?h=<height>&w=<width>`

docs/sources/reference/commandline/cli.md

@@ -2001,8 +2001,28 @@ more details on finding shared images from the command line.
       -a, --attach=false         Attach container's STDOUT and STDERR and forward all signals to the process
       -i, --interactive=false    Attach container's STDIN
 
-When run on a container that has already been started,
+## stats
-takes no action and succeeds unconditionally.
+
+    Usage: docker stats [CONTAINERS]
+
+    Display live container stats based on resource usage
+
+      --help=false       Print usage
+
+Running `docker stats` on two redis containers
+
+    $ sudo docker stats redis1 redis2
+    CONTAINER           CPU %               MEM USAGE/LIMIT     MEM %               NET I/O
+    redis1              0.07%               796 KiB/64 MiB      1.21%               788 B/648 B
+    redis2              0.07%               2.746 MiB/64 MiB    4.29%               1.266 KiB/648 B
+
+
+When run on running containers live container stats will be streamed
+back and displayed to the client.  Stopped containers will not 
+receive any updates to their stats unless the container is started again.
+
+> **Note:**
+> If you want more in depth resource usage for a container use the API endpoint
 
 ## stop
 

integration-cli/docker_api_containers_test.go

@@ -9,7 +9,9 @@ import (
 	"os/exec"
 	"strings"
 	"testing"
+	"time"
 
+	"github.com/docker/docker/api/stats"
 	"github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar"
 )
 
@@ -251,3 +253,31 @@ func TestVolumesFromHasPriority(t *testing.T) {
 
 	logDone("container REST API - check VolumesFrom has priority")
 }
+
+func TestGetContainerStats(t *testing.T) {
+	defer deleteAllContainers()
+	name := "statscontainer"
+
+	runCmd := exec.Command(dockerBinary, "run", "-d", "--name", name, "busybox", "top")
+	out, _, err := runCommandWithOutput(runCmd)
+	if err != nil {
+		t.Fatalf("Error on container creation: %v, output: %q", err, out)
+	}
+	go func() {
+		time.Sleep(4 * time.Second)
+		runCommand(exec.Command(dockerBinary, "kill", name))
+		runCommand(exec.Command(dockerBinary, "rm", name))
+	}()
+
+	body, err := sockRequest("GET", "/containers/"+name+"/stats", nil)
+	if err != nil {
+		t.Fatalf("GET containers/stats sockRequest failed: %v", err)
+	}
+
+	var s *stats.Stats
+	if err := json.Unmarshal(body, &s); err != nil {
+		t.Fatal(err)
+	}
+
+	logDone("container REST API - check GET containers/stats")
+}