From 6271ef005eb311c819b7ab041e09f50e4155ec1e Mon Sep 17 00:00:00 2001 From: vmarchaud Date: Sun, 2 Jun 2019 13:33:47 +0200 Subject: process: expose uv_rusage on process.resourcesUsage() As discussed in https://github.com/nodejs/diagnostics/issues/161, the core should expose important metrics about the runtime, this PR's goal is to let user get the number of io request made, and lower level mertrics like the page faults and context switches. PR-URL: https://github.com/nodejs/node/pull/28018 Reviewed-By: Ben Noordhuis Reviewed-By: Colin Ihrig Reviewed-By: Anna Henningsen --- doc/api/process.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) (limited to 'doc/api/process.md') diff --git a/doc/api/process.md b/doc/api/process.md index 752889b3f0..ec48906d5c 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -1815,6 +1815,91 @@ process.report.writeReport(); Additional documentation is available in the [report documentation][]. +## process.resourceUsage() + + +* Returns: {Object} + * `userCPUTime` {integer} + * `systemCPUTime` {integer} + * `maxRSS` {integer} + * `sharedMemorySize` {integer} + * `unsharedDataSize` {integer} + * `unsharedStackSize` {integer} + * `minorPageFault` {integer} + * `majorPageFault` {integer} + * `swapedOut` {integer} + * `fsRead` {integer} + * `fsWrite` {integer} + * `ipcSent` {integer} + * `ipcReceived` {integer} + * `signalsCount` {integer} + * `voluntaryContextSwitches` {integer} + * `involuntaryContextSwitches` {integer} + +The `process.resourceUsage()` method returns the resource usage +for the current process. +All of these values come from the `uv_getrusage` call which returns +[this struct][uv_rusage_t], here the mapping between node and libuv: +- `userCPUTime` maps to `ru_utime` computed in microseconds. +It is the values as [`process.cpuUsage().user`][process.cpuUsage] +- `systemCPUTime` maps to `ru_stime` computed in microseconds. +It is the value as [`process.cpuUsage().system`][process.cpuUsage] +- `maxRSS` maps to `ru_maxrss` which is the maximum resident set size +used (in kilobytes). +- `sharedMemorySize` maps to `ru_ixrss` but is not supported by any platform. +- `unsharedDataSize` maps to `ru_idrss` but is not supported by any platform. +- `unsharedStackSize` maps to `ru_isrss` but is not supported by any platform. +- `minorPageFault` maps to `ru_minflt` which is the number of minor page fault +for the process, see [this article for more details][wikipedia_minor_fault] +- `majorPageFault` maps to `ru_majflt` which is the number of major page fault +for the process, see [this article for more details][wikipedia_major_fault]. +This field is not supported on Windows platforms. +- `swappedOut` maps to `ru_nswap` which is not supported by any platform. +- `fsRead` maps to `ru_inblock` which is the number of times the file system +had to perform input. +- `fsWrite` maps to `ru_oublock` which is the number of times the file system +had to perform output. +- `ipcSent` maps to `ru_msgsnd` but is not supported by any platform. +- `ipcReceived` maps to `ru_msgrcv` but is not supported by any platform. +- `signalsCount` maps to `ru_nsignals` but is not supported by any platform. +- `voluntaryContextSwitches` maps to `ru_nvcsw` which is the number of times +a CPU context switch resulted due to a process voluntarily giving up the +processor before its time slice was completed +(usually to await availability of a resource). +This field is not supported on Windows platforms. +- `involuntaryContextSwitches` maps to `ru_nivcsw` which is the number of times +a CPU context switch resulted due to a higher priority process becoming runnable + or because the current process exceeded its time slice. +This field is not supported on Windows platforms. + + +```js +console.log(process.resourceUsage()); +/* + Will output: + { + userCPUTime: 82872, + systemCPUTime: 4143, + maxRSS: 33164, + sharedMemorySize: 0, + unsharedDataSize: 0, + unsharedStackSize: 0, + minorPageFault: 2469, + majorPageFault: 0, + swapedOut: 0, + fsRead: 0, + fsWrite: 8, + ipcSent: 0, + ipcReceived: 0, + signalsCount: 0, + voluntaryContextSwitches: 79, + involuntaryContextSwitches: 1 + } +*/ +``` + ## process.send(message[, sendHandle[, options]][, callback])