doc: add useful v8 option section

nimit95 · targos · commit 00ce6a32404e · 2020-04-22T19:45:10.000+02:00
This adds new section for v8 options and --max-old-space-size Fixes: #32252 PR-URL: #32262 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -1384,6 +1384,30 @@ threadpool by setting the `'UV_THREADPOOL_SIZE'` environment variable to a value
 greater than `4` (its current default value). For more information, see the
 [libuv threadpool documentation][].
 
+## Useful V8 options
+
+V8 has its own set of CLI options. Any V8 CLI option that is provided to `node`
+will be passed on to V8 to handle. V8's options have _no stability guarantee_.
+The V8 team themselves don't consider them to be part of their formal API,
+and reserve the right to change them at any time. Likewise, they are not
+covered by the Node.js stability guarantees. Many of the V8
+options are of interest only to V8 developers. Despite this, there is a small
+set of V8 options that are widely applicable to Node.js, and they are
+documented here:
+
+### `--max-old-space-size=SIZE` (in Mbytes)
+
+Sets the max memory size of V8's old memory section. As memory
+consumption approaches the limit, V8 will spend more time on
+garbage collection in an effort to free unused memory.
+
+On a machine with 2GB of memory, consider setting this to
+1536 (1.5GB) to leave some memory for other uses and avoid swapping.
+
+```console
+$ node --max-old-space-size=1536 index.js
+```
+
 [`--openssl-config`]: #cli_openssl_config_file
 [`Buffer`]: buffer.html#buffer_class_buffer
 [`SlowBuffer`]: buffer.html#buffer_class_slowbuffer
