pidusage

You can pass an options object to pidusage() to customize behavior. These options override the corresponding environment variables.

Additionally, setting the environment variable PIDUSAGE_SILENT=1 will suppress all console messages triggered by the library.

// Use 'ps' instead of proc files
pidusage(pid, { usePs: true })

When monitoring process statistics repeatedly, avoid using setInterval as asynchronous processing might overlap. Instead, use recursive setTimeout calls to ensure the previous measurement is complete before scheduling the next one.

Async/Await Pattern:

const interval = async (time) => {
  setTimeout(async () => {
    await compute()
    interval(time)
  }, time)
}

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

const interval = async (time) => {
  setTimeout(async () => {
    await compute()
    interval(time)
  }, time)
}

interval(1000) // Run every 1000ms

The server.js example demonstrates how to use pidusage in a server environment. To test the performance or behavior of this example, you can use an HTTP benchmark tool like wrk against localhost:8020 after starting the server.

# Start the server, run the tests on localhost:8020

The stresstest.js example is designed to put the system under load. Use caution when running this script as it is intended to be a stress test.

node stresstest.js

The pidusage function retrieves cross-platform CPU percentage and memory usage for one or more PIDs.

It supports:

• A single PID (Number or String).
• An array of PIDs (Array of Numbers or Strings).

If a callback is provided, it follows the Node.js error-first callback pattern. If no callback is provided, it returns a Promise that resolves to the statistics object.

var pidusage = require('pidusage')

// Using a callback
pidusage(process.pid, function (err, stats) {
  console.log(stats)
})

// Using Promises/async/await
const stats = await pidusage(process.pid)
console.log(stats)

// Using multiple PIDs
pidusage([727, 1234], function (err, stats) {
  // stats is an object keyed by PID
  console.log(stats[727])
})

The pidusage.clear() method deletes all in-memory metrics and clears the event loop. This is useful if you need to reset the internal history. It is generally not required before exiting the process, as the internal interval does not prevent the event loop from exiting.

const pidusage = require('pidusage')

// Clear all cached metrics
pidusage.clear()

The statistics object returned by pidusage contains the following fields:

// Example output for a single PID
{
  cpu: 10.0,
  memory: 357306368,
  ppid: 312,
  pid: 727,
  ctime: 867000,
  elapsed: 6650000,
  timestamp: 864000000
}

// Example output for multiple PIDs
{
  727: { ... },
  1234: { ... }
}

The availability of specific metrics depends on the operating system:

Legend: ✅ Working, ℹ️ Not Accurate, ❓ Should Work, ❌ Not Working

Use pidusage.clear() to clear the internal history/cache of process statistics. This is useful if you want to force the library to fetch fresh data instead of using cached values.

const pidusage = require('pidusage');

// Clear the history/cache
pidusage.clear();