Skip to content

Commit 76141a0

Browse files
crosbymichaelcrosbymichael
committed
Add documentation for stats feature
Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
1 parent 2f46b76 commit 76141a0

File tree

7 files changed

+180
-4
lines changed

7 files changed

+180
-4
lines changed

‎api/client/commands.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2687,7 +2687,7 @@ func (s *containerStats) Display(w io.Writer) {
26872687
}
26882688

26892689
func (cli *DockerCli) CmdStats(args ...string) error {
2690-
cmd := cli.Subcmd("stats", "CONTAINER", "Stream the stats of a container", true)
2690+
cmd := cli.Subcmd("stats", "CONTAINER", "Display live container stats based on resource usage", true)
26912691
cmd.Require(flag.Min, 1)
26922692
utils.ParseFlags(cmd, args, true)
26932693

‎docker/flags.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ func init() {
9898
{"save", "Save an image to a tar archive"},
9999
{"search", "Search for an image on the Docker Hub"},
100100
{"start", "Start a stopped container"},
101-
{"stats", "Receive container stats"},
101+
{"stats", "Display live container stats based on resource usage"},
102102
{"stop", "Stop a running container"},
103103
{"tag", "Tag an image into a repository"},
104104
{"top", "Lookup the running processes of a container"},

‎docs/man/docker-stats.1.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
% DOCKER(1) Docker User Manuals
2+
% Docker Community
3+
% JUNE 2014
4+
# NAME
5+
docker-stats - Display live container stats based on resource usage.
6+
7+
# SYNOPSIS
8+
**docker top**
9+
[**--help**]
10+
[CONTAINERS]
11+
12+
# DESCRIPTION
13+
14+
Display live container stats based on resource usage.
15+
16+
# OPTIONS
17+
**--help**
18+
Print usage statement
19+
20+
# EXAMPLES
21+
22+
Run **docker stats** with multiple containers.
23+
24+
$ sudo docker stats redis1 redis2
25+
CONTAINER CPU % MEM USAGE/LIMIT MEM % NET I/O
26+
redis1 0.07% 796 KiB/64 MiB 1.21% 788 B/648 B
27+
redis2 0.07% 2.746 MiB/64 MiB 4.29% 1.266 KiB/648 B
28+
29+
# HISTORY
30+
April 2014, Originally compiled by William Henry (whenry at redhat dot com)
31+
based on docker.com source material and internal work.
32+
June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>

‎docs/sources/reference/api/docker_remote_api.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,12 @@ New endpoint to rename a container `id` to a new name.
6868
(`ReadonlyRootfs`) can be passed in the host config to mount the container's
6969
root filesystem as read only.
7070

71+
`GET /containers/(id)/stats`
72+
73+
**New!**
74+
This endpoint returns a stream of container stats based on resource usage.
75+
76+
7177
## v1.16
7278

7379
### Full Documentation

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -514,6 +514,94 @@ Status Codes:
514514
- **404** – no such container
515515
- **500** – server error
516516

517+
### Get container stats based on resource usage
518+
519+
`GET /containers/(id)/stats`
520+
521+
Returns a stream of json objects of the container's stats
522+
523+
**Example request**:
524+
525+
GET /containers/redis1/stats HTTP/1.1
526+
527+
**Example response**:
528+
529+
HTTP/1.1 200 OK
530+
Content-Type: application/json
531+
532+
{
533+
"read" : "2015-01-08T22:57:31.547920715Z",
534+
"network" : {
535+
"rx_dropped" : 0,
536+
"rx_bytes" : 648,
537+
"rx_errors" : 0,
538+
"tx_packets" : 8,
539+
"tx_dropped" : 0,
540+
"rx_packets" : 8,
541+
"tx_errors" : 0,
542+
"tx_bytes" : 648
543+
},
544+
"memory_stats" : {
545+
"stats" : {
546+
"total_pgmajfault" : 0,
547+
"cache" : 0,
548+
"mapped_file" : 0,
549+
"total_inactive_file" : 0,
550+
"pgpgout" : 414,
551+
"rss" : 6537216,
552+
"total_mapped_file" : 0,
553+
"writeback" : 0,
554+
"unevictable" : 0,
555+
"pgpgin" : 477,
556+
"total_unevictable" : 0,
557+
"pgmajfault" : 0,
558+
"total_rss" : 6537216,
559+
"total_rss_huge" : 6291456,
560+
"total_writeback" : 0,
561+
"total_inactive_anon" : 0,
562+
"rss_huge" : 6291456,
563+
"hierarchical_memory_limit" : 67108864,
564+
"total_pgfault" : 964,
565+
"total_active_file" : 0,
566+
"active_anon" : 6537216,
567+
"total_active_anon" : 6537216,
568+
"total_pgpgout" : 414,
569+
"total_cache" : 0,
570+
"inactive_anon" : 0,
571+
"active_file" : 0,
572+
"pgfault" : 964,
573+
"inactive_file" : 0,
574+
"total_pgpgin" : 477
575+
},
576+
"max_usage" : 6651904,
577+
"usage" : 6537216,
578+
"failcnt" : 0,
579+
"limit" : 67108864
580+
},
581+
"blkio_stats" : {},
582+
"cpu_stats" : {
583+
"cpu_usage" : {
584+
"percpu_usage" : [
585+
16970827,
586+
1839451,
587+
7107380,
588+
10571290
589+
],
590+
"usage_in_usermode" : 10000000,
591+
"total_usage" : 36488948,
592+
"usage_in_kernelmode" : 20000000
593+
},
594+
"system_cpu_usage" : 20091722000000000,
595+
"throttling_data" : {}
596+
}
597+
}
598+
599+
Status Codes:
600+
601+
- **200** – no error
602+
- **404** – no such container
603+
- **500** – server error
604+
517605
### Resize a container TTY
518606

519607
`POST /containers/(id)/resize?h=<height>&w=<width>`

‎docs/sources/reference/commandline/cli.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2001,8 +2001,28 @@ more details on finding shared images from the command line.
20012001
-a, --attach=false Attach container's STDOUT and STDERR and forward all signals to the process
20022002
-i, --interactive=false Attach container's STDIN
20032003

2004-
When run on a container that has already been started,
2005-
takes no action and succeeds unconditionally.
2004+
## stats
2005+
2006+
Usage: docker stats [CONTAINERS]
2007+
2008+
Display live container stats based on resource usage
2009+
2010+
--help=false Print usage
2011+
2012+
Running `docker stats` on two redis containers
2013+
2014+
$ sudo docker stats redis1 redis2
2015+
CONTAINER CPU % MEM USAGE/LIMIT MEM % NET I/O
2016+
redis1 0.07% 796 KiB/64 MiB 1.21% 788 B/648 B
2017+
redis2 0.07% 2.746 MiB/64 MiB 4.29% 1.266 KiB/648 B
2018+
2019+
2020+
When run on running containers live container stats will be streamed
2021+
back and displayed to the client. Stopped containers will not
2022+
receive any updates to their stats unless the container is started again.
2023+
2024+
> **Note:**
2025+
> If you want more in depth resource usage for a container use the API endpoint
20062026
20072027
## stop
20082028

‎integration-cli/docker_api_containers_test.go‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@ import (
99
"os/exec"
1010
"strings"
1111
"testing"
12+
"time"
1213

14+
"github.com/docker/docker/api/stats"
1315
"github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar"
1416
)
1517

@@ -251,3 +253,31 @@ func TestVolumesFromHasPriority(t *testing.T) {
251253

252254
logDone("container REST API - check VolumesFrom has priority")
253255
}
256+
257+
func TestGetContainerStats(t *testing.T) {
258+
defer deleteAllContainers()
259+
name := "statscontainer"
260+
261+
runCmd := exec.Command(dockerBinary, "run", "-d", "--name", name, "busybox", "top")
262+
out, _, err := runCommandWithOutput(runCmd)
263+
if err != nil {
264+
t.Fatalf("Error on container creation: %v, output: %q", err, out)
265+
}
266+
go func() {
267+
time.Sleep(4 * time.Second)
268+
runCommand(exec.Command(dockerBinary, "kill", name))
269+
runCommand(exec.Command(dockerBinary, "rm", name))
270+
}()
271+
272+
body, err := sockRequest("GET", "/containers/"+name+"/stats", nil)
273+
if err != nil {
274+
t.Fatalf("GET containers/stats sockRequest failed: %v", err)
275+
}
276+
277+
var s *stats.Stats
278+
if err := json.Unmarshal(body, &s); err != nil {
279+
t.Fatal(err)
280+
}
281+
282+
logDone("container REST API - check GET containers/stats")
283+
}

0 commit comments

Comments
 (0)