mirror of https://github.com/hanzoai/next.js.git synced 2026-09-24 17:00:51 +00:00

Files

T

Luke SandbergandGitHub a7b04690e6 gitignore .next-profiles (#95256 )

### What?

When profiling is enabled (`--experimental-cpu-prof` /
`--internal-trace`, or the `NEXT_CPU_PROF` / `NEXT_TURBOPACK_TRACING`
env vars), Next.js writes a `.gitignore` containing `*` into
`.next-profiles/` as it creates the directory. This keeps the profiling
output out of git and out of the way of tools that scan the project
tree.

### Why?

`.next-profiles` is a sibling of `.next`, so it's intentionally *not*
covered by the `.gitignore` create-next-app ships. The motivation was
that profiles wouldn't bloat `.next` and wouldn't be silently ignored.
But a sibling dir full of large profile/trace files turns out to be a
liability:

- **Ecosystem tools scan it.** Tailwind v4 aggressively auto-scans files
and has opened a `trace-turbopack.bin` and crashed; Turborepo <2.8.13
hashes the file and OOMs, and >=2.8.13 fails to start `dev` watchers
because reading the large trace is too slow. (workflow watchers are
likely affected too.)
- **Turbopack NFT globbing** can read/hash the file via overly broad
`fs.read` patterns.
- **Accidental commits.** Pushing a multi-GB trace would be miserable
for a customer helping us debug.

These have each gotten point bandaids (#94587, #94570), but the real fix
preserves the original motivation: a nested `.gitignore` with `*` keeps
the files off git **and** makes gitignore-respecting tools (Tailwind,
Turborepo) skip the whole subtree, which resolves the scanning failures.
Reverting to `.next/profiles` was the alternative; the gitignore
approach keeps the existing path.

### How?

- `ensureProfilesDir()` (`packages/next/src/lib/profiles-dir.ts`)
creates `.next-profiles` and writes the `.gitignore` (only if absent, so
user edits survive). Single source of truth.
- `bin/next.ts` calls a `setupProfilesDir()` helper on build/dev/start,
gated on the env vars so both the CLI flags and direct env-var usage are
covered. Skipped when `NEXT_TURBOPACK_TRACING_PATH` redirects trace
output.
- Rust keeps `create_dir_all` as a backstop for the trace dir; the
`.gitignore` is written in JS only.
- Docs switched from `NEXT_TURBOPACK_TRACING=1` to `next dev
--internal-trace`, and the stale `trace-turbopack` filename corrected to
`trace-turbopack.bin`.

<!-- NEXT_JS_LLM_PR -->

2026-07-01 15:51:33 +00:00

3.4 KiB

Raw Permalink Blame History

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:

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 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 on how to create one.

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

Viewer

To visualize the content of .next-profiles/trace-turbopack.bin, use the turbo-trace-viewer.

A video showing how to use the tool is available here.

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:

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

# or
pnpm next internal trace .next-profiles/trace-turbopack.bin

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 are 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.

3.4 KiB Raw Permalink Blame History

Tracing Turbopack

Logging

Viewer

3.4 KiB

Raw Permalink Blame History