Turbopack: Add --internal-trace cli flag (#92190)

## What?

Adds `--internal-trace` to both `dev` and `build` that enables
`NEXT_TURBOPACK_TRACING=turbo-tasks`.

Optionally supports `minimal` and `all` (all is the default).

When `minimal` is provided it passes `NEXT_TURBOPACK_TRACING=1` and the
trace file won't include turbo-tasks spans.

Author: timneutkens

packages/next/src/bin/next.ts

@@ -208,6 +208,14 @@ program
     '--experimental-cpu-prof',
     'Enable CPU profiling. Profile is saved to .next-profiles/ on exit.'
   )
+  .addOption(
+    new Option(
+      '--internal-trace [level]',
+      'Enable Turbopack tracing. "all" (default) enables turbo-tasks level tracing, "overview" enables overview tracing.'
+    )
+      .choices(['all', 'overview'])
+      .preset('all')
+  )
   .action((directory: string, options: NextBuildOptions) => {
     if (options.debugPrerender) {
       // @ts-expect-error not readonly
@@ -225,6 +233,12 @@ program
       mkdirSync(cpuProfileDir, { recursive: true })
       process.env.NEXT_CPU_PROF_DIR = cpuProfileDir
     }
+    if (options.internalTrace) {
+      process.env.NEXT_TURBOPACK_TRACING =
+        options.internalTrace === 'all'
+          ? 'turbo-tasks'
+          : String(options.internalTrace)
+    }
 
     // ensure process exits after build completes so open handles/connections
     // don't cause process to hang
@@ -350,6 +364,14 @@ program
     '--experimental-cpu-prof',
     'Enable CPU profiling. Profiles are saved to .next-profiles/ on exit.'
   )
+  .addOption(
+    new Option(
+      '--internal-trace [level]',
+      'Enable Turbopack tracing. "all" (default) enables turbo-tasks level tracing, "overview" enables overview tracing.'
+    )
+      .choices(['all', 'overview'])
+      .preset('all')
+  )
   .action(
     (directory: string, options: NextDevOptions, { _optionValueSources }) => {
       if (options.experimentalNextConfigStripTypes) {
@@ -364,6 +386,12 @@ program
         mkdirSync(cpuProfileDir, { recursive: true })
         process.env.NEXT_CPU_PROF_DIR = cpuProfileDir
       }
+      if (options.internalTrace) {
+        process.env.NEXT_TURBOPACK_TRACING =
+          options.internalTrace === 'all'
+            ? 'turbo-tasks'
+            : String(options.internalTrace)
+      }
       const portSource = _optionValueSources.port
       import('../cli/next-dev.js').then((mod) =>
         mod.nextDev(options, portSource, directory)

packages/next/src/cli/next-build.ts

@@ -33,6 +33,7 @@ export type NextBuildOptions = {
   experimentalNextConfigStripTypes?: boolean
   debugBuildPaths?: string
   experimentalCpuProf?: boolean
+  internalTrace?: string | boolean
 }
 
 const nextBuild = async (options: NextBuildOptions, directory?: string) => {

packages/next/src/cli/next-dev.ts

@@ -56,6 +56,7 @@ export type NextDevOptions = {
   experimentalNextConfigStripTypes?: boolean
   experimentalCpuProf?: boolean
   serverFastRefresh?: boolean
+  internalTrace?: string | boolean
 }
 
 type PortSource = 'cli' | 'default' | 'env'
@@ -348,6 +349,9 @@ const nextDev = async (
                 __NEXT_PRIVATE_CPU_PROFILE: 'dev-server',
               }
             : undefined),
+          ...(process.env.NEXT_TURBOPACK_TRACING
+            ? { NEXT_TURBOPACK_TRACING: process.env.NEXT_TURBOPACK_TRACING }
+            : undefined),
         },
       })