Get container stats based on resource usage Run in API Explorer

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 = lenght(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

    ID or name of the container

Query parameters

  • stream boolean

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

    Default value is true.

  • one-shot boolean

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

    Default value is false.

Responses

  • 200 application/json

    no error
  • 404 application/json

    no such container

    Hide response attribute Show response attribute object
    • message string Required

      The error message.
  • 500 application/json

    server error

    Hide response attribute Show response attribute object
    • message string Required

      The error message.
GET /containers/{id}/stats 
curl \
 --request GET 'http://api.example.com/v1.44/containers/{id}/stats'
Response examples (200) 
{
  "read": "2015-01-08T22:57:31.547920715Z",
  "networks": {
    "eth0": {
      "rx_bytes": 5338,
      "tx_bytes": 648,
      "rx_errors": 0,
      "tx_errors": 0,
      "rx_dropped": 0,
      "rx_packets": 36,
      "tx_dropped": 0,
      "tx_packets": 8
    },
    "eth5": {
      "rx_bytes": 4641,
      "tx_bytes": 690,
      "rx_errors": 0,
      "tx_errors": 0,
      "rx_dropped": 0,
      "rx_packets": 26,
      "tx_dropped": 0,
      "tx_packets": 9
    }
  },
  "cpu_stats": {
    "cpu_usage": {
      "total_usage": 100215355,
      "percpu_usage": [
        8646879,
        24472255,
        36438778,
        30657443
      ],
      "usage_in_usermode": 50000000,
      "usage_in_kernelmode": 30000000
    },
    "online_cpus": 4,
    "throttling_data": {
      "periods": 0,
      "throttled_time": 0,
      "throttled_periods": 0
    },
    "system_cpu_usage": 739306590000000
  },
  "pids_stats": {
    "current": 3
  },
  "blkio_stats": {},
  "memory_stats": {
    "limit": 67108864,
    "stats": {
      "rss": 6537216,
      "cache": 0,
      "pgpgin": 477,
      "pgfault": 964,
      "pgpgout": 414,
      "rss_huge": 6291456,
      "total_rss": 6537216,
      "writeback": 0,
      "pgmajfault": 0,
      "active_anon": 6537216,
      "active_file": 0,
      "mapped_file": 0,
      "total_cache": 0,
      "unevictable": 0,
      "total_pgpgin": 477,
      "inactive_anon": 0,
      "inactive_file": 0,
      "total_pgfault": 964,
      "total_pgpgout": 414,
      "total_rss_huge": 6291456,
      "total_writeback": 0,
      "total_pgmajfault": 0,
      "total_active_anon": 6537216,
      "total_active_file": 0,
      "total_mapped_file": 0,
      "total_unevictable": 0,
      "total_inactive_anon": 0,
      "total_inactive_file": 0,
      "hierarchical_memory_limit": 67108864
    },
    "usage": 6537216,
    "failcnt": 0,
    "max_usage": 6651904
  },
  "precpu_stats": {
    "cpu_usage": {
      "total_usage": 100093996,
      "percpu_usage": [
        8646879,
        24350896,
        36438778,
        30657443
      ],
      "usage_in_usermode": 50000000,
      "usage_in_kernelmode": 30000000
    },
    "online_cpus": 4,
    "throttling_data": {
      "periods": 0,
      "throttled_time": 0,
      "throttled_periods": 0
    },
    "system_cpu_usage": 9492140000000
  }
}
Response examples (200) 
{}
Response examples (404) 
{
  "message": "No such container: c2ada9df5af8"
}
Response examples (404) 
{
  "message": "Something went wrong."
}
Response examples (500) 
{
  "message": "Something went wrong."
}
Response examples (500) 
{
  "message": "Something went wrong."
}