Simple docker statistics libary
npm install dockerstatsSimple [Docker][docker-url] info and stats library for [node.js][nodejs-url]
[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Git Issues][issues-img]][issues-url]
[![Caretaker][caretaker-image]][caretaker-url]
[![MIT license][license-img]][license-url]
Version 2 just released with several security fixes, improvements and changes.
Be aware, that the new version 2.x is NOT fully backward compatible to version 1.x ...
We had to make several interface changes to keep dockerStats as consistent as possible. We highly recommend to go through the complete list and adapt your own code to be again compatible to the new version 2.
| Function | Old | New (V5) | Comments |
| ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------- |
| dockerContainerStats() | mem_usage
mem_limit
mem_percent
cpu_percent
cpu_stats
precpu_stats
memory_stats | memUsage
memLimit
memPercent
cpuPercent
cpuStats
precpuStats
memoryStats | pascalCase conformity |
| dockerContainerProcesses() | pid_host | pidHost | pascalCase conformity |
Collection of a few functions to retrieve detailed docker statistics. With this package you easily can retrieve
- list of top level/all docker images
- list of active/all docker containers
- statistics for a specific container (mem, cpu, network and blockIO stats)
- information of all processes of a specific active docker container (pids, state, cpu-time, user...)
- list all docker volumes
Super simple to use with callback functions or promise style.
``bash`
$ npm install dockerstats --save
All functions are implemented as asynchronous functions. Here a small example how to use them:
`js
const dockerstats = require('dockerstats');
// callback style
dockerstats.dockerContainers(function(data) {
console.log('Docker Containers');
console.log(data);
})
// promises style
dockerstats.dockerContainers()
.then(data => console.log(data))
.catch(error => console.error(error));
// full async / await example (node >= 7.6)
async function dockerContainers() {
try {
const data = await dockerstats.dockerContainers();
console.log(data)
} catch (e) {
console.log(e)
}
}
`
[Docker][docker-url] comes with a API to control Docker and retrieve detailes information. So I came up to write this
little library to collect some docker statistics. This library is still work in progress. I am sure, there is for sure room for improvement.
Tested on several Debian, Raspbian, Ubuntu distributions, OS X (Mavericks, Yosemite, El Captain, Sierra, High Sierra, Mojave).
If you have comments, suggestions & reports, please feel free to contact me!
I also created a full blown system information library (including all docker stats) called [systeminformation][systeminformation-github-url], also available via [github][systeminformation-github-url] and [npm][systeminformation-npm-url].
| Function | Result object | Comments |
| ----------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
| si.dockerInfo(cb) | {...} | returns general docker info |
| | id | Docker ID |
| | containers | number of containers |
| | containersRunning | number of running containers |
| | containersPaused | number of paused containers |
| | containersStopped | number of stopped containers |
| | images | number of images |
| | driver | driver (e.g. 'devicemapper', 'overlay2') |
| | memoryLimit | has memory limit |
| | swapLimit | has swap limit |
| | kernelMemory | has kernal memory |
| | cpuCfsPeriod | has CpuCfsPeriod |
| | cpuCfsQuota | has CpuCfsQuota |
| | cpuShares | has CPUShares |
| | cpuSet | has CPUShares |
| | ipv4Forwarding | has IPv4Forwarding |
| | bridgeNfIptables | has BridgeNfIptables |
| | bridgeNfIp6tables | has BridgeNfIp6tables |
| | debug | Debug on |
| | nfd | named data networking forwarding daemon |
| | oomKillDisable | out-of-memory kill disabled |
| | ngoroutines | number NGoroutines |
| | systemTime | docker SystemTime |
| | loggingDriver | logging driver e.g. 'json-file' |
| | cgroupDriver | cgroup driver e.g. 'cgroupfs' |
| | nEventsListener | number NEventsListeners |
| | kernelVersion | docker kernel version |
| | operatingSystem | docker OS e.g. 'Docker for Mac' |
| | osType | OSType e.g. 'linux' |
| | architecture | architecture e.g. x86_64 |
| | ncpu | number of CPUs |
| | memTotal | memory total |
| | dockerRootDir | docker root directory |
| | httpProxy | http proxy |
| | httpsProxy | https proxy |
| | noProxy | NoProxy |
| | name | Name |
| | labels | array of labels |
| | experimentalBuild | is experimental build |
| | serverVersion | server version |
| | clusterStore | cluster store |
| | clusterAdvertise | cluster advertise |
| | defaultRuntime | default runtime e.g. 'runc' |
| | liveRestoreEnabled | live store enabled |
| | isolation | isolation |
| | initBinary | init binary |
| | productLicense | product license |
| si.dockerImages(all, cb) | [{...}] | returns array of top level/all docker images |
| | [0].id | image ID |
| | [0].container | container ID |
| | [0].comment | comment |
| | [0].os | OS |
| | [0].architecture | architecture |
| | [0].parent | parent ID |
| | [0].dockerVersion | docker version |
| | [0].size | image size |
| | [0].sharedSize | shared size |
| | [0].virtualSize | virtual size |
| | [0].author | author |
| | [0].created | created date / time |
| | [0].containerConfig | container config object |
| | [0].graphDriver | graph driver object |
| | [0].repoDigests | repo digests array |
| | [0].repoTags | repo tags array |
| | [0].config | config object |
| | [0].rootFS | root fs object |
| si.dockerContainers(all, cb) | [{...}] | returns array of active/all docker containers |
| | [0].id | ID of container |
| | [0].name | name of container |
| | [0].image | name of image |
| | [0].imageID | ID of image |
| | [0].command | command |
| | [0].created | creation time (unix) |
| | [0].started | creation time (unix) |
| | [0].finished | creation time (unix) |
| | [0].createdAt | creation date time string |
| | [0].startedAt | creation date time string |
| | [0].finishedAt | creation date time string |
| | [0].state | created, running, exited |
| | [0].ports | array of ports |
| | [0].mounts | array of mounts |
| si.dockerContainerStats(ids, cb) | [{...}] | statistics for specific containers
container IDs: space or comma separated,
pass '*' for all containers |
| | [0].id | Container ID |
| | [0].memUsage | memory usage in bytes |
| | [0].memLimit | memory limit (max mem) in bytes |
| | [0].memPercent | memory usage in percent |
| | [0].cpuPercent | cpu usage in percent |
| | [0].pids | number of processes |
| | [0].netIO.rx | received bytes via network |
| | [0].netIO.wx | sent bytes via network |
| | [0].blockIO.r | bytes read from BlockIO |
| | [0].blockIO.w | bytes written to BlockIO |
| | [0].cpuStats | detailed cpu stats |
| | [0].percpuStats | detailed per cpu stats |
| | [0].memoryStats | detailed memory stats |
| | [0].networks | detailed network stats per interface |
| si.dockerContainerProcesses(id, cb) | [{...}] | array of processes inside a container |
| | [0].pid_host | process ID (host) |
| | [0].ppid | parent process ID |
| | [0].pgid | process group ID |
| | [0].user | effective user name |
| | [0].ruser | real user name |
| | [0].group | effective group name |
| | [0].rgroup | real group name |
| | [0].stat | process state |
| | [0].time | accumulated CPU time |
| | [0].elapsed | elapsed running time |
| | [0].nice | nice value |
| | [0].rss | resident set size |
| | [0].vsz | virtual size in Kbytes |
| | [0].command | command and arguments |
| si.dockerVolumes(cb) | [{...}] | returns array of all docker volumes |
| | [0].name | volume name |
| | [0].driver | driver |
| | [0].labels | labels object |
| | [0].mountpoint | mountpoint |
| | [0].options | options |
| | [0].scope | scope |
| | [0].created | created at |
| si.dockerAll(cb) | {...} | list of all containers including their stats
and processes in one single array |
Remember: all functions are implemented as asynchronous functions! There are now two ways to consume them:
Callback Style
`js
// assuming you have a container with ID 'ae8a76'
const dockerstats = require('dockerstats');
dockerstats.dockerContainerStats('ae8a76', function(data) {
console.log('Docker Container Stats:');
console.log('- ID: ' + data.id);
console.log('- Mem usage: ' + data.memUsage);
console.log('- Mem limit: ' + data.memLimit);
console.log('- Mem usage %: ' + data.memPercent);
console.log('- CPU usage %: ' + data.cpuPercent);
})
`
Promises Style
When omitting callback parameter (cb), then you can use all function in a promise oriented way. All functions are returning a promise, that you can consume:
`js
// assuming you have a container with ID 'ae8a76'
const dockerstats = require('dockerstats');
dockerstats.dockerContainerStats('ae8a76')
.then(data => {
console.log('Docker Container Stats:');
console.log('- ID: ' + data.id);
console.log('- Mem usage: ' + data.memUsage);
console.log('- Mem limit: ' + data.memLimit);
console.log('- Mem usage %: ' + data.memPercent);
console.log('- CPU usage %: ' + data.cpuPercent);
})
.catch(error => console.error(error));
`
Using async / await (available since node v7.6)
Since node v7.6 you can also use the async / await pattern. The above example would then look like this:
`js
// assuming you have a container with ID 'ae8a76'
const dockerstats = require('dockerstats');
async function dockerContainerData() {
try {
const data = await dockerstats.dockerContainerStats('ae8a76');
console.log('Docker Container Stats:');
console.log('- ID: ' + data.id);
console.log('- Mem usage: ' + data.memUsage);
console.log('- Mem limit: ' + data.memLimit);
console.log('- Mem usage %: ' + data.memPercent);
console.log('- CPU usage %: ' + data.cpuPercent);
console.log('...');
} catch (e) {
console.log(e)
}
}
`
| Version | Date | Comment |
| ------- | ---------- | -------------------------------------------------------------------------------------------------- |
| 2.4.3 | 2026-01-10 | code refactoring, cleanup |
| 2.4.2 | 2023-06-22 | fix dockerContainerStats() fix parsing all |util.js
| 2.4.1 | 2022-12-18 | fix after code restructuring |dockerContainerStats()
| 2.4.0 | 2022-12-08 | code restructuring, improved parsing, TS typings update |dockerImagesInspect()
| 2.3.0 | 2021-05-04 | , dockerContainerInspect(), dockerContainerProcesses() security updates |dockerVolumes
| 2.2.0 | 2021-02-25 | added dockerVolumes() - get volume data |dockerImages
| 2.1.0 | 2021-02-24 | added dockerImages() - get image data |dockerContainerStats
| 2.0.2 | 2021-02-23 | fixed param * |dockerContainerStats
| 2.0.1 | 2021-02-15 | fixed ID splitting |dockerContainerStats
| 2.0.0 | 2021-02-14 | new version 2.0 with security patches, fixes and several updated |
| 1.4.4 | 2021-01-02 | fix tx changed to wx as documented |typescript
| 1.4.3 | 2020-12-03 | definitions fix |dockerContainers()
| 1.4.2 | 2020-10-16 | resolved hanging issue |dockerInfo()
| 1.4.1 | 2019-05-31 | changed property naming style |dockerInfo()
| 1.4.0 | 2019-05-30 | added typescript definitions, updated docs |
| 1.3.0 | 2019-05-29 | added , dockerContainers()
added started, finished time, restartCount |
| 1.2.8 | 2018-12-03 | updated package.json (files) |
| 1.2.7 | 2018-12-03 | updated docs |
| 1.2.6 | 2018-11-21 | updated docs |
| 1.2.5 | 2018-11-18 | code cleanup |
| 1.2.4 | 2018-11-18 | bug-fixing - CPU percent calculation (win) |
| 1.2.3 | 2018-11-18 | bug-fixing - CPU percent calculation (linux, win) |
| 1.2.2 | 2018-11-18 | bug-fixing - parsing JSON |
| 1.2.1 | 2018-11-18 | bug-fixing - parsing JSON |
| 1.2.0 | 2018-11-06 | bug-fixing, stabilization, added error handling |
| 1.1.0 | 2017-11-06 | added windows support, dependency version bump |
| 1.0.0 | 2016-11-04 | Initial release |
If you have ideas or comments, please do not hesitate to contact me.
Happy monitoring!
Sincerely,
Sebastian Hildebrandt, +innovations
Written by Sebastian Hildebrandt sebhildebrandt
#### Contributers
- toolcreator toolcreator
Linux is a registered trademark of Linus Torvalds. macOS, OS X is a registered trademark of Apple Inc.,
Windows is a registered trademark of Microsoft Corporation. Node.js is a trademark of Joyent Inc.,
Intel is a trademark of Intel Corporation. Raspberry Pi is a trademark of the Raspberry Pi Foundation.
Debian is a trademark of the Debian Project. Ubuntu is a trademark of Canonical Ltd., Docker is a trademark of Docker, Inc.
All other trademarks are the property of their respective owners.
>The [MIT`][license-url] License (MIT)
>
>Copyright © 2026 Sebastian Hildebrandt, +innovations.
>
>Permission is hereby granted, free of charge, to any person obtaining a copy
>of this software and associated documentation files (the "Software"), to deal
>in the Software without restriction, including without limitation the rights
>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
>copies of the Software, and to permit persons to whom the Software is
>furnished to do so, subject to the following conditions:
>
>The above copyright notice and this permission notice shall be included in
>all copies or substantial portions of the Software.
>
>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
>THE SOFTWARE.
>
>Further details see LICENSE file.
[npm-image]: https://img.shields.io/npm/v/dockerstats.svg?style=flat-square
[npm-url]: https://npmjs.org/package/dockerstats
[downloads-image]: https://img.shields.io/npm/dm/dockerstats.svg?style=flat-square
[downloads-url]: https://npmjs.org/package/dockerstats
[license-url]: https://github.com/sebhildebrandt/dockerstats/blob/master/LICENSE
[license-img]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[npmjs-license]: https://img.shields.io/npm/l/dockerstats.svg?style=flat-square
[changelog-url]: https://github.com/sebhildebrandt/dockerstats/blob/master/CHANGELOG.md
[caretaker-url]: https://github.com/sebhildebrandt
[caretaker-image]: https://img.shields.io/badge/caretaker-sebhildebrandt-blue.svg?style=flat-square
[nodejs-url]: https://nodejs.org/en/
[docker-url]: https://www.docker.com/
[issues-img]: https://img.shields.io/github/issues/sebhildebrandt/dockerstats.svg?style=flat-square
[issues-url]: https://github.com/sebhildebrandt/dockerstats/issues
[closed-issues-img]: https://img.shields.io/github/issues-closed-raw/sebhildebrandt/dockerstats.svg?style=flat-square
[closed-issues-url]: https://github.com/sebhildebrandt/dockerstats/issues?q=is%3Aissue+is%3Aclosed
[systeminformation-npm-url]: https://npmjs.org/package/systeminformation
[systeminformation-github-url]: https://github.com/sebhildebrandt/systeminformation