Unverified Commit ae6406af authored by Benjamin Woodruff's avatar Benjamin Woodruff Committed by GitHub

docs(turbopack): Copy over turbopack-trace-server docs (#91111)

**Rendered:** https://github.com/vercel/next.js/blob/dd1cc6fba3cff5fbc38dac3ff4426b481bfcbcb5/contributing/turbopack/tracing.md

This is the content from https://turbopack-rust-docs.vercel.sh/tracing_turbopack.html with some minor updates:

- Use GitHub Flavored Markdown for the warning block
- Some grammar fixes/tweaks
- Add an extra note about `--release` being important
- Add a mention of `pnpm next internal trace`
- Add a link to @timneutkens's youtube video
- Change the filepath from the old confusingly named `.next/trace.log` to `.next/trace-turbopack`
- Add a link to https://trace.nextjs.org/
parent 2ecfbfc1
......@@ -25,3 +25,7 @@
- [Adding a new feature](./contributing/core/adding-features.md)
- [Developing Using Local App](./contributing/core/developing-using-local-app.md)
<!-- - [Using the VS Code Debugger](./contributing/core/vscode-debugger.md) -->
## Turbopack
- [Tracing](./contributing/turbopack/tracing.md)
# Tracing Turbopack
`turbo-tasks` comes with a tracing feature that allows to keep track of executions and their runtime and memory consumption. This is useful to debug and optimize the performance of Turbopack.
## Logging
Inside of Next.js one can enable tracing with the `NEXT_TURBOPACK_TRACING` environment variable.
It supports [the following special preset values][presets]:
- **`1` or `overview`:** Basic user level tracing is enabled. (This is the only preset available in a published Next.js release)
- **`next`:** Same as `overview`, but with lower-level `debug` and `trace` logs for Next.js's own crates
- **`turbopack`:** Same as `next`, but with lower-level `debug` and `trace` logs for Turbopack's own crates
- **`turbo-tasks`:** Same as `turbopack`, but also with verbose tracing of every Turbo-Engine function execution.
Alternatively, any directives syntax supported by [`tracing_subscriber::filter::EnvFilter`][directives] can be used.
> [!WARNING]
> A normal Next.js canary/stable release only includes the info level tracing. This is the tracing level intended for user-facing tracing.
>
> For the more detailed tracing a custom Next.js build is required. See [Developing] for more information how to create one.
With this environment variable, Next.js will write a `.next/trace-turbopack` file with the tracing information in a binary format.
[presets]: https://github.com/vercel/next.js/blob/c506c0de1d6f17ad400ad5aa85edaae23b6b44d2/packages/next-swc/crates/napi/src/next_api/project.rs#L218
[directives]: https://tracing.rs/tracing_subscriber/filter/struct.envfilter#directives
[Developing]: ../core/developing.md
## Viewer
To visualize the content of `.next/trace-turbopack`, use the [turbo-trace-viewer].
A video showing how to use the tool [is available here][youtube-tutorial].
This tool connects a WebSocket on port 57475 on localhost to connect to the trace-server. You can start the trace-server with the following command:
```sh
cargo run --bin turbo-trace-server --release -- /path/to/your/trace-turbopack
# or
pnpm next internal trace .next/trace-turbopack
```
Once the server is started, open <https://trace.nextjs.org/> in your browser.
> [!TIP]
> Make sure you're using a `--release` build when running the trace server. The trace server is very slow and this can make a very significant (10x) difference in performance.
The trace viewer allows to switch between multiple different visualization modes:
- **Aggregated spans:** Spans with the same name in the same parent are grouped together.
- **Individual spans:** Every span is shown individually.
- **... in order:** Spans are shown in the order they occur.
- **... by value:** Spans are sorted and spans with the largest value are shown first.
- **Bottom-up view:** Instead of showing the total value, the self value is shown.
And there different value modes:
- **Duration:** The CPU time of each span is shown.
- **Allocated Memory:** How much memory was allocated during the span.
- **Allocations:** How many allocations were made during the span.
- **Deallocated Memory:** How much memory was deallocated during the span.
- **Persistently allocated Memory:** How much memory was allocated but not deallocated during the span. It survives the span.
[turbo-trace-viewer]: https://turbo-trace-viewer.vercel.app/
[youtube-tutorial]: https://www.youtube.com/watch?v=PGO2szAye7A
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment