DOdocker
Container

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
get/containers/{id}/stats

Request

Path parameters

idstring required

ID or name of the container

Query parameters

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.

networksunknown

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
  },
  "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
    }
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.