doc: `--max-old-space-size` should be documented

[addaleax]

Even though --max-old-space-size is a V8 flag, I would expect us to document it, given that it’s probably the most useful V8 flag for Node.js users overall.

Refs: #32251

[jasnell]

+1 ... Let's just make sure that v8 flags that are documented are separated off in their own section of cli.md with clear indication in the docs that they fall outside Node.js' responsibility and therefore cannot be covered by the semver rules. Beyond that, I'm very much +1 on documenting useful v8 options.

Obviously, we should get @nodejs/v8 folks to review those first tho ;-)

[nimit95]

If this is a good first issue, I would like to work on it. :)

[jasnell]

@nimit95 ... definitely a good first issue. It would be good to include some explanation around best practices in use, at least in the cli.md doc part.

[nimit95]

Will make a PR and submit.

[juanarbol]

@nimit95 You already made the changes, great! It would nice if you open the PR now.

[sideburnie]

I'm not sure this is the right place to go, but is there any documentation of the maximum size of max-old-space-size (or the max heap size V8 will allow)?

On a machine with 256GB of ram another with 768GB of ram with a max-old-space-size of 200gb and 500gb with v14.15.1, I'm not seeing a heap larger than about 16GB regardless of max-old-space-size. Calling v8.getHeapStatistics() shows a heap_size_limit that matches my given max-old-space-size but total_heap_size never goes above above 16GB. I've tried with optimize-for-size and without.

I'm now finding that an older version that I had been using, v10.16.0, appears to use at least 32GB... still experimenting... but if there's a doc somewhere that specifies the actual max heap allowed (maybe by version?) I would definitely read it! TIA!

[edit]: well it looks like v10.16.0 crashes at about 33GB with a 500GB max-old-space-size...