Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tracing Turbopack

Turbopack 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 your application.

Logging

Inside of Next.js one can enable tracing with the NEXT_TURBOPACK_TRACING environment variable.

It supports the following special preset values:

  • 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 syntax supported by tracing_subscriber::filter::EnvFilter can be used.

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 Setup for more information how to create one.

With this environment variable, Next.js will write a .next/trace.log file with the tracing information in a binary format.

Viewer

To visualize the content of .next/trace.log, the turbo-trace-viewer can be used.

This tool connects the a WebSocket on port 57475 on localhost to connect the the trace-server.

One can start the trace-server with the following command:

cargo run --bin turbo-trace-server --release -- /path/to/your/trace.log

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.