docs: API: update "/containers/{id}/stats" description and examples for cgroups v2

[lantos1618]

Docker Engine API - Incorrect reporting Memory_stats.stats["cache"] not avaliable

Description

Docker engine api not reporting the correct details in
container/{{id}}/stats reporting json:
memory.stats is meant to have cache but doesn't. It could labled as anon

Reproduce

1. docker run --name myContainer nginx:alpine
2. curl -v --unix-socket /var/run/docker.sock http://localhost/containers/myContainer/stats

Expected behavior

When sending a GET request to containers/{{id}}/stats there is expected to be the following "cache" field on the memory_stats field.

...
"memory_stats": {
    "usage": 23123,
    "stats": {
       "cache": 123231,
       ...
   }
}

as defined in https://docs.docker.com/engine/api/v1.41/#tag/Container/operation/ContainerStats
I have tested it on linux and the reponse is correct as the api. On mac however the response is invalid

docker version

Client:
 Cloud integration: v1.0.24
 Version:           20.10.17
 API version:       1.41
 Go version:        go1.17.11
 Git commit:        100c701
 Built:             Mon Jun  6 23:04:45 2022
 OS/Arch:           darwin/arm64
 Context:           default
 Experimental:      true

Server: Docker Desktop 4.10.1 (82475)
 Engine:
  Version:          20.10.17
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.17.11
  Git commit:       a89b842
  Built:            Mon Jun  6 23:01:01 2022
  OS/Arch:          linux/arm64
  Experimental:     true
 containerd:
  Version:          1.6.6
  GitCommit:        10c12954828e7c7c9b6e0ea9b0c02b01407d3ae1
 runc:
  Version:          1.1.2
  GitCommit:        v1.1.2-0-ga916309
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

docker info

Client:
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc., v0.8.2)
  compose: Docker Compose (Docker Inc., v2.6.1)
  extension: Manages Docker extensions (Docker Inc., v0.2.7)
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc., 0.6.0)
  scan: Docker Scan (Docker Inc., v0.17.0)

Server:
 Containers: 1
  Running: 1
  Paused: 0
  Stopped: 0
 Images: 9
 Server Version: 20.10.17
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runtime.v1.linux runc io.containerd.runc.v2
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 10c12954828e7c7c9b6e0ea9b0c02b01407d3ae1
 runc version: v1.1.2-0-ga916309
 init version: de40ad0
 Security Options:
  seccomp
   Profile: default
  cgroupns
 Kernel Version: 5.10.104-linuxkit
 Operating System: Docker Desktop
 OSType: linux
 Architecture: aarch64
 CPUs: 5
 Total Memory: 7.653GiB
 Name: docker-desktop
 ID: 5XV3:EJDU:I6XT:TS2E:3M6Y:LIFL:VLA5:TTWL:4H6O:6TVC:PB22:YE4A
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 HTTP Proxy: http.docker.internal:3128
 HTTPS Proxy: http.docker.internal:3128
 No Proxy: hubproxy.docker.internal
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: true
 Insecure Registries:
  hubproxy.docker.internal:5000
  127.0.0.0/8
 Live Restore Enabled: false

Additional Info

No response

[AkihiroSuda]

Cgroup Version: 2

cgroup v2 provides different stats than v1, so this is not a bug

[thaJeztah]

Looks like this is documented in the endpoint description;

moby/api/swagger.yaml

Lines 6973 to 6977 in 572ca79

	On a cgroup v2 host, the following fields are not set
	* `blkio_stats`: all fields other than `io_service_bytes_recursive`
	* `cpu_stats`: `cpu_usage.percpu_usage`
	* `memory_stats`: `max_usage` and `failcnt`
	Also, `memory_stats.stats` fields are incompatible with cgroup v1.

But perhaps we should update the example response to match cgroups v2, as that's (becoming) the default for current Linux distributions.

[valkyr13]

can i pick this up? @lantos-lgtm

[lantos1618]

can i pick this up? @lantos-lgtm

I'm not on this. Looks like the docker internal teams are on this now though.

[AkihiroSuda]

@valkyr13 @lantos-lgtm
Anybody can submit PRs directly