moby--moby/client
Brian Goff ce1ceeb257 Add stats options to not prime the stats
Metrics collectors generally don't need the daemon to prime the stats
with something to compare since they already have something to compare
with.
Before this change, the API does 2 collection cycles (which takes
roughly 2s) in order to provide comparison for CPU usage over 1s. This
was primarily added so that `docker stats --no-stream` had something to
compare against.

Really the CLI should have just made a 2nd call and done the comparison
itself rather than forcing it on all API consumers.
That ship has long sailed, though.

With this change, clients can set an option to just pull a single stat,
which is *at least* a full second faster:

Old:
```
time curl --unix-socket
/go/src/github.com/docker/docker/bundles/test-integration-shell/docker.sock
http://./containers/test/stats?stream=false\&one-shot=false > /dev/null
2>&1

real0m1.864s
user0m0.005s
sys0m0.007s

time curl --unix-socket
/go/src/github.com/docker/docker/bundles/test-integration-shell/docker.sock
http://./containers/test/stats?stream=false\&one-shot=false > /dev/null
2>&1

real0m1.173s
user0m0.010s
sys0m0.006s
```

New:
```
time curl --unix-socket
/go/src/github.com/docker/docker/bundles/test-integration-shell/docker.sock
http://./containers/test/stats?stream=false\&one-shot=true > /dev/null
2>&1
real0m0.680s
user0m0.008s
sys0m0.004s

time curl --unix-socket
/go/src/github.com/docker/docker/bundles/test-integration-shell/docker.sock
http://./containers/test/stats?stream=false\&one-shot=true > /dev/null
2>&1

real0m0.156s
user0m0.007s
sys0m0.007s
```

This fixes issues with downstreams ability to use the stats API to
collect metrics.

