Get container stats based on resource usage

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

idstring required

ID or name of the container

streamboolean

Stream the output. If false, the stats will be output once and then it will disconnect.

one-shotboolean

Only get a single stat instead of waiting for 2 cycles. Must be used with stream=false.

Response

no error

namestring nullable

Name of the container

idstring nullable

ID of the container

readstring date-time

Date and time at which this sample was collected. The value is formatted as RFC 3339 with nano-seconds.

prereadstring 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 with nano-seconds.

num_procsinteger

The number of processors on the system.

This field is Windows-specific and always zero for Linux containers.

{"stackTrail":"components:schemas:ContainerStatsResponse:properties:networks","oasType":"schema","type":"unknown","description":"Network statistics for the container per interface.\n\nThis field is omitted if the container has no networking enabled.\n","example":{"eth0":{"rx_bytes":5338,"rx_dropped":0,"rx_errors":0,"rx_packets":36,"tx_bytes":648,"tx_dropped":0,"tx_errors":0,"tx_packets":8},"eth5":{"rx_bytes":4641,"rx_dropped":0,"rx_errors":0,"rx_packets":26,"tx_bytes":690,"tx_dropped":0,"tx_errors":0,"tx_packets":9}},"nullable":true}

Example response

{
  "name": "boring_wozniak",
  "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
  "read": "2025-01-16T13:55:22.165243637Z",
  "preread": "2025-01-16T13:55:21.160452595Z",
  "pids_stats": {
    "current": 5,
    "limit": 18446744073709552000
  },
  "blkio_stats": {
    "io_service_bytes_recursive": [
      {
        "major": 254,
        "minor": 0,
        "op": "read",
        "value": 7593984
      },
      {
        "major": 254,
        "minor": 0,
        "op": "write",
        "value": 100
      }
    ],
    "io_serviced_recursive": null,
    "io_queue_recursive": null,
    "io_service_time_recursive": null,
    "io_wait_time_recursive": null,
    "io_merged_recursive": null,
    "io_time_recursive": null,
    "sectors_recursive": null
  },
  "num_procs": 16,
  "storage_stats": {
    "read_count_normalized": 7593984,
    "read_size_bytes": 7593984,
    "write_count_normalized": 7593984,
    "write_size_bytes": 7593984
  },
  "cpu_stats": {
    "cpu_usage": {
      "total_usage": 29912000,
      "percpu_usage": [
        29912000
      ],
      "usage_in_kernelmode": 21994000,
      "usage_in_usermode": 7918000
    },
    "system_cpu_usage": 5,
    "online_cpus": 5
  },
  "precpu_stats": {
    "cpu_usage": {
      "total_usage": 29912000,
      "percpu_usage": [
        29912000
      ],
      "usage_in_kernelmode": 21994000,
      "usage_in_usermode": 7918000
    },
    "system_cpu_usage": 5,
    "online_cpus": 5
  },
  "memory_stats": {
    "stats": {
      "active_anon": 1572864,
      "active_file": 5115904,
      "anon": 1572864,
      "anon_thp": 0,
      "file": 7626752,
      "file_dirty": 0,
      "file_mapped": 2723840,
      "file_writeback": 0,
      "inactive_anon": 0,
      "inactive_file": 2510848,
      "kernel_stack": 16384,
      "pgactivate": 0,
      "pgdeactivate": 0,
      "pgfault": 2042,
      "pglazyfree": 0,
      "pglazyfreed": 0,
      "pgmajfault": 45,
      "pgrefill": 0,
      "pgscan": 0,
      "pgsteal": 0,
      "shmem": 0,
      "slab": 1180928,
      "slab_reclaimable": 725576,
      "slab_unreclaimable": 455352,
      "sock": 0,
      "thp_collapse_alloc": 0,
      "thp_fault_alloc": 1,
      "unevictable": 0,
      "workingset_activate": 0,
      "workingset_nodereclaim": 0,
      "workingset_refault": 0
    },
    "limit": 8217579520
  },
  "networks": {
    "eth0": {
      "rx_bytes": 5338,
      "rx_dropped": 0,
      "rx_errors": 0,
      "rx_packets": 36,
      "tx_bytes": 648,
      "tx_dropped": 0,
      "tx_errors": 0,
      "tx_packets": 8
    },
    "eth5": {
      "rx_bytes": 4641,
      "rx_dropped": 0,
      "rx_errors": 0,
      "rx_packets": 26,
      "tx_bytes": 690,
      "tx_dropped": 0,
      "tx_errors": 0,
      "tx_packets": 9
    }
  }
}

v1

Get container stats based on resource usage

Path parameters

Query parameters

Response

Example response