node --prof documentation missing from --help output

[joliss]

• Version: v14.5.0
• Platform: Linux

The node --prof option is documented on the website, but it's missing from the output of node --help.

[mmarchini]

I believe that's on purpose for the best since it is a V8 flag and is not officially supported by the V8 team (meaning it could get removed or the behavior could drastically change at any point). Besides, the help message is available via node --v8-options.

(edit: not sure if it was under documented on purpose or not, but I do believe describing too much what it does would be counter-productive)

[mmarchini]

With that being said, we could explain a bit more and add a link to https://nodejs.org/en/docs/guides/simple-profiling/ to explain how to consume the profile output, although I think we should highlight that this flag is provided by V8 and therefore has less stability guarantees than flags maintained by Node.js.

[joliss]

I think just giving a hint might be useful. I found the --prof option on some blog post I found on Google, and it seemed to be doing something, but I was very confused when I didn't see it at least mentioned in --help.

[mmarchini]

--prof is a V8 option, not a Node.js option. As a rule of thumb, we don't include V8 options on --help since those are not maintained by us*. --v8-options prints the help message from V8 with all V8 options. Would a message on top of --help like the list below includes only Node.js options. If you're looking for an option not listed below, check "--v8-options" for options provided by V8 help? Or we could add another section "Commonly Used V8 Options" (which is very subjective), although I'd rather not since we've been instructed several times by the V8 team to avoid documenting their flags since there's no stability guarantees for most of them.

FWIW, this is why I'm in favor of changing how we handle V8 options so instead of verbatim using them like --prof we would pass them as --v8-option="--prof", it makes explicit to the users that those options are not provided by Node.js.

* I see we have --abort-on-uncaught-exception on --help. V8 provides that flag but we implemented different behavior on top of V8, which makes it a hybrid V8/Node.js flag

[ghost]

Actually, both options sound good. Though the first one requires less effort. However, the second one will be better in the long run IMO

[VikiD]

As a follow up regarding nodejs, you should check this article, might be useful for general info.
https://os-system.com/blog/12-types-of-node-js-applications-with-examples/

[Ayase-252]

As I understand, it has been addressed by #34991 . Since it has been landed and I can verify the —prof doc is shown when exec node —help, I think the issue has been resolved, I will close the issue. Please feel free to reopen it, if you have further concerns.