/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 thanio_service_bytes_recursivecpu_stats:cpu_usage.percpu_usagememory_stats:max_usageandfailcntAlso,memory_stats.statsfields 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(cgroups v1) - used_memory =
memory_stats.usage - memory_stats.stats.inactive_file(cgroups v2) - 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)orcpu_stats.online_cpus - CPU usage % =
(cpu_delta / system_cpu_delta) * number_cpus * 100.0
Connection and access
API connection and authentication guidance
/v1.57
No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.
Parameters
id
path
Required
Type:
string
All schema constraints and annotations
{
"type": "string"
}stream
query
Type:
boolean
All schema constraints and annotations
{
"default": true,
"type": "boolean"
}one-shot
query
stream=false.Type:
boolean
All schema constraints and annotations
{
"default": false,
"type": "boolean"
}Request and responses
Response
200
application/json
Schema:
ContainerStatsResponse
Response
404
application/json
Schema:
ErrorResponse
Example
{
"message": "No such container: c2ada9df5af8"
}Response
500
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Referenced schemas
#/components/schemas/ContainerStatsResponse
#/components/schemas/ErrorResponse
Complete operation contract
{
"description": "This endpoint returns a live stream of a container’s resource usage\nstatistics.\n\nThe `precpu_stats` is the CPU statistic of the *previous* read, and is\nused to calculate the CPU usage percentage. It is not an exact copy\nof the `cpu_stats` field.\n\nIf either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is\nnil then for compatibility with older daemons the length of the\ncorresponding `cpu_usage.percpu_usage` array should be used.\n\nOn a cgroup v2 host, the following fields are not set\n* `blkio_stats`: all fields other than `io_service_bytes_recursive`\n* `cpu_stats`: `cpu_usage.percpu_usage`\n* `memory_stats`: `max_usage` and `failcnt`\nAlso, `memory_stats.stats` fields are incompatible with cgroup v1.\n\nTo calculate the values shown by the `stats` command of the docker cli tool\nthe following formulas can be used:\n* used_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)\n* used_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)\n* available_memory = `memory_stats.limit`\n* Memory usage % = `(used_memory / available_memory) * 100.0`\n* cpu_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`\n* system_cpu_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`\n* number_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`\n* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`\n",
"operationId": "ContainerStats",
"parameters": [
{
"description": "ID or name of the container",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Stream the output. If false, the stats will be output once and then\nit will disconnect.\n",
"in": "query",
"name": "stream",
"schema": {
"default": true,
"type": "boolean"
}
},
{
"description": "Only get a single stat instead of waiting for 2 cycles. Must be used\nwith `stream=false`.\n",
"in": "query",
"name": "one-shot",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContainerStatsResponse"
}
}
},
"description": "no error"
},
"404": {
"content": {
"application/json": {
"example": {
"message": "No such container: c2ada9df5af8"
},
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "no such container"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "server error"
}
},
"summary": "Get container stats based on resource usage",
"tags": [
"Container"
]
}