@@ -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)

@@ -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"},

new file mode 100644

@@ -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>

@@ -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

@@ -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>`

@@ -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,

-takes no action and succeeds unconditionally.

+## stats

+

+    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

@@ -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")

+}