A process lookup utility
npm install @webpod/ps> A Node.js module for looking up running processes. Originated from neekey/ps, UmbraEngineering/ps and completely reforged.
table-parser replaced with @webpod/ingrid to handle some issues: neekey/ps#76, neekey/ps#62, neekey/table-parser#11, neekey/table-parser#18bash
$ npm install @webpod/ps
`Internals
This module uses different approaches for getting process list:| Platform | Method |
|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| Unix/Mac |
ps -lx |
| Windows (kernel >= 26000)| pwsh -NoProfile -Command "Get-CimInstance Win32_Process \| Select-Object ProcessId,ParentProcessId,CommandLine \| ConvertTo-Json -Compress" |
| Windows (kernel < 26000) | wmic process get ProcessId,CommandLine |Usage
$3
Searches for the process by the specified pid.
`ts
import {lookup} from '@webpod/ps'// Both callback and promise styles are supported
const list = await lookup({pid: 12345})
// or
lookup({pid: 12345}, (err, list) => {
if (err) {
throw new Error(err)
}
const [found] = list
if (found) {
console.log('PID: %s, COMMAND: %s, ARGUMENTS: %s', found.pid, found.command, found.arguments)
} else {
console.log('No such process found!')
}
})
// or syncronously
const _list = lookup.sync({pid: 12345})
`Define a query opts to filter the results by
command and/or arguments predicates:
`ts
const list = await lookup({
command: 'node', // it will be used to build a regex
arguments: '--debug',
})list.forEach(entry => {
console.log('PID: %s, COMMAND: %s, ARGUMENTS: %s', entry.pid, entry.command, entry.arguments);
})
`Unix users can override the default
ps arguments:
`ts
lookup({
command: 'node',
psargs: 'ux'
}, (err, resultList) => {
// ...
})
`Specify the
ppid option to filter the results by the parent process id (make sure that your custom psargs provides this output: -l or -j for instance)
`ts
lookup({
command: 'mongod',
psargs: '-l',
ppid: 82292
}, (err, resultList) => {
// ...
})
`$3
Returns a child processes list by the specified parent pid. Some kind of shortcut for lookup({ppid: pid}).
`ts
import { tree } from '@webpod/ps'const children = await tree(123)
/**
[
{pid: 124, ppid: 123},
{pid: 125, ppid: 123}
]
*/
`To obtain all nested children, set
recursive option to true:
`ts
const children = await tree({pid: 123, recursive: true})
/**
[
{pid: 124, ppid: 123},
{pid: 125, ppid: 123}, {pid: 126, ppid: 124},
{pid: 127, ppid: 124},
{pid: 128, ppid: 124},
{pid: 129, ppid: 125},
{pid: 130, ppid: 125},
]
*/
// or syncronously
const list = tree.sync({pid: 123, recursive: true})
`$3
Eliminates the process by its pid.`ts
import { kill } from '@webpod/ps'kill('12345', (err, pid) => {
if (err) {
throw new Error(err)
} else {
console.log('Process %s has been killed!', pid)
}
})
`Method
kill also supports a signal option to be passed. It's only a wrapper of process.kill() with checking of that killing is finished after the method is called.`ts
import { kill } from '@webpod/ps'// Pass signal SIGKILL for killing the process without allowing it to clean up
kill('12345', 'SIGKILL', (err, pid) => {
if (err) {
throw new Error(err)
} else {
console.log('Process %s has been killed without a clean-up!', pid)
}
})
`You can also use object notation to specify more opts:
`ts
kill( '12345', {
signal: 'SIGKILL',
timeout: 10, // will set up a ten seconds timeout if the killing is not successful
}, () => {})
`Notice that the nodejs build-in
process.kill()` does not accept number as a signal, you will have to use string format.