A long long time ago (in this galaxy, though), we added support for container stats.
The API was designed to just push stats at an interval until the client disconnects.

Not too much later, people were wanting to be able to just fetch a single set of stats and be done with it, so we added a query param stream=false, which makes dockerd hang up after a single stat is sent. Not the best naming but it did what it needed to do.

But then, oh no... now the docker CLI, when using --no-stream, always shows 0% CPU usage because there was only 1 CPU stat and nothing compare CPU usage with. It was decided to collect 2 stats instead of just 1 so that the client can calculate the usage.

Fast forward to where we are now....

Here we have a problem. Any tool wanting to sample docker takes 2x as long (nearly 2 seconds) to collect per container than before the mentioned change (which admittedly was years ago).
Meanwhile every sampling tool is just going to sample as often as it needs to and calculate usage from there and does not care about the primed stats.

It would have been nice if we changed the CLI to make 2 collections rather than expecting the engine to do this for them. It wasn't a breaking change to make the engine do 2 collections, but certainly seems (or at least requiring an API bump) to backtrack and only take 1 collection.

I was hoping to make a patch to work around this problem but I can't really think of one that doesn't involve bumping the API... save for probably a long shot where we could change the engine to accept more than just true/false from the query param (?stream=)... but even this could only be taken advantage of by a custom client lib, not the official one because that is accepting a bool in the function arguments.

So opening this as an intention to fix this, and also to solicit feedback for ideas we could do possibly as a back-portable patch.