mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
Add documentation for stats feature
Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
This commit is contained in:
Michael Crosby
parent
2f46b7601a
commit
76141a0077
7 changed files with 180 additions and 4 deletions
|
|
@ -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"},
|
||||
|
|
|
|||
32
docs/man/docker-stats.1.md
Normal file
32
docs/man/docker-stats.1.md
Normal file
|
|
@ -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")
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue