docker stats --one-shot explanation

Question

I am trying to implement an api endpoint for docker stats --one-shot but I simply do not understand the difference between --one-shot and --no-stream. The API documentation is located here but doesn't illuminate much. I know this seems like a simple question but I am a newcomer to the docker api and can't seem to find much clarity. Thank you.

Answer 1

If you specify one-shot=true then the precpu stats will be empty. By default a second check is run on the server side to fill in this value, but it results in an extra 2 second delay:

$ curl -s --unix-socket /var/run/docker.sock 'http://localhost/containers/76c22a363ea8900ddd7ecee74fd6bb19d5dd7c50a26695e6b0dee5c353e2174d/stats?stream=false&one-shot=true' | jq .precpu_stats
{
  "cpu_usage": {
    "total_usage": 0,
    "usage_in_kernelmode": 0,
    "usage_in_usermode": 0
  },
  "throttling_data": {
    "periods": 0,
    "throttled_periods": 0,
    "throttled_time": 0
  }
}

$ curl -s --unix-socket /var/run/docker.sock 'http://localhost/containers/76c22a363ea8900ddd7ecee74fd6bb19d5dd7c50a26695e6b0dee5c353e2174d/stats?stream=false&one-shot=false' | jq .precpu_stats
{
  "cpu_usage": {
    "total_usage": 336500498536,
    "percpu_usage": [
      42273785950,
      42067912050,
      42236140288,
      42504140826,
      42151800123,
      41175670348,
      41403446188,
      42687602763
    ],
    "usage_in_kernelmode": 6110000000,
    "usage_in_usermode": 97120000000
  },
  "system_cpu_usage": 70752558350000000,
  "online_cpus": 8,
  "throttling_data": {
    "periods": 0,
    "throttled_periods": 0,
    "throttled_time": 0
  }
}