From 76141a00779880368b15ef2a5ffd28a80e4637df Mon Sep 17 00:00:00 2001 From: Michael Crosby Date: Mon, 19 Jan 2015 16:10:26 -0800 Subject: [PATCH] Add documentation for stats feature Signed-off-by: Michael Crosby --- api/client/commands.go | 2 +- docker/flags.go | 2 +- docs/man/docker-stats.1.md | 32 +++++++ .../reference/api/docker_remote_api.md | 6 ++ .../reference/api/docker_remote_api_v1.17.md | 88 +++++++++++++++++++ docs/sources/reference/commandline/cli.md | 24 ++++- integration-cli/docker_api_containers_test.go | 30 +++++++ 7 files changed, 180 insertions(+), 4 deletions(-) create mode 100644 docs/man/docker-stats.1.md diff --git a/api/client/commands.go b/api/client/commands.go index 07554ed609481..40de033d42b38 100644 --- a/api/client/commands.go +++ b/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) diff --git a/docker/flags.go b/docker/flags.go index 8db636e5cef69..525e8cbfd6d8b 100644 --- a/docker/flags.go +++ b/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"}, diff --git a/docs/man/docker-stats.1.md b/docs/man/docker-stats.1.md new file mode 100644 index 0000000000000..991b3d9f1774f --- /dev/null +++ b/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 diff --git a/docs/sources/reference/api/docker_remote_api.md b/docs/sources/reference/api/docker_remote_api.md index a36133795cdde..2d52d53b8d8c1 100644 --- a/docs/sources/reference/api/docker_remote_api.md +++ b/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 diff --git a/docs/sources/reference/api/docker_remote_api_v1.17.md b/docs/sources/reference/api/docker_remote_api_v1.17.md index a44dcbf3a9269..77e9a87133c92 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.17.md +++ b/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=&w=` diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 36d0b18cc3871..b8af02da304f3 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/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, -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 diff --git a/integration-cli/docker_api_containers_test.go b/integration-cli/docker_api_containers_test.go index 8b0b8fd696be8..43ae8edde5203 100644 --- a/integration-cli/docker_api_containers_test.go +++ b/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") +}