From 6e5359349c0d6e2c9f786ecf9da3df1dad69d311 Mon Sep 17 00:00:00 2001 From: Lazizbek Ergashev Date: Wed, 5 Aug 2026 22:48:53 +0500 Subject: [PATCH 1/7] doc: document the --with-perfetto build flag Signed-off-by: Lazizbek Ergashev --- BUILDING.md | 15 +++++++++++++++ doc/api/cli.md | 5 ++++- doc/api/tracing.md | 8 ++++++++ 3 files changed, 27 insertions(+), 1 deletion(-) diff --git a/BUILDING.md b/BUILDING.md index e477d46863f4..64d4071fdc5f 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -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) @@ -1083,6 +1084,20 @@ 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. See [Trace events](doc/api/tracing.md) for how the output of such a +build differs. + ## Building Node.js with external core modules It is possible to specify one or more JavaScript text files to be bundled in diff --git a/doc/api/cli.md b/doc/api/cli.md index 2052f010f4bb..61f4129e6552 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -3302,7 +3302,9 @@ added: v9.8.0 --> Template string specifying the filepath for the trace event data, it -supports `${rotation}` and `${pid}`. +supports `${rotation}` and `${pid}`. It defaults to `node_trace.${rotation}.log`, +or to `node_trace.${rotation}.pftrace` when Node.js is built with the +`--with-perfetto` configure flag. See [Trace events][] for details. ### `--trace-events-enabled` @@ -4481,6 +4483,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 [ShadowRealm]: https://github.com/tc39/proposal-shadowrealm [Source Map]: https://tc39.es/ecma426/ [Test tags]: test.md#test-tags +[Trace events]: tracing.md [TypeScript type-stripping]: typescript.md#type-stripping [V8 Inspector integration for Node.js]: debugger.md#v8-inspector-integration-for-nodejs [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 577ec5c23cd8..eabfc64b93b0 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -102,6 +102,13 @@ string that supports `${rotation}` and `${pid}`: node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js ``` +Node.js can also be built with the `--with-perfetto` configure flag, described +in [BUILDING.md][]. Such a build writes [Perfetto](https://perfetto.dev/) +protobuf traces instead of JSON, so the default file name becomes +`node_trace.${rotation}.pftrace` and the files are opened at +[`ui.perfetto.dev`](https://ui.perfetto.dev/). JSON output is unavailable there, +as is trace collection over the inspector protocol. + To guarantee that the log file is properly generated after signal events like `SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers in your code, such as: @@ -361,6 +368,7 @@ async function collect() { collect(); ``` +[BUILDING.md]: https://github.com/nodejs/node/blob/HEAD/BUILDING.md#building-nodejs-with-perfetto-support [Performance API]: perf_hooks.md [V8]: v8.md [`Worker`]: worker_threads.md#class-worker From 228464b504fa281840639166904e2c54fd92fbb9 Mon Sep 17 00:00:00 2001 From: Lazizbek Ergashev Date: Wed, 5 Aug 2026 22:55:44 +0500 Subject: [PATCH 2/7] doc: clarify perfetto build limitations Signed-off-by: Lazizbek Ergashev --- doc/api/tracing.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/doc/api/tracing.md b/doc/api/tracing.md index eabfc64b93b0..1aafa6b71064 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -103,11 +103,10 @@ node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}. ``` Node.js can also be built with the `--with-perfetto` configure flag, described -in [BUILDING.md][]. Such a build writes [Perfetto](https://perfetto.dev/) -protobuf traces instead of JSON, so the default file name becomes -`node_trace.${rotation}.pftrace` and the files are opened at -[`ui.perfetto.dev`](https://ui.perfetto.dev/). JSON output is unavailable there, -as is trace collection over the inspector protocol. +in [BUILDING.md][]. Such a build writes [Perfetto][] protobuf traces instead of +JSON, so the default file name becomes `node_trace.${rotation}.pftrace` and the +files can be opened in [`ui.perfetto.dev`][]. It cannot write JSON traces, and +it does not support trace collection over the inspector protocol. To guarantee that the log file is properly generated after signal events like `SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers @@ -296,6 +295,9 @@ console.log(getEnabledCategories()); ### Collect trace events data by inspector +The `NodeTracing` domain is not registered in builds configured with +`--with-perfetto`. + ```mjs import { Session } from 'node:inspector'; const session = new Session(); @@ -369,7 +371,9 @@ collect(); ``` [BUILDING.md]: https://github.com/nodejs/node/blob/HEAD/BUILDING.md#building-nodejs-with-perfetto-support +[Perfetto]: https://perfetto.dev/ [Performance API]: perf_hooks.md [V8]: v8.md [`Worker`]: worker_threads.md#class-worker [`async_hooks`]: async_hooks.md +[`ui.perfetto.dev`]: https://ui.perfetto.dev/ From 5ac3533ef25b8d7c3916dadf285def635706ead8 Mon Sep 17 00:00:00 2001 From: Lazizbek Ergashev Date: Wed, 5 Aug 2026 23:16:16 +0500 Subject: [PATCH 3/7] doc: describe perfetto builds without naming the configure flag 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 --- doc/api/cli.md | 4 ++-- doc/api/tracing.md | 13 ++++++------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 61f4129e6552..e691568c9075 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -3303,8 +3303,8 @@ added: v9.8.0 Template string specifying the filepath for the trace event data, it supports `${rotation}` and `${pid}`. It defaults to `node_trace.${rotation}.log`, -or to `node_trace.${rotation}.pftrace` when Node.js is built with the -`--with-perfetto` configure flag. See [Trace events][] for details. +or to `node_trace.${rotation}.pftrace` in builds with Perfetto support. See +[Trace events][] for details. ### `--trace-events-enabled` diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 1aafa6b71064..3d027f6d1d98 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -102,11 +102,11 @@ string that supports `${rotation}` and `${pid}`: node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js ``` -Node.js can also be built with the `--with-perfetto` configure flag, described -in [BUILDING.md][]. Such a build writes [Perfetto][] protobuf traces instead of -JSON, so the default file name becomes `node_trace.${rotation}.pftrace` and the -files can be opened in [`ui.perfetto.dev`][]. It cannot write JSON traces, and -it does not support trace collection over the inspector protocol. +Node.js can also be built with [Perfetto][] support, as described in +[BUILDING.md][]. Such a build writes Perfetto protobuf traces instead of JSON, +so the default file name becomes `node_trace.${rotation}.pftrace` and the files +can be opened in [`ui.perfetto.dev`][]. It cannot write JSON traces, and it +does not support trace collection over the inspector protocol. To guarantee that the log file is properly generated after signal events like `SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers @@ -295,8 +295,7 @@ console.log(getEnabledCategories()); ### Collect trace events data by inspector -The `NodeTracing` domain is not registered in builds configured with -`--with-perfetto`. +The `NodeTracing` domain is not registered in builds with Perfetto support. ```mjs import { Session } from 'node:inspector'; From f32bee65bcee0ae37d0c96983f78d8ae876dd2e4 Mon Sep 17 00:00:00 2001 From: Lazizbek Ergashev Date: Wed, 5 Aug 2026 23:25:55 +0500 Subject: [PATCH 4/7] doc: use autolink for ui.perfetto.dev --- doc/api/tracing.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 3d027f6d1d98..2797171dea02 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -105,7 +105,7 @@ node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}. Node.js can also be built with [Perfetto][] support, as described in [BUILDING.md][]. Such a build writes Perfetto protobuf traces instead of JSON, so the default file name becomes `node_trace.${rotation}.pftrace` and the files -can be opened in [`ui.perfetto.dev`][]. It cannot write JSON traces, and it +can be opened in . It cannot write JSON traces, and it does not support trace collection over the inspector protocol. To guarantee that the log file is properly generated after signal events like @@ -375,4 +375,3 @@ collect(); [V8]: v8.md [`Worker`]: worker_threads.md#class-worker [`async_hooks`]: async_hooks.md -[`ui.perfetto.dev`]: https://ui.perfetto.dev/ From 9ea221de857d5025120ce0fcf7a5d4e36132245e Mon Sep 17 00:00:00 2001 From: Lazizbek Ergashev Date: Thu, 6 Aug 2026 05:46:52 +0500 Subject: [PATCH 5/7] doc: regenerate node.1 --- doc/node.1 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/node.1 b/doc/node.1 index 1098bcff047f..0c2cfaa745a7 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1599,7 +1599,9 @@ tracing is enabled using \fB--trace-events-enabled\fR. . .It Fl -trace-event-file-pattern Template string specifying the filepath for the trace event data, it -supports \fB${rotation}\fR and \fB${pid}\fR. +supports \fB${rotation}\fR and \fB${pid}\fR. It defaults to \fBnode_trace.${rotation}.log\fR, +or to \fBnode_trace.${rotation}.pftrace\fR in builds with Perfetto support. See +Trace events for details. . .It Fl -trace-events-enabled Enables the collection of trace event tracing information. From dc65fb20274cbf01de5ab2f319ef79e1df83b2b7 Mon Sep 17 00:00:00 2001 From: Lazizbek Ergashev Date: Thu, 6 Aug 2026 06:32:13 +0500 Subject: [PATCH 6/7] doc: keep perfetto docs in BUILDING.md only 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 --- BUILDING.md | 8 ++++++-- doc/api/cli.md | 5 +---- doc/api/tracing.md | 10 ---------- doc/node.1 | 4 +--- 4 files changed, 8 insertions(+), 19 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 64d4071fdc5f..34ea43950eea 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1095,8 +1095,12 @@ format instead: ``` The Perfetto SDK ships in `deps/perfetto`, so no additional dependency is -needed. See [Trace events](doc/api/tracing.md) for how the output of such a -build differs. +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 . It cannot write JSON traces, and it does +not support trace collection over the inspector protocol. ## Building Node.js with external core modules diff --git a/doc/api/cli.md b/doc/api/cli.md index e691568c9075..2052f010f4bb 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -3302,9 +3302,7 @@ added: v9.8.0 --> Template string specifying the filepath for the trace event data, it -supports `${rotation}` and `${pid}`. It defaults to `node_trace.${rotation}.log`, -or to `node_trace.${rotation}.pftrace` in builds with Perfetto support. See -[Trace events][] for details. +supports `${rotation}` and `${pid}`. ### `--trace-events-enabled` @@ -4483,7 +4481,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 [ShadowRealm]: https://github.com/tc39/proposal-shadowrealm [Source Map]: https://tc39.es/ecma426/ [Test tags]: test.md#test-tags -[Trace events]: tracing.md [TypeScript type-stripping]: typescript.md#type-stripping [V8 Inspector integration for Node.js]: debugger.md#v8-inspector-integration-for-nodejs [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 2797171dea02..577ec5c23cd8 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -102,12 +102,6 @@ string that supports `${rotation}` and `${pid}`: node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js ``` -Node.js can also be built with [Perfetto][] support, as described in -[BUILDING.md][]. Such a build writes Perfetto protobuf traces instead of JSON, -so the default file name becomes `node_trace.${rotation}.pftrace` and the files -can be opened in . It cannot write JSON traces, and it -does not support trace collection over the inspector protocol. - To guarantee that the log file is properly generated after signal events like `SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers in your code, such as: @@ -295,8 +289,6 @@ console.log(getEnabledCategories()); ### Collect trace events data by inspector -The `NodeTracing` domain is not registered in builds with Perfetto support. - ```mjs import { Session } from 'node:inspector'; const session = new Session(); @@ -369,8 +361,6 @@ async function collect() { collect(); ``` -[BUILDING.md]: https://github.com/nodejs/node/blob/HEAD/BUILDING.md#building-nodejs-with-perfetto-support -[Perfetto]: https://perfetto.dev/ [Performance API]: perf_hooks.md [V8]: v8.md [`Worker`]: worker_threads.md#class-worker diff --git a/doc/node.1 b/doc/node.1 index 0c2cfaa745a7..1098bcff047f 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1599,9 +1599,7 @@ tracing is enabled using \fB--trace-events-enabled\fR. . .It Fl -trace-event-file-pattern Template string specifying the filepath for the trace event data, it -supports \fB${rotation}\fR and \fB${pid}\fR. It defaults to \fBnode_trace.${rotation}.log\fR, -or to \fBnode_trace.${rotation}.pftrace\fR in builds with Perfetto support. See -Trace events for details. +supports \fB${rotation}\fR and \fB${pid}\fR. . .It Fl -trace-events-enabled Enables the collection of trace event tracing information. From 26297bcb84943afbf43cf6beca02935b20168ed6 Mon Sep 17 00:00:00 2001 From: Lazizbek Ergashev Date: Thu, 6 Aug 2026 07:08:46 +0500 Subject: [PATCH 7/7] doc: don't call inspector trace collection unsupported --- BUILDING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 34ea43950eea..86cf17aef23e 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1099,8 +1099,7 @@ 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 . It cannot write JSON traces, and it does -not support trace collection over the inspector protocol. +opened in . It does not support JSON traces output. ## Building Node.js with external core modules