dockerstats

Simple Docker info and stats library for node.js

New Version 2

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.

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

Quick Start

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.

Installation

$ npm install dockerstats --save

Usage

All functions are implemented as asynchronous functions. Here a small example how to use them:

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)
  }
}

Core concept

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].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

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)
    }
}

Version history

Version	Date	Comment
2.3.0	2021-05-04	dockerImagesInspect(), dockerContainerInspect(), dockerContainerProcesses() security updates
2.2.0	2021-02-25	dockerVolumes added dockerVolumes() - get volume data
2.1.0	2021-02-24	dockerImages added dockerImages() - get image data
2.0.2	2021-02-23	dockerContainerStats fixed param *
2.0.1	2021-02-15	dockerContainerStats fixed ID splitting
2.0.0	2021-02-14	new version 2.0 with security patches, fixes and several updated
1.4.4	2021-01-02	dockerContainerStats fix tx changed to wx as documented
1.4.3	2020-12-03	typescript definitions fix
1.4.2	2020-10-16	dockerContainers() resolved hanging issue
1.4.1	2019-05-31	dockerInfo() changed property naming style
1.4.0	2019-05-30	added typescript definitions, updated docs
1.3.0	2019-05-29	added dockerInfo(), 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

Comments

If you have ideas or comments, please do not hesitate to contact me.

Happy monitoring!

Sincerely,

Sebastian Hildebrandt, +innovations

Credits

Written by Sebastian Hildebrandt sebhildebrandt

Contributers

• toolcreator toolcreator

Copyright Information

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.

License

The MIT License (MIT)

Copyright © 2021 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.