--max-semi-space-size doc is wrong after Node 18

[joebowbeer]

Affected URL(s)

https://github.com/nodejs/node/blob/main/doc/api/cli.md#--max-semi-space-sizesize-in-mib

Description of the problem

The docs read:

The default value is 16 MiB for 64-bit systems and 8 MiB for 32-bit systems. To get the best configuration for your application, you should try different max-semi-space-size values when running benchmarks for your application.

This may have been true in Node 18 but in the newer version of v8 (11.3) used in Node 20, the default scales with the memory limit, and will generally be less than this documented value.

See https://blog.ztec.fr/en/2024/post/node.js-20-upgrade-journey-though-unexpected-heap-issues-with-kubernetes/

Running the example from the docs on Node 18:

docker run -it -m 2g \
  -e NODE_OPTIONS="--max-old-space-size=1536" \
  node:18 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
1584

1584-1536 = 48MB = 3 x max-semi-space-size

Now in Node 20:

docker run -it -m 2g \
  -e NODE_OPTIONS="--max-old-space-size=1536" \
  node:20 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
1560

1560-1536 = 24MB, so max-semi-space-size defaults to 8 here 👈

In order to run with the same heap size limit in Node 20, you must explicitly set the max-semi-space-size:

docker run -it -m 2g \
  -e NODE_OPTIONS="--max-old-space-size=1536 --max-semi-space-size=16" \
  node:20 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
1584

👉 1584-1536 = 48MB, same as Node 18

[RedYetiDev]

PRs are always welcome :-)

[joebowbeer]

@RedYetiDev I'll try to determine where the crossover point is, that is, at what memory limit the new default equals the old default (2GB) and then I'll draft a true statement for the docs.

[joebowbeer]

The breakeven point in node:20 seems to be at memory limit 2g

docker run -it -m 3g \
  node:20 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
1584

docker run -it -m 3g \
  -e NODE_OPTIONS="--max-semi-space-size=16" \
  node:20 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
1584

node:18 seems to support the new NODE_OPTIONS

docker run -it -m 512m \
  -e NODE_OPTIONS="--max-old-space-size=384" \
  node:18 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
432

docker run -it -m 512m \
  -e NODE_OPTIONS="--max-old-space-size=384 --max-semi-space-size=16" \
  node:18 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
432

Without an explicit semi-space-size in node:20, the young generation in this case is only 3MB

docker run -it -m 512m \
  -e NODE_OPTIONS="--max-old-space-size=384" \
  node:20 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
387

Configuring semi-space-size, below, for same young generation size (48MB) as node:18

docker run -it -m 512m \
  -e NODE_OPTIONS="--max-old-space-size=384 --max-semi-space-size=16" \
  node:20 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'
432

node:14 fails the new option

docker run -it -m 512m \
  -e NODE_OPTIONS="--max-old-space-size=384 --max-semi-space-size=16" \
  node:14 node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1024))'

node: --max-semi-space-size= is not allowed in NODE_OPTIONS

[joebowbeer]

@RedYetiDev PR: #55495