lib: add util.getCallSite() API

[RafaelGSS]

This pull request introduces a new API method, util.getCallSite(), which provides a way to capture and inspect the call stack within a Node.js application. The method returns an array of CallSite objects, so developers can retrieve information about each function call in the stack trace.

Previously, they could reach the same behaviour by using Error.prepareStackTrace but, this API isn't that friendly IMO.

[codecov]

Codecov Report

Attention: Patch coverage is 95.91837% with 2 lines in your changes missing coverage. Please review.

Project coverage is 87.60%. Comparing base (298dea0) to head (aa11f56).
Report is 250 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_util.cc	94.59%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #54380      +/-   ##
==========================================
- Coverage   87.61%   87.60%   -0.01%     
==========================================
  Files         650      650              
  Lines      182829   182878      +49     
  Branches    35382    35390       +8     
==========================================
+ Hits       160179   160210      +31     
  Misses      15931    15931              
- Partials     6719     6737      +18     

Files with missing lines	Coverage Δ
lib/util.js	95.91% <100.00%> (+0.12%)	⬆️
src/node_util.cc	85.77% <94.59%> (+1.61%)	⬆️

... and 29 files with indirect coverage changes

[H4ad]

Should we add an option to ignore node:internal?

Also, I think we should pretty print the callsite object, if we console.log it:

[
  CallSite {},
  CallSite {},
  CallSite {},
  CallSite {},
  CallSite {},
  CallSite {},
  CallSite {},
  CallSite {}
]

If we JSON.stringify:

[{},{},{},{},{},{},{},{}]

And maybe we should add some snapshot tests, I know they could break if we change/add the methods that call them but usually they are great to track regressions, I know we have a couple snapshot tests like that in our codebase.

In general, looks great to me to have a utility function like this.

[RafaelGSS]

I'd not include an option to ignore it in this initial version - maybe a follow up pr once it's landed?

It's not supposed to be printed via console.log because it's a CallSite representation. I will modify the API so it retrieves the stack trace from C++, and this should address this issue with the new object

[H4ad]

I'm fine landing it with this js version, just include a benchmark and then we can evaluate if the new c++ version will be faster.

Also, having some snapshot tests will be good to see what will change when we land the c++ version.

[RafaelGSS]

C++ version will be landed on this PR. I didn't have time yet.

[mugli]

Is the new API going to work for events like unhandledRejection?

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/61255/

[mcollina]

lgtm

Did you do a benchmark?

[RafaelGSS]

lgtm

Did you do a benchmark?

I did, but without having a fair comparison I don't know if it will mean much:

From my local machine

util/get-callsite.js n=1000000: 178,641.08162235853

I suspect the C++ implementation will be slower than the JS one for this particular scenario. We need to iterate over v8::StackTrace to create objects while the JS approach does not compute the values unless the function is called. e.g: .getFileName(). So the comparison will be unfair.

But, remember that we've switched to C++ for a side-effect-less approach. I can optimize this code later.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/61886/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/61893/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/61917/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/61928/

[nodejs-github-bot]

Landed in 80a989f