doc: add useful v8 option section

This adds new section for v8 options and --max-old-space-size
Fixes: https://github.com/nodejs/node/issues/32252

PR-URL: https://github.com/nodejs/node/pull/32262
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>

1 files changed, 24 insertions, 0 deletions

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 386d9cdb96e..535a139b41d 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1419,6 +1419,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