Tier of Support: V8 CodeEventHandler API current state

[Drieger]

I tried to summarize current state of requisites for V8 Code Event Handler API. Requisites are taken from Tier 1 (most complete set of requirements).

There are some requirements that seem to be subjective (at least to me), which means it's not clear if a tool fulfills it or not.

Requisites

• Must always be working (CI tests passing) for all LTS Node.js
• Have a good test suite
• Test suite job must exist in Node.js CI
• The maintainers of the tool must remain responsive when there are problems (Subjective)
• The tool must be actively used by the ecosystem (Subjective)
• The tool must be heavily depended on (Subjective)
• The tool must have a guide or other documentation in the Node.js GitHub organization or website
• The tool must be working on all supported platforms
• The tool must only be using APIs exposed by Nodejs as opposed to its dependencies
• The tool must be open source.

Tool Analysis

Name	V8 CodeEventHandler API
URL	https://github.com/v8/v8/blob/master/src/api.cc#L10219
Type	Profiling
Target Tier	2

Requisite	Status	Observation
Must always be working (CI tests passing) for all LTS Node.js	Ok	Tool is working for all LTS Node.js - each with its own V8 version
Have a good test suite	Ok	Test suite exists in V8
Test suite job must exist in Node.js CI	Maybe	V8 tests only, but it should be ok
The maintainers of the tool must remain responsive when there are problems	Ok	This is mantained as part of V8, so should be ok
The tool must be actively used by the ecosystem	Maybe	It is hard to define it, specially if we think that the ecosystem could be only people interested in diagnostics/profiling/...
The tool must be heavily depended on	Maybe	Diagnostic/analysis tools are almost never depended on to run systems. Maybe a better definition of what 'heavily depended on' means is necessary
The tool must have a guide or other documentation in the Node.js GitHub organization or website	Fail	The tool doesn't have any guide in the Node.js Github organization or website.
The tool must be working on all supported platforms	Ok	Works on all platforms where V8 is also working
The tool must only be using APIs exposed by Nodejs as opposed to its dependencies	Fail	The tool is an API itself, so it must use dependencies (but it uses dependencies in V8)
The tool must be open source	Ok	Ok, the tool is part of V8 and is open source

Based on this it is possible to have a more clear view of the current state and what is necessary to work on to move V8 Code Event Handler API to target tier. It is also an opportunity to debate if requirements are correct. Any ideas and opinions are welcome.

[mcollina]

I think the tool is not easily discoverable/usable by the community. I don't really know what it is for, how I can use it, and why we need this at Tier 1 or Tier 2.

Overall we should plan to either a) expose it somehow through Node.js or b) wrap into a binary module and ship it to NPM. And then document it ;).

[vmarchaud]

We tried to play around at @keymetrics without success since it's not really documented in the V8 side either. From these research we believe the only use of this API right now in NodeJS is to be able to resolve js symbol (toggled with --perf flag) for perf.

I would love to commit some time to build a higher level API, but it would need some targeted use cases before.

[mmarchini]

I don't really know what it is for, how I can use it, and why we need this at Tier 1 or Tier 2.

The CodeEventHandler API was created as a generic mechanism to collect information about JIT generated code. With this API we can implement --perf-basic-prof and --perf-prof in user-land (see mmarchini/node-linux-perf), removing the dependency on those (unsupported) V8 flags for system profilers. Implementing these flags in user-land also allow for more sophisticated features, such as runtime togglable generation of perf map files.

Alone this API doesn't do much, but it can allow other tools (such as Linux perf, bpftrace, dtrace, etc.) to understand JIT frames on the process stack.

[github-actions[bot]]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.

[theanarkh]

I don't really know what it is for, how I can use it, and why we need this at Tier 1 or Tier 2.

The CodeEventHandler API was created as a generic mechanism to collect information about JIT generated code. With this API we can implement --perf-basic-prof and --perf-prof in user-land (see mmarchini/node-linux-perf), removing the dependency on those (unsupported) V8 flags for system profilers. Implementing these flags in user-land also allow for more sophisticated features, such as runtime togglable generation of perf map files.

Alone this API doesn't do much, but it can allow other tools (such as Linux perf, bpftrace, dtrace, etc.) to understand JIT frames on the process stack.

hello, will nodejs support runtime togglable generation of perf map files like node-linux-perf do ?

[Qard]

It can also enable support of userland profilers. I built a cpu profiler with it external to V8 by pairing it with v8::Isolate::GetStackSample().

[theanarkh]

It can also enable support of userland profilers. I built a cpu profiler with it external to V8 by pairing it with v8::Isolate::GetStackSample().

Can you provide some example code or document ? Thanks.

[Qard]

Here's some code demonstrating it: https://github.com/DataDog/pprof-nodejs/pull/23

[theanarkh]

Here's some code demonstrating it: DataDog/pprof-nodejs#23

Thanks !

[github-actions[bot]]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.