Unit of measure is missing for metrics endpoints

[embcla]

Is this a docs issue?

• [X] My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

I'm looking for the unit of measure used by many metrics endpoints exposed by the docker engine and used my metric streaming components like telegraf.

In telegraf's own documentation, here you can see an example

docker_container_cpu

tags:
engine_host
server_version
container_image
container_name
container_status
container_version
cpu
fields:
throttling_periods
throttling_throttled_periods
throttling_throttled_time
usage_in_kernelmode
usage_in_usermode
usage_system
usage_total
usage_percent
container_id

these usages are all missing their unit of measure, and when I query the DB I get numbers I can't make sense of. I then looked into the docker engine api and I am more confused: the latest mention of the usage_in_usermode endpoint is in v1.24, I couldn't find any mention in any more recent version.

And even in 1.24 docs, there is no mention of the unit of measure.

Maybe I anm missing something obvious here?

Location

https://docs.docker.com/engine/api/v1.24/

Suggestion

Create a specific page for metrics with all endpoints and their unit of measure

[thaJeztah]

Thanks for reporting! Hm.. yes, it looks like the swagger / OpenAPI file that's used for the API docs doesn't currently define a schema for the response; https://github.com/moby/moby/blob/v25.0.4/docs/api/v1.44.yaml#L7132-L7141, so currently (besides som "example" response), it only shows object;

I think that may have been done because the response differs between Windows and Linux daemons and because some of the fields returned are raw data originating from the kernel / cgroups (and information provided for various of those depend on kernel version and cgroups used (v1/v2)). But we should look if we can improve that; at least for fields that do not depend on cgroups / cgroup-versions.

For these specific fields, you can refer to the Go documentation for the underlyling structs used here's the links for the current (v25.0.2) release of the Docker Engine;

• github.com/docker/docker/api/types.CPUUsage (source-code: https://github.com/moby/moby/blob/v25.0.4/api/types/stats.go#L19)
• github.com/docker/docker/api/types.CPUStats (source-code: https://github.com/moby/moby/blob/v25.0.4/api/types/stats.go#L43)

Other stats-related structs can be found in the same file in the repository; https://github.com/moby/moby/blob/v25.0.4/api/types/stats.go

Some fields returned by the stats endpoint (as mentioned) may differ between platforms as they are collected from the underlying runtime (containerd, or the hcsshim runtime on Windows), and some of those are merely expose the underlying group data (for which you may have to refer to the Linux kernel documentation).

https://github.com/moby/moby/blob/v25.0.4/daemon/stats_unix.go#L89-L123 https://github.com/moby/moby/blob/v25.0.4/daemon/stats_windows.go#L45-L58

We should have a look though how much information we can add (or where needed, link to relevant (kernel) documentation).