initial stab at process.cpuUsage()

[pmuellr]

Pull Request check-list

Please make sure to review and check all of these items:

• Does make -j8 test (UNIX) or vcbuild test nosign (Windows) pass with
  this change (including linting)?
• Is the commit message formatted according to CONTRIBUTING.md?
• If this change fixes a bug (or a performance problem), is a regression
  test (or a benchmark) included?
• Is a documentation update included (if this change modifies
  existing APIs, or introduces new ones)?

NOTE: these things are not required to open a PR and can be done
afterwards / while the PR is open.

Affected core subsystem(s)

process

Description of change

Adds the function cpuUsage() to the global process object. Proposed doc is in the PR, and immediate below:

process.cpuUsage()

Returns the user and system cpu time usage of the current process, in an object with properties user and system, whose values are arrays of integers as [seconds, microseconds] tuples. These values measure time spent in user and system code respectively, and may end up being greater than actual elapsed time if multiple cpu cores are performing work for this process.

console.log(process.cpuUsage());
// { user: [ 0, 43979 ], system: [ 0, 12423 ] }

setTimeout(() => {
  var startTime = process.hrtime();

  // spin the CPU for 500 milliseconds
  while (true) {
    var time = process.hrtime(startTime);

    // calculate elapsed wall clock time in millis
    var elapsed = time[0] * 1000 + time[1] / 1000 / 1000;

    if (elapsed > 500) break;
  }

  console.log(process.cpuUsage());
  // { user: [ 0, 554966 ], system: [ 0, 14881 ] }
}, 1000);

[mscdex]

s/reassembed/reassembled/

[Trott]

Should get at least a minimal test that confirms the object returned by process.cpuUsage() conforms with what is documented.

[pmuellr]

Should get at least a minimal test that confirms the object returned by process.cpuUsage() conforms with what is documented.

absolutely @Trott

Figured I'd do the minimal work to see if there's even interest in this, if the approach is generally correct, etc.

The most basic test is to ensure that subsequent values are monotonically increasing, or the same. Would be nice to have one that slept for a 100 ms or so, and then made sure the old / new values were within some range of reasonable-ness, but I fear could easily become flaky. I will also peek at libuv's tests for this.

BTW, purty sure this my first Node.js PR!

[evanlucas]

I really like the idea, but should we be adding this onto process? I think we should try to avoid adding anything to process unless absolutely necessary. Maybe a metrics builtin or something like that?

[YurySolovyov]

Maybe put it to os module?

[mscdex]

The os module is typically for more global stuff. I think process is a good fit for it, whether it should go directly on it or whether it and memoryUsage() would go on a new .metrics-like namespace like @evanlucas suggested.

[ronkorving]

To avoid confusion in user land (ie: to maintain a level of consistency), would it make sense to turn them into nanoseconds?

[pmuellr]

Have to admit, I'm a bit torn on this:

• on one hand, rusage() returns seconds / microseconds, and so I'd kinda like to match that
• on the other hand, process.hrtime() returns [seconds, nanoseconds], so would be nice to be consistent

I'm kinda leaning towards your suggestion, returning [seconds, nanoseconds], especially since folks may be using both hrtime() and cpuUsage() together, to get a "cpu usage %" type value.

If we want to do that, then I think we'd just doc that the resolution is currently at the microsecond level, but the value returned is nanoseconds.

[pmuellr]

If we align more with hrtime(), perhaps it also makes sense to provide a "diff" function, like hrtime(), where if you pass a previous result of cpuUsage() into the function, it will return a "diff" of the times, instead of the current time. For one of the primary use cases I'm considering, I'd be wanting a diff anyway, so this cuts down a little bit on the amount of code I'd be writing.

[ronkorving]

That's interesting. Would love to see some feedback from others on this.

[eljefedelrodeodeljefe]

generally +1. I'd favor nanoseconds for consistency also. Also +1 on the diffing. Would be nicely consistent to vanilla js also.

Just a quick thought: Maybe it's worth taking this even further, whether let p = process.cpuUsage(); p.diff(); p.diff() might be a thing.

[jasnell]

Needs some form of test case but generally LGTM

[Fishrock123]

@pmuellr Could you go over the checklist in the OP? Thanks! :D

[pmuellr]

@Fishrock123 sure; let me refresh the code given the changes mentioned here (still in process, but doing the diff, and using nanos instead of micros), add some tests, and I'll ensure the checklist is ready to go. Prolly end of this week.

[pmuellr]

My git foo is weak. The rebases I've done on my clone/fork look ok, but in the PR, they're pulling in stuff from the old branch I started on (some 5.x branch, which was incorrect, shouda been master from the start).

So, giving up on this branch / PR.

I've got a clean branch / PR here as a replacement: #6157