pidusage

What is pidusage?

The pidusage npm package is a cross-platform process and system monitoring library. It provides statistics such as CPU usage, memory usage, running time, and more for a given process ID (PID). It's particularly useful for monitoring the resource consumption of processes in Node.js applications.

What are pidusage's main functionalities?

Process Statistics

This feature allows you to monitor the resource usage of a specific process. The code sample demonstrates how to get statistics such as CPU and memory usage for the current process.

const pidusage = require('pidusage');
pidusage(process.pid, function (err, stats) {
  console.log(stats);
});

Monitoring Multiple PIDs

Pidusage also supports monitoring multiple processes at once. This code sample shows how to get statistics for multiple PIDs simultaneously.

const pidusage = require('pidusage');
pidusage([1234, 5678], function (err, stats) {
  console.log(stats);
});

Other packages similar to pidusage

ps-node

A library for looking up processes running on the system. While ps-node focuses more on finding and interacting with processes, pidusage specializes in monitoring their resource usage.

systeminformation

This package provides a broad set of system and OS metrics, including process monitoring. Compared to pidusage, systeminformation offers a wider range of system-related information but might be more complex to use for simple process monitoring tasks.

README

pidusage

Cross-platform process cpu % and memory usage of a PID

Ideas from https://github.com/arunoda/node-usage/ but with no C-bindings

API

var pusage = require('pidusage')

pusage.stat(process.pid, function(err, stat) {

	expect(err).to.be.null
	expect(stat).to.be.an('object')
	expect(stat).to.have.property('cpu')
	expect(stat).to.have.property('memory')

	console.log('Pcpu: %s', stat.cpu)
	console.log('Mem: %s', stat.memory) //those are bytes

})

// Unmonitor process
pusage.unmonitor(18902);

How it works

A check on the os.platform is done to determine the method to use.

Linux

We use /proc/{pid}/stat in addition to the the PAGE_SIZE and the CLK_TCK direclty from getconf() command. Uptime comes from proc/uptime file because it's more accurate than the nodejs os.uptime().

/!\ As stated in #17, memory will increase when using pidusage.stat in an interval because of readFile. Use --expose-gc and release the garbage collector to avoid such leaking.

Cpu usage is computed by following those instructions. It keeps an history of the current processor time for the given pid so that the computed value gets more and more accurate. Don't forget to do unmonitor(pid) so that history gets cleared. Cpu usage does not check the child process tree!

Memory result is representing the RSS (resident set size) only by doing rss*pagesize, where pagesize is the result of getconf PAGE_SIZE.

On darwin, freebsd, solaris (tested on 10/11)

We use a fallback with the ps -o pcpu,rss -p PID command to get the same informations.

Memory usage will also display the RSS only, process cpu usage might differ from a distribution to another. Please check the correspoding man ps for more insights on the subject.

On AIX

AIX is tricky because I have no AIX test environement, at the moment we use: ps -o pcpu,rssize -p PID but /proc results should be more accurate! If you're familiar with the AIX environment and know how to get the same results as we've got with Linux systems, please help. #4

Windows

Windows is really tricky, atm it uses the wmic.exe, feel free to share ideas on how to improve this. More specifically, thanks to @crystaldust we replaced wmic PROCESS by wmic path Win32_RawData_PerfProc_Process to get more accurated data (PR, commit, switched from formatted to raw data here).

The memory usage here is what windows calls the "Working Set":

Maximum number of bytes in the working set of this process at any point in time. The working set is the set of memory pages touched recently by the threads in the process. If free memory in the computer is above a threshold, pages are left in the working set of a process even if they are not in use. When free memory falls below a threshold, pages are trimmed from working sets. If they are needed, they are then soft-faulted back into the working set before they leave main memory.

For cpu usage, it's the "Percent Processor Time", which is about the same computation as it is done with linux implementations:

Returns elapsed time that all of the threads of this process used the processor to execute instructions in 100 nanoseconds ticks. An instruction is the basic unit of execution in a computer, a thread is the object that executes instructions, and a process is the object created when a program is run. Code executed to handle some hardware interrupts and trap conditions is included in this count.

Source, Source for raw calculation

Why wmic? I have the feeling it's slow

This is the safest implementation I've found that works on most Windows version (>= XP). I've tried many other implementations but there was always some failing test case. For example, powershell would be faster but powershell needs to be attached to a console (see this comment). This means it'd have to popup a new cmd.exe every time we execute pidusage. If you know a way that doesn't imply the use of wmic, please open an issue so that I can try it!

Licence

MIT

Changelog

1.1.0

Windows: (wmic) goes back to the first version of wmic, naming wmic process {pid} get workingsetsize,usermodetime,kernelmodetime. CPU usage % is computed on the flight, per pid.