What do the return values of node.js process.memoryUsage() stand for?

From the official documentation (source):

> process.memoryUsage() > > Returns an object describing the memory usage of the Node process > measured in bytes. > > var util = require('util'); >
> console.log(util.inspect(process.memoryUsage())); > > This will generate: > > { rss: 4935680, heapTotal: 1826816, heapUsed: 650472 } > > heapTotal and heapUsed refer to V8's memory usage.

Exactly what do rss, heapTotal, and heapUsed stand for?

It might seem like a trivial question, but I've been looking and I could not find a clear answer so far.

In order to answer this question, one has to understand V8’s Memory Scheme first.

A running program is always represented through some space allocated in memory. This space is called Resident Set. V8 uses a scheme similar to the Java Virtual Machine and divides the memory into segments:

• Code: the actual code being executed
• Stack: contains all value types (primitives like integer or Boolean) with pointers referencing objects on the heap and pointers defining the control flow of the program
• Heap: a memory segment dedicated to storing reference types like objects, strings and closures.

Now it is easy to answer the question:

• rss: Resident Set Size
• heapTotal: Total Size of the Heap
• heapUsed: Heap actually Used

Ref: http://apmblog.dynatrace.com/2015/11/04/understanding-garbage-collection-and-hunting-memory-leaks-in-node-js/

RSS is the resident set size, the portion of the process's memory held in RAM (as opposed to the swap space or the part held in the filesystem).

The heap is the portion of memory from which newly allocated objects will come from (think of malloc in C, or new in JavaScript).

You can read more about the heap at Wikipedia.

The Node.js documentation describes it as follows:

> heapTotal and heapUsed refer to V8's memory usage. external refers to > the memory usage of C++ objects bound to JavaScript objects managed by > V8. rss, Resident Set Size, is the amount of space occupied in the > main memory device (that is a subset of the total allocated memory) > for the process, which includes the heap, code segment and stack.

All mentioned values are expressed in bytes. So, if you just want to print them, you probably want to rescale them to MB:

const used = process.memoryUsage();
for (let key in used) {
  console.log(`Memory: ${key} ${Math.round(used[key] / 1024 / 1024 * 100) / 100} MB`);
}

That will give you an output like:

Memory: rss 522.06 MB
Memory: heapTotal 447.3 MB
Memory: heapUsed 291.71 MB
Memory: external 0.13 MB

Let's do this with an Example

The following example will show you how the increase in memory usage will actually increase the rss and heapTotal

const numeral = require('numeral');
let m = new Map();
for (let i = 0; i < 100000; i++) {
    m.set(i, i);
    if (i % 10000 === 0) { 
        const { rss, heapTotal } = process.memoryUsage();
        console.log( 'rss', numeral(rss).format('0.0 ib'), heapTotal, numeral(heapTotal).format('0.0 ib') )
    } 
}

Running The above will give you something like this:

rss 22.3 MiB 4734976 4.5 MiB
rss 24.2 MiB 6483968 6.2 MiB
rss 27.6 MiB 9580544 9.1 MiB
rss 27.6 MiB 9580544 9.1 MiB
rss 29.3 MiB 11419648 10.9 MiB
rss 29.3 MiB 11419648 10.9 MiB
rss 29.3 MiB 11419648 10.9 MiB
rss 32.8 MiB 15093760 14.4 MiB
rss 32.9 MiB 15093760 14.4 MiB
rss 32.9 MiB 15093760 14.4 MiB

This clearly shows you how using variable and continuously incrementing the space required by it increases the heapTotal and correspondingly the Resident Set Size(rss)

RSS is a reasonable measure for the "total memory usage of the Node.js interpreter process". You simply be able to run your program if that goes above the available RAM. Note however that it excludes some types of memory, so the actual memory consumption on a server that just runs a single process could be higher (VSZ is the worst case).

The concept of RSS is defined in the Linux kernel itself as mentioned at: https://stackoverflow.com/questions/7880784/what-is-rss-and-vsz-in-linux-memory-management and measures the total memory usage of the process. This value can therefore be measured by external programs such as ps without knowledge of Node.js internals, e.g. as shown at: https://stackoverflow.com/questions/1221555/retrieve-cpu-usage-and-memory-usage-of-a-single-process-on-linux/40576129#40576129

