What Is the Docker Stats API?

Last updated at Fri, 03 Nov 2017 20:14:47 GMT

Containerization and micro-services are changing how development and operations teams design, build and monitor systems. Containerization of environments regularly results in systems with large numbers of dynamic and ephemeral instances that autoscale to meet demands on system load. In fact, it’s not uncommon to see thousands of container instances, where once there were hundreds of (cloud) server instances, where once there were tens of physical servers,

From a monitoring perspective this means it’s even more difficult to understand what is happening across your environment without centralized monitoring and logging. After all you can not manage what you do not monitor. 

Enter the Docker stats API. The Docker stats API is part of the new docker 1.5 release and is an API endpoint and CLI command that will stream live resource usage information (such as CPU, memory, network IO and block IO) for your containers. The API endpoint can be used to build tools that feed live resource information for your containers into your existing monitoring solutions, or build live dashboards directly using the API.

In fact at we have built a new Docker Logentries container to plug into this endpoint to allow you to stream this data into your Logentries account, along with any Docker logs from your containers. If you want to build your own tool you can check out the source code on this github repo – it might give you some ideas. The container is also available on the Logentries Dockerhub repo. Our friends at nearfrom – leaders in the Node space, the guys behind Europe’s biggest (and most fun!) node conference and avid Docker contributors (e.g. the guys behind jsChan) have helped us to develop this container (thanks Peter and Matteo!).

The Docker Logentries container works by mounting the Docker socket to consume both a stream of log data from your docker containers as well as a stream of stats from the docker stats API. The docker stats API will forward the following type of info per container:

{
   "read" : "2015-01-08T22:57:31.547920715Z",
   "network" : {
      "rx_dropped" : 0,
      "rx_bytes" : 648,
      "rx_errors" : 0,
      "tx_packets" : 8,
      "tx_dropped" : 0,
      "rx_packets" : 8,
      "tx_errors" : 0,
      "tx_bytes" : 648
   },
   "memory_stats" : {
      "stats" : {
         "total_pgmajfault" : 0,
         "cache" : 0,
         "mapped_file" : 0,
         "total_inactive_file" : 0,
         "pgpgout" : 414,
         "rss" : 6537216,
         "total_mapped_file" : 0,
         "writeback" : 0,
         "unevictable" : 0,
         "pgpgin" : 477,
         "total_unevictable" : 0,
         "pgmajfault" : 0,
         "total_rss" : 6537216,
         "total_rss_huge" : 6291456,
         "total_writeback" : 0,
         "total_inactive_anon" : 0,
         "rss_huge" : 6291456,
         "hierarchical_memory_limit" : 67108864,
         "total_pgfault" : 964,
         "total_active_file" : 0,
         "active_anon" : 6537216,
         "total_active_anon" : 6537216,
         "total_pgpgout" : 414,
         "total_cache" : 0,
         "inactive_anon" : 0,
         "active_file" : 0,
         "pgfault" : 964,
         "inactive_file" : 0,
         "total_pgpgin" : 477
      },
      "max_usage" : 6651904,
      "usage" : 6537216,
      "failcnt" : 0,
      "limit" : 67108864
   "blkio_stats" : {},
   "cpu_stats" : {
      "cpu_usage" : {
         "percpu_usage" : [
            16970827,
            1839451,
            7107380,
            10571290
         ],
         "usage_in_usermode" : 10000000,
         "total_usage" : 36488948,
         "usage_in_kernelmode" : 20000000
      },
      "system_cpu_usage" : 20091722000000000,
      "throttling_data" : {}
   }
}

You can see that it provides a nice level of visibility across your key server resources and ultimately you can now build a specialised monitoring/logging container (as we have) to give you an easy way to collect both you container logs and metrics and to make them available in a centralized location. Collecting BOTH log data and stats in a single dashboard has the advantage of giving you a multi-dimensional view of your system and is particularly useful for troubleshooting and monitoring of your production docker environments – which has been pretty difficult to achieve up to this point.

To visualise this info you can also take advantage of the Logentries Docker Community pack which provides out of the box dashboards, alerts and tags for your stats API data – providing dashboards and alerts on per container CPU, Memory and Network trends for example.

For details on setting up the new Docker Logentries container, see our setup guide. And as always let us know what you think.