Version 2 just released with several security fixes, improvements and changes.
Breaking Changes Version 2
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.
Docker 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, also available via github and npm.
Reference
Function Reference and OS Support
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].status
healthy, starting, unhealthy
[0].state
created, running, exited
[0].labels
object of labels (key-value pairs)
[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
cb: Asynchronous Function Calls (callback)
Remember: all functions are implemented as asynchronous functions! There are now two ways to consume them:
Callback Style
// 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
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:
// 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));
Async / Await
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:
// 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); }}
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.
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.