heapTotal and heapUsed are concepts internal to the Node.js implementation. It would be good to look at the v8 source code to understand them more precisely, notably I wonder if they just obtain those values from glibc with functions such as those mentioned at: https://stackoverflow.com/questions/41093780/api-call-to-get-current-heap-size-of-process of if it has its own heap management done on top of it.

For the concept of heap in general see also: https://stackoverflow.com/questions/79923/what-and-where-are-the-stack-and-heap and https://stackoverflow.com/questions/4584089/what-is-the-function-of-the-push-pop-instructions-used-on-registers-in-x86-ass/33583134#33583134 The heap is overwhelmingly likely to take the majority of memory in a JavaScript program, I don't think you will ever bother to try and look for that memory elsewhere (besides perhaps typed arrays perhaps, which show separately under process.memoryUsage()).

The following code example can be used to do simple tests which I have tried to analyze at: https://cirosantilli.com/javascript-memory-usage-benchmark But unlike languages without garbage collection like C++, it is very difficult to predict why memory usage is so overblown sometimes, especially when we have smaller numbers of objects. I'm not sure other garbage collected languages do any better though.

You have to run the program with:

node --expose-gc main.js

main.js

#!/usr/bin/env node

// CLI arguments.
let arr = false
let array_buffer = false
let dealloc = false
let klass = false
let obj = false
let n = 1000000
let objn = 0
for (let i = 2; i < process.argv.length; i++) {
  switch (process.argv[i]) {
    case 'arr':
      arr = true
    break
    case 'array-buffer':
      array_buffer = true
    break
    case 'class':
      klass = true
    break
    case 'dealloc':
      dealloc = true
    break
    case 'obj':
      obj = true
    break
    case 'n':
      i++
      n = parseInt(process.argv[i], 10)
    break
    case 'objn':
      i++
      objn = parseInt(process.argv[i], 10)
    break
    default:
      console.error(`unknown option: ${process.argv[i]}`);
    break
  }
}

class MyClass {
  constructor(a, b) {
    this.a = a
    this.b = b
  }
}

let a
if (array_buffer) {
  a = new Int32Array(new ArrayBuffer(n * 4))
  for (let i = 0; i < n; i++) {
    a[i] = i
  }
} else if (obj) {
  a = []
  for (let i = 0; i < n; i++) {
    a.push({ a: i, b: -i })
  }
} else if (objn) {
  a = []
  for (let i = 0; i < n; i++) {
    const obj = {}
    for (let j = 0; j < objn; j++) {
      obj[String.fromCharCode(65 + j)] = i
    }
    a.push(obj)
  }
} else if (klass) {
  a = []
  for (let i = 0; i < n; i++) {
    a.push({ a: i, b: -i })
  }
} else if (klass) {
  a = []
  for (let i = 0; i < n; i++) {
    a.push(new MyClass(i, -i))
  }
} else if (arr) {
  a = []
  for (let i = 0; i < n; i++) {
    a.push([i, -i])
  }
} else {
  a = []
  for (let i = 0; i < n; i++) {
    a.push(i)
  }
}

if (dealloc) {
  a = undefined
}

let j
while (true) {
  if (!dealloc) {
    j = 0
    // The collector somehow removes a if we don't reference it here.
    for (let i = 0; i < n; i++) {
      if (obj || klass) {
        j += a[i].a + a[i].b
      } else if (objn) {
        const obj = a[i]
        for (let k = 0; k < objn; k++) {
          j += obj[String.fromCharCode(65 + k)]
        }
      } else if (arr) {
        j += a[i][0] + a[i][1]
      } else {
        j += a[i]
      }
    }
    console.error(j)
  }
  global.gc()
  console.error(process.memoryUsage())
}

Some things we learn on Node 16 Ubuntu 21.10:

• with node --expose-gc bench_mem.js n 1 we see that the minimum RSS is 30 MiB and the minimum heapUsed 3.7 MB. RSS for a C hello world on the same system is 770 kB for comparison