Signed-off-by: Brian Goff <cpuguy83@gmail.com>
2020-02-28 09:54:37 -08:00
..
testdata
README.md Remove use of deprecated client.NewEnvClient() 2019-01-03 22:49:00 +01:00
build_cancel.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
build_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
checkpoint_create.go
checkpoint_create_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
checkpoint_delete.go
checkpoint_delete_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
checkpoint_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
checkpoint_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
client.go fix client.HTTPClient() not returning a copy 2019-08-06 00:45:45 +02:00
client_deprecated.go Move deprecated client constructors to a separate file 2019-01-21 15:27:52 +01:00
client_mock_test.go
client_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
client_unix.go Allow client consumers like traefik to compile on illumos 2019-11-23 19:28:45 +01:00
client_windows.go
config_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
config_create_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
config_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
config_inspect_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
config_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
config_list_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
config_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
config_remove_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
config_update.go
config_update_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
container_attach.go
container_commit.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_commit_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_copy.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_copy_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
container_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_create_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_diff.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_diff_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_exec.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_exec_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
container_export.go
container_export_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_inspect_test.go TestContainerInspectNode: document test as being for classic swarm 2020-01-06 12:25:00 +01:00
container_kill.go
container_kill_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_list.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
container_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_logs.go Improve GetTimestamp parsing 2018-05-20 13:07:17 +02:00
container_logs_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
container_pause.go
container_pause_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_prune_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
container_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_remove_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
container_rename.go
container_rename_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_resize.go
container_resize_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_restart.go
container_restart_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_start.go
container_start_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_stats.go Add stats options to not prime the stats 2020-02-28 09:54:37 -08:00
container_stats_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_stop.go Merge pull request #36874 from kolyshkin/stop-timeout 2018-05-30 13:38:42 -04:00
container_stop_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_top.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_top_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_unpause.go
container_unpause_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_update.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_update_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
container_wait.go
container_wait_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
disk_usage.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
disk_usage_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
distribution_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
distribution_inspect_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
errors.go Keep old "notfound" interface for backward compatibility 2019-03-16 00:42:36 +01:00
events.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
events_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
hijack.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
hijack_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
image_build.go builder-next: allow outputs configuration 2019-03-19 10:28:30 -07:00
image_build_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_create.go
image_create_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_history.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_history_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_import.go client: normalize comment formatting 2019-11-27 15:44:49 +01:00
image_import_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_inspect_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_list.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
image_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_load.go
image_load_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_prune_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
image_pull.go Use errdefs for handling errors in client 2019-03-16 00:42:42 +01:00
image_pull_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_push.go client.ImagePush(): default to ":latest" instead of "all tags" 2019-12-10 12:24:14 +01:00
image_push_test.go client.ImagePush(): default to ":latest" instead of "all tags" 2019-12-10 12:24:14 +01:00
image_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_remove_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
image_save.go
image_save_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_search.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_search_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
image_tag.go
image_tag_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
info.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
info_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
interface.go Add stats options to not prime the stats 2020-02-28 09:54:37 -08:00
interface_experimental.go
interface_stable.go
login.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
network_connect.go
network_connect_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
network_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
network_create_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
network_disconnect.go
network_disconnect_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
network_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
network_inspect_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
network_list.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
network_list_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
network_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
network_prune_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
network_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
network_remove_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
node_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
node_inspect_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
node_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
node_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
node_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
node_remove_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
node_update.go
node_update_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
options.go Merge pull request #39032 from thaJeztah/improve_version_negotiation 2019-04-20 13:34:22 +02:00
options_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
ping.go remove extra space in code comment in ping.go 2020-01-20 00:04:53 -05:00
ping_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
plugin_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
plugin_disable.go
plugin_disable_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
plugin_enable.go
plugin_enable_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
plugin_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
plugin_inspect_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
plugin_install.go Use errdefs for handling errors in client 2019-03-16 00:42:42 +01:00
plugin_list.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
plugin_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
plugin_push.go
plugin_push_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
plugin_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
plugin_remove_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
plugin_set.go
plugin_set_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
plugin_upgrade.go
request.go client: use constants for http methods 2019-10-13 17:30:21 +02:00
request_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
secret_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
secret_create_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
secret_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
secret_inspect_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
secret_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
secret_list_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
secret_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
secret_remove_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
secret_update.go
secret_update_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
service_create.go goimports: fix imports 2019-09-18 12:56:54 +02:00
service_create_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
service_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
service_inspect_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
service_list.go Add support for sending down service Running and Desired task counts 2019-10-14 10:43:00 -05:00
service_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
service_logs.go Improve GetTimestamp parsing 2018-05-20 13:07:17 +02:00
service_logs_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
service_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
service_remove_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
service_update.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
service_update_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
swarm_get_unlock_key.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_get_unlock_key_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
swarm_init.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_init_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
swarm_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_inspect_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
swarm_join.go
swarm_join_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
swarm_leave.go
swarm_leave_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
swarm_unlock.go
swarm_unlock_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
swarm_update.go
swarm_update_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
task_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
task_inspect_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
task_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
task_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
task_logs.go
transport.go
utils.go
version.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_create_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00
volume_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_inspect_test.go bump gotest.tools v3.0.1 for compatibility with Go 1.14 2020-02-11 00:06:42 +01:00
volume_list.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
volume_list_test.go client: reduce string-matching in tests 2019-10-13 17:00:40 +02:00
volume_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_remove.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_remove_test.go Merge pull request #40080 from thaJeztah/client_string_matching 2019-10-17 11:38:00 -07:00

README.md

Go client for the Docker Engine API

The docker command uses this package to communicate with the daemon. It can also be used by your own Go applications to do anything the command-line interface does  running containers, pulling images, managing swarms, etc.

For example, to list running containers (the equivalent of docker ps):

package main

import (
	"context"
	"fmt"

	"github.com/docker/docker/api/types"
	"github.com/docker/docker/client"
)

func main() {
	cli, err := client.NewClientWithOpts(client.FromEnv)
	if err != nil {
		panic(err)
	}

	containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
	if err != nil {
		panic(err)
	}

	for _, container := range containers {
		fmt.Printf("%s %s\n", container.ID[:10], container.Image)
	}
}

Full documentation is available on GoDoc.