--- title: "Get container stats based on resource usage" method: GET path: "/containers/{id}/stats" tags: ["Container"] --- # Get container stats based on resource usage `GET /containers/{id}/stats` This endpoint returns a live stream of a container’s resource usage statistics. The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field. If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used. 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. To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used: * used_memory = `memory_stats.usage - memory_stats.stats.cache` * available_memory = `memory_stats.limit` * Memory usage % = `(used_memory / available_memory) * 100.0` * cpu_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage` * system_cpu_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage` * number_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus` * CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0` ## Path parameters - `id` string, required ## Query parameters - `stream` boolean - `one-shot` boolean ## Response `200` no error - ContainerStatsResponse — Statistics sample for a container. - `name` string, nullable — Name of the container - `id` string, nullable — ID of the container - `read` string, date-time — Date and time at which this sample was collected. The value is formatted as [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) with nano-seconds. - `preread` string, date-time — Date and time at which this first sample was collected. This field is not propagated if the "one-shot" option is set. If the "one-shot" option is set, this field may be omitted, empty, or set to a default date (`0001-01-01T00:00:00Z`). The value is formatted as [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) with nano-seconds. - `pids_stats` ContainerPidsStats, nullable — PidsStats contains Linux-specific stats of a container's process-IDs (PIDs). This type is Linux-specific and omitted for Windows containers. - `current` integer, nullable — Current is the number of PIDs in the cgroup. - `limit` integer, nullable — Limit is the hard limit on the number of pids in the cgroup. A "Limit" of 0 means that there is no limit. - `blkio_stats` ContainerBlkioStats, nullable — BlkioStats stores all IO service stats for data read and write. This type is Linux-specific and holds many fields that are specific to cgroups v1. On a cgroup v2 host, all fields other than `io_service_bytes_recursive` are omitted or `null`. This type is only populated on Linux and omitted for Windows containers. - `io_service_bytes_recursive` ContainerBlkioStatEntry[] - `major` integer - `minor` integer - `op` string - `value` integer - `io_serviced_recursive` ContainerBlkioStatEntry[], nullable — This field is only available when using Linux containers with cgroups v1. It is omitted or `null` when using cgroups v2. - `major` integer - `minor` integer - `op` string - `value` integer - `io_queue_recursive` ContainerBlkioStatEntry[], nullable — This field is only available when using Linux containers with cgroups v1. It is omitted or `null` when using cgroups v2. - `major` integer - `minor` integer - `op` string - `value` integer - `io_service_time_recursive` ContainerBlkioStatEntry[], nullable — This field is only available when using Linux containers with cgroups v1. It is omitted or `null` when using cgroups v2. - `major` integer - `minor` integer - `op` string - `value` integer - `io_wait_time_recursive` ContainerBlkioStatEntry[], nullable — This field is only available when using Linux containers with cgroups v1. It is omitted or `null` when using cgroups v2. - `major` integer - `minor` integer - `op` string - `value` integer - `io_merged_recursive` ContainerBlkioStatEntry[], nullable — This field is only available when using Linux containers with cgroups v1. It is omitted or `null` when using cgroups v2. - `major` integer - `minor` integer - `op` string - `value` integer - `io_time_recursive` ContainerBlkioStatEntry[], nullable — This field is only available when using Linux containers with cgroups v1. It is omitted or `null` when using cgroups v2. - `major` integer - `minor` integer - `op` string - `value` integer - `sectors_recursive` ContainerBlkioStatEntry[], nullable — This field is only available when using Linux containers with cgroups v1. It is omitted or `null` when using cgroups v2. - `major` integer - `minor` integer - `op` string - `value` integer - `num_procs` integer — The number of processors on the system. This field is Windows-specific and always zero for Linux containers. - `storage_stats` ContainerStorageStats, nullable — StorageStats is the disk I/O stats for read/write on Windows. This type is Windows-specific and omitted for Linux containers. - `read_count_normalized` integer, nullable - `read_size_bytes` integer, nullable - `write_count_normalized` integer, nullable - `write_size_bytes` integer, nullable - `cpu_stats` ContainerCPUStats, nullable — CPU related info of the container - `cpu_usage` ContainerCPUUsage, nullable — All CPU stats aggregated since container inception. - `total_usage` integer — Total CPU time consumed in nanoseconds (Linux) or 100's of nanoseconds (Windows). - `percpu_usage` integer[], nullable — Total CPU time (in nanoseconds) consumed per core (Linux). This field is Linux-specific when using cgroups v1. It is omitted when using cgroups v2 and Windows containers. - `usage_in_kernelmode` integer — Time (in nanoseconds) spent by tasks of the cgroup in kernel mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows). Not populated for Windows containers using Hyper-V isolation. - `usage_in_usermode` integer — Time (in nanoseconds) spent by tasks of the cgroup in user mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows). Not populated for Windows containers using Hyper-V isolation. - `system_cpu_usage` integer, nullable — System Usage. This field is Linux-specific and omitted for Windows containers. - `online_cpus` integer, nullable — Number of online CPUs. This field is Linux-specific and omitted for Windows containers. - `throttling_data` ContainerThrottlingData, nullable — CPU throttling stats of the container. This type is Linux-specific and omitted for Windows containers. - `periods` integer — Number of periods with throttling active. - `throttled_periods` integer — Number of periods when the container hit its throttling limit. - `throttled_time` integer — Aggregated time (in nanoseconds) the container was throttled for. - `precpu_stats` ContainerCPUStats, nullable — CPU related info of the container - `cpu_usage` ContainerCPUUsage, nullable — All CPU stats aggregated since container inception. - `total_usage` integer — Total CPU time consumed in nanoseconds (Linux) or 100's of nanoseconds (Windows). - `percpu_usage` integer[], nullable — Total CPU time (in nanoseconds) consumed per core (Linux). This field is Linux-specific when using cgroups v1. It is omitted when using cgroups v2 and Windows containers. - `usage_in_kernelmode` integer — Time (in nanoseconds) spent by tasks of the cgroup in kernel mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows). Not populated for Windows containers using Hyper-V isolation. - `usage_in_usermode` integer — Time (in nanoseconds) spent by tasks of the cgroup in user mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows). Not populated for Windows containers using Hyper-V isolation. - `system_cpu_usage` integer, nullable — System Usage. This field is Linux-specific and omitted for Windows containers. - `online_cpus` integer, nullable — Number of online CPUs. This field is Linux-specific and omitted for Windows containers. - `throttling_data` ContainerThrottlingData, nullable — CPU throttling stats of the container. This type is Linux-specific and omitted for Windows containers. - `periods` integer — Number of periods with throttling active. - `throttled_periods` integer — Number of periods when the container hit its throttling limit. - `throttled_time` integer — Aggregated time (in nanoseconds) the container was throttled for. - `memory_stats` ContainerMemoryStats — Aggregates all memory stats since container inception on Linux. Windows returns stats for commit and private working set only. - `usage` integer, nullable — Current `res_counter` usage for memory. This field is Linux-specific and omitted for Windows containers. - `max_usage` integer, nullable — Maximum usage ever recorded. This field is Linux-specific and only supported on cgroups v1. It is omitted when using cgroups v2 and for Windows containers. - `stats` object — All the stats exported via memory.stat. when using cgroups v2. This field is Linux-specific and omitted for Windows containers. - `failcnt` integer, nullable — Number of times memory usage hits limits. This field is Linux-specific and only supported on cgroups v1. It is omitted when using cgroups v2 and for Windows containers. - `limit` integer, nullable — This field is Linux-specific and omitted for Windows containers. - `commitbytes` integer, nullable — Committed bytes. This field is Windows-specific and omitted for Linux containers. - `commitpeakbytes` integer, nullable — Peak committed bytes. This field is Windows-specific and omitted for Linux containers. - `privateworkingset` integer, nullable — Private working set. This field is Windows-specific and omitted for Linux containers. - `networks` unknown ## Other responses - `404` — no such container - `500` — server error --- [API](https://skmtc.net/docker/apis/docker-engine-api.md) · [All operations](https://skmtc.net/docker/apis/docker-engine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/docker/docker-engine-api/versions/a181425ed19e/schema)