Skip to content

doc: document the --with-perfetto build flag #65056

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lazerg wants to merge 6 commits into
base: main
Choose a base branch
from
+19 −0
Open

doc: document the --with-perfetto build flag #65056

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6e53593
doc: document the --with-perfetto build flag
lazerg Aug 5, 2026
228464b
doc: clarify perfetto build limitations
lazerg Aug 5, 2026
5ac3533
doc: describe perfetto builds without naming the configure flag
lazerg Aug 5, 2026
f32bee6
doc: use autolink for ui.perfetto.dev
lazerg Aug 5, 2026
9ea221d
doc: regenerate node.1
lazerg Aug 6, 2026
dc65fb2
doc: keep perfetto docs in BUILDING.md only
lazerg Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ file a new issue.
* [Configuring OpenSSL config appname](#configure-openssl-appname)
* [Building Node.js with FIPS-compliant OpenSSL](#building-nodejs-with-fips-compliant-openssl)
* [Building Node.js with Temporal support](#building-nodejs-with-temporal-support)
* [Building Node.js with Perfetto support](#building-nodejs-with-perfetto-support)
* [Building Node.js with external core modules](#building-nodejs-with-external-core-modules)
* [Unix/macOS](#unixmacos-4)
* [Windows](#windows-5)
Expand Down Expand Up @@ -1083,6 +1084,24 @@ a warning is printed and Temporal support is disabled.

Passing both options to `configure.py` is an error.

## Building Node.js with Perfetto support

Trace events are recorded in JSON by default. Pass `--with-perfetto` to
`configure.py` to record them in the [Perfetto](https://perfetto.dev/) protobuf
format instead:

```bash
./configure --with-perfetto
```

The Perfetto SDK ships in `deps/perfetto`, so no additional dependency is
needed.

Such a build writes Perfetto protobuf traces instead of JSON, so the default
trace file name becomes `node_trace.${rotation}.pftrace` and the files can be
opened in <https://ui.perfetto.dev>. It cannot write JSON traces, and it does
not support trace collection over the inspector protocol.
Comment on lines +1102 to +1103

@legendecas legendecas Aug 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The inspector support was only an intermediate state. It is not intended "not supported".

Suggested change
opened in <https://ui.perfetto.dev>. It cannot write JSON traces, and it does
not support trace collection over the inspector protocol.
opened in <https://ui.perfetto.dev>. It does not support JSON traces output.


## Building Node.js with external core modules

It is possible to specify one or more JavaScript text files to be bundled in
Expand Down