Skip to content

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

Open
lazerg wants to merge 7 commits into
nodejs:mainfrom
lazerg:fix/issue-65055-doc-perfetto
Open

doc: document the --with-perfetto build flag#65056
lazerg wants to merge 7 commits into
nodejs:mainfrom
lazerg:fix/issue-65055-doc-perfetto

Conversation

@lazerg

@lazerglazerg commented Aug 5, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

The perfetto tracing support added in #64565 was never documented, so there is
no way to find out from the docs that the --with-perfetto configure flag
exists or what it changes.

This adds a short BUILDING.md section for the flag. The trace events and CLI
docs do not name the configure flag. They only describe how a perfetto build
behaves: traces come out as perfetto protobuf, the default trace file name
becomes node_trace.${rotation}.pftrace, and JSON output and inspector-based
collection are not available.

Fixes: #65055

@nodejs-github-bot

nodejs-github-bot commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/build
  • @nodejs/tsc

@nodejs-github-botnodejs-github-bot added build Issues and PRs related to build files or the CI. doc Issues and PRs related to the documentations. labels Aug 5, 2026
avivkeller
avivkeller requested changes Aug 5, 2026
View reviewed changes

@avivkelleravivkeller left a comment

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.

We usually don't document configure flags in doc/api, only in the non-user facing docs

@lazerg

lazerg commented Aug 5, 2026

Copy link
Copy Markdown
ContributorAuthor

I checked doc/api before changing this. A few files there do name configure flags. intl.md has an "Options for building Node.js" section with --with-intl and --with-icu-default-data-dir, including ./configure examples. dtls.md says the module must be enabled at build time with the --experimental-dtls configure flag. ffi.md names --shared-ffi, and crypto.md shows ./configure --openssl-conf-name=<name>.

cli.md is different though. It never names a configure flag anywhere. It describes the build condition by its effect instead, like "only available in builds with FFI support" for --experimental-ffi. My line was the only exception in that file, so you are right about it.

I pushed a change that keeps --with-perfetto in BUILDING.md only. cli.md and tracing.md now say "builds with Perfetto support" and link to BUILDING.md for the flag itself.

I kept the behavior text. --trace-event-file-pattern really does default to a different extension in such a build, and NodeTracing is not registered. That is runtime behavior an API reader can hit, so it seemed worth keeping in doc/api. Happy to drop it if you still think it belongs only in BUILDING.md.

avivkeller
avivkeller reviewed Aug 5, 2026
View reviewed changes
Comment threaddoc/api/tracing.md Outdated
legendecas
legendecas reviewed Aug 6, 2026
View reviewed changes
Comment threaddoc/node.1 Outdated
legendecas
legendecas reviewed Aug 6, 2026
View reviewed changes

@legendecaslegendecas left a comment

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 build-time flag is not mature enough yet. I'd prefer documenting in BUILDING.md only.

@lazerg

lazerg commented Aug 6, 2026•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Makes sense, I'll trim it down to BUILDING.md only.
Let me know if anything else is needed to get this mergeable.

@lazerg
doc: document the --with-perfetto build flag
6e53593
Signed-off-by: Lazizbek Ergashev <lazerg2@gmail.com>
@lazerg
doc: clarify perfetto build limitations
228464b
Signed-off-by: Lazizbek Ergashev <lazerg2@gmail.com>
@lazerg
doc: describe perfetto builds without naming the configure flag
5ac3533
Keep the --with-perfetto flag itself documented in BUILDING.md and refer
to a perfetto build by its observable behavior in doc/api, matching how
cli.md already describes FFI-gated builds.
Signed-off-by: Lazizbek Ergashev <lazerg2@gmail.com>
@lazerg
doc: use autolink for ui.perfetto.dev
f32bee6
@lazerg
doc: regenerate node.1
9ea221d
@lazerg
doc: keep perfetto docs in BUILDING.md only
dc65fb2
Revert the doc/api/tracing.md and doc/api/cli.md changes so that the
perfetto build is described in one place; the build-time flag is not
mature enough to document in the API docs yet. doc/node.1 is left as
upstream's already-regenerated version.
Signed-off-by: Lazizbek Ergashev <lazerg2@gmail.com>
@lazerg
lazergforce-pushed the fix/issue-65055-doc-perfetto branch from 41ac864 to dc65fb2CompareAugust 6, 2026 01:35
legendecas
legendecas reviewed Aug 6, 2026
View reviewed changes
Comment threadBUILDING.md Outdated
@legendecas

legendecas commented Aug 6, 2026

Copy link
Copy Markdown
Member

Thanks!

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@avivkelleravivkelleravivkeller approved these changes
@legendecaslegendecaslegendecas approved these changes
+1 more reviewer
@AugustinMauroyAugustinMauroyAugustinMauroy approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

buildIssues and PRs related to build files or the CI.docIssues and PRs related to the documentations.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

doc(cli-flag): missing perfetto

5 participants

@lazerg@nodejs-github-bot@legendecas@avivkeller@AugustinMauroy