Skip to content

sebhildebrandt/dockerstats

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

58 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

dockerstats

Simple Docker info and stats library for node.js

NPM Version NPM Downloads Git Issues Caretaker MIT license

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.4.2 2023-06-22 fix dockerContainerStats() fix parsing all ‚
2.4.1 2022-12-18 fix util.js after code restructuring
2.4.0 2022-12-08 code restructuring, dockerContainerStats() improved parsing, TS typings update
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

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 MIT license

The MIT License (MIT)

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

About

No description, website, or topics provided.

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published