@stroncium/procfs

procfs

Zero dependency library for reading and parsing various files from procfs for Node.js, implemented in pure JS.

Linux implements procfs filesystem mounted at /proc(usually). This filesystem is virtual, and can be used to extract various information about kernel state and running processes.

Compatible with releases of Linux since 4.4 SLTS. Attempts to support new features from all the following releases. Features which are deprecated/discontinued in latest releases are not supported. Some features aren't expected to be used from Node.js and so were not implemented, if you need to use some of them, please open a feature request.

Example

npm install @stroncium/procfs

const {
	procfs,
	ProcfsError,
} = require('procfs');

console.log(procfs.uptime()); // { time: 2514423.82, idle: 9658533.16 }

console.log(procfs.processIo()); // { read: 66191, write: 147816, readSyscalls: 176, writeSyscalls: 498, readReal: 9805824, writeReal: 49152, writeCancelled: 0 }

let targetPid = 12345;

try {
	procfs.processIo(targetPid);
} catch (error) {
	if(error.code === ProcfsError.ERR_NOT_FOUND) {
		console.log('process ${targetPid} does not exist');
	}
}

API

Full version of API is available in API.md.

Currently, the folowing procfs paths are supported by the library:

• /proc/*: procfs.processes
• /proc/<pid>/autogroup: procfs.processAutogroup
• /proc/<pid>/cgroups: procfs.processCgroups
• /proc/<pid>/cmdline: procfs.processCmdline
• /proc/<pid>/comm: procfs.processComm
• /proc/<pid>/cpuset: procfs.processCpuset
• /proc/<pid>/cwd: procfs.processCwd
• /proc/<pid>/environ: procfs.processEnviron
• /proc/<pid>/exe: procfs.processExe
• /proc/<pid>/fd/*: procfs.processFds
• /proc/<pid>/fd/<fd>: procfs.processFd
• /proc/<pid>/fdinfo/<fd>: procfs.processFdinfo
• /proc/<pid>/gid_map: procfs.processGidMap
• /proc/<pid>/io: procfs.processIo
• /proc/<pid>/limits: procfs.processLimits
• /proc/<pid>/mountinfo: procfs.processMountinfo
• /proc/<pid>/net/dev: procfs.processNetDev
• /proc/<pid>/net/tcp6: procfs.processNetTcp6
• /proc/<pid>/net/tcp: procfs.processNetTcp4
• /proc/<pid>/net/udp6: procfs.processNetUdp6
• /proc/<pid>/net/udp: procfs.processNetUdp4
• /proc/<pid>/net/unix: procfs.processNetUnix
• /proc/<pid>/net/wireless: procfs.processNetWireless
• /proc/<pid>/oom_score: procfs.processOomScore
• /proc/<pid>/personality: procfs.processPersonality
• /proc/<pid>/stat: procfs.processStat
• /proc/<pid>/statm: procfs.processStatm
• /proc/<pid>/status: procfs.processStatus
• /proc/<pid>/task/*: procfs.processThreads
• /proc/<pid>/timerslack_ns: procfs.processTimerslackNs
• /proc/<pid>/uid_map: procfs.processUidMap
• /proc/cgroups: procfs.cgroups
• /proc/cmdline: procfs.cmdline
• /proc/config.gz: procfs.config
• /proc/cpuinfo: procfs.cpuinfo
• /proc/devices: procfs.devices
• /proc/diskstats: procfs.diskstats
• /proc/filesystems: procfs.filesystems
• /proc/loadavg: procfs.loadavg
• /proc/meminfo: procfs.meminfo
• /proc/net/dev: procfs.netDev
• /proc/net/tcp6: procfs.netTcp6
• /proc/net/tcp: procfs.netTcp4
• /proc/net/udp6: procfs.netUdp6
• /proc/net/udp: procfs.netUdp4
• /proc/net/unix: procfs.netUnix
• /proc/net/wireless: procfs.netWireless
• /proc/partitions: procfs.partitions
• /proc/stat: procfs.stat
• /proc/swaps: procfs.swaps
• /proc/uptime: procfs.uptime
• /proc/version: procfs.version

Custom procfs path

const {
	Procfs
} = require('procfs');

let procfs = new Procfs('/custom/proc');
console.log(procfs.uptime()); // { time: 2514423.82, idle: 9658533.16 }

Performance

Good performance is considered one of the main goals of this library, but for some calls which aren't expected to be used frequently the parsing might be done in sub-optimal(but still quite performant) way. If you encounter a need for performance optimizations of some call, please open an issue.

Currently, all the IO is done synchronously, in most cases it is faster than asynchronous IO for procfs. For many methods, synchronous IO is always faster than asynchronous, as time required to perform full read synchronously is smaller than just initializing asynchronous read structures. For others, it is on par. In case when a lot of relatively big files are read at the same time, asynchronous IO can be faster on multi-core systems, so introducing async versions of methods is considered for future versions.

Development

npm run test to perform a test without updating docs nor type asserts.

npm run fulltest to npm run build && npm run test

npm run build builds API.md and type asserts for tests from haxe/procfs/Procfs.hx.