pidusage


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

Synopsis

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

Please note that if you need to check a Node.JS script process cpu and memory usage, you can use [process.cpuUsage][node:cpuUsage] and [process.memoryUsage][node:memUsage] since node v6.1.0. This script remain useful when you have no control over the remote script, or if the process is not a Node.JS process.

Usage

``js
var pidusage = require('pidusage')

pidusage(process.pid, function (err, stats) {
console.log(stats)
// => {
// cpu: 10.0, // percentage (from 0 to 100*vcore)
// memory: 357306368, // bytes
// ppid: 312, // PPID
// pid: 727, // PID
// ctime: 867000, // ms user + system time
// elapsed: 6650000, // ms since the start of the process
// timestamp: 864000000 // ms since epoch
// }
cb()
})

// It supports also multiple pids
pidusage([727, 1234], function (err, stats) {
console.log(stats)
// => {
// 727: {
// cpu: 10.0, // percentage (from 0 to 100*vcore)
// memory: 357306368, // bytes
// ppid: 312, // PPID
// pid: 727, // PID
// ctime: 867000, // ms user + system time
// elapsed: 6650000, // ms since the start of the process
// timestamp: 864000000 // ms since epoch
// },
// 1234: {
// cpu: 0.1, // percentage (from 0 to 100*vcore)
// memory: 3846144, // bytes
// ppid: 727, // PPID
// pid: 1234, // PID
// ctime: 0, // ms user + system time
// elapsed: 20000, // ms since the start of the process
// timestamp: 864000000 // ms since epoch
// }
// }
})

// If no callback is given it returns a promise instead
const stats = await pidusage(process.pid)
console.log(stats)
// => {
// cpu: 10.0, // percentage (from 0 to 100*vcore)
// memory: 357306368, // bytes
// ppid: 312, // PPID
// pid: 727, // PID
// ctime: 867000, // ms user + system time
// elapsed: 6650000, // ms since the start of the process
// timestamp: 864000000 // ms since epoch
// }

// Avoid using setInterval as they could overlap with asynchronous processing
function compute(cb) {
pidusage(process.pid, function (err, stats) {
console.log(stats)
// => {
// cpu: 10.0, // percentage (from 0 to 100*vcore)
// memory: 357306368, // bytes
// ppid: 312, // PPID
// pid: 727, // PID
// ctime: 867000, // ms user + system time
// elapsed: 6650000, // ms since the start of the process
// timestamp: 864000000 // ms since epoch
// }
cb()
})
}

function interval(time) {
setTimeout(function() {
compute(function() {
interval(time)
})
}, time)
}

// Compute statistics every second:
interval(1000)

// Above example using async/await
const compute = async () => {
const stats = await pidusage(process.pid)
// do something
}

// Compute statistics every second:
const interval = async (time) => {
setTimeout(async () => {
await compute()
interval(time)
}, time)
}

interval(1000)
`

Compatibility

| Property | Linux | FreeBSD | NetBSD | SunOS | macOS | Win | AIX | Alpine
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| cpu | ✅ | ❓ | ❓ | ❓ | ✅ | ℹ️ | ❓ | ✅ |
| memory | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ |
| pid | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ |
| ctime | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ |
| elapsed | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ |
| timestamp | ✅ | ❓ | ❓ | ❓ | ✅ | ✅ | ❓ | ✅ |

✅ = Working
ℹ️ = Not Accurate
❓ = Should Work
❌ = Not Working

Please if your platform is not supported or if you have reported wrong readings
[file an issue][new issue].

By default, pidusage will use procfile parsing on most unix systems. If you want to use ps instead use the usePs option:

`
pidusage(pid, {usePs: true})
`

API

$3

Get pid informations.

Kind: global function
Returns: Promise.<Object> - Only when the callback is not provided.
Access: public

| Param | Type | Description |
| --- | --- | --- |
| pids | Number \| Array.<Number> \| String \| Array.<String> | A pid or a list of pids. |
| [options] | object | Options object. See the table below. |
| [callback] | function | Called when the statistics are ready. If not provided a promise is returned instead. |

$3

Setting the options programatically will override environment variables

| Param | Type | Environment variable | Default | Description |
| --- | --- | --- | --- | --- |
| [usePs] | boolean | PIDUSAGE_USE_PS| false | When true uses ps instead of proc files to fetch process information |
| [maxage] | number | PIDUSAGE_MAXAGE| 60000 | Max age of a process on history. |

PIDUSAGE_SILENT=1` can be used to remove every console message triggered by pidusage.

$3

If needed this function can be used to delete all in-memory metrics and clear the event loop. This is not necessary before exiting as the interval we're registring does not hold up the event loop.

Related

- [pidusage-tree][gh:pidusage-tree] -
Compute a pidusage tree

Authors

- Antoine Bluchet - [soyuka][github:soyuka]
- Simone Primarosa - [simonepri][github:simonepri]

See also the list of [contributors][contributors] who participated in this project.

License

This project is licensed under the MIT License - see the [LICENSE][license] file for details.

[new issue]: https://github.com/soyuka/pidusage/issues/new
[license]: https://github.com/soyuka/pidusage/tree/master/LICENSE
[contributors]: https://github.com/soyuka/pidusage/contributors

[github:soyuka]: https://github.com/soyuka
[github:simonepri]: https://github.com/simonepri

[gh:pidusage-tree]: https://github.com/soyuka/pidusage-tree

[node:cpuUsage]: https://nodejs.org/api/process.html#process_process_cpuusage_previousvalue
[node:memUsage]: https://nodejs.org/api/process.html#process_process_memoryusage