API: container stats docs missing information

[vivanov-dp]

Problem description

The API docs about container stats are missing important bits of information.
I had to dig into the source code for the cli stats command (here: https://github.com/docker/cli/blob/19.03/cli/command/container/stats_helpers.go#L166) to discover that memory usage is actually memory_stats.usage - memory_stats.stats.cache, so percentage used is calculated as (memory_stats.usage - memory_stats.stats.cache) / memory_stats.limit * 100.0
and that cpu usage has to be muliplied by the number of cpus - (diff(cpu_stats.cpu_usage.total_usage) / diff(cpu_stats.system_cpu_usage)) * number_cpus * 100.0.

Problem location

URL: https://docs.docker.com/engine/api/v1.40/#operation/ContainerStats

Suggestions for a fix

An example containing the above calculations would be nice, even nicer if it is accompanied by an explanation of what exactly these values represent.

[thaJeztah]

The API docs are generated from the swagger file in the upstream moby repository; https://github.com/moby/moby/blob/840a12ac90fd41bc0fc170868566b4c422dd404c/api/swagger.yaml#L5979-L5997

Perhaps you're interested in opening a pull request to improve the description?

[vivanov-dp]

Alright, I will look into adding the example there

[docker-robott]

Closed issues are locked after 30 days of inactivity.
This helps our team focus on active issues.

If you have found a problem that seems similar to this, please open a new issue.

/lifecycle locked