Trace Profiling

Copyexport async function getInstrumentationModule(
  projectDir: string,
  distDir: string
): Promise<InstrumentationModule | undefined> {
  if (cachedInstrumentationModule) {
    return cachedInstrumentationModule
  }
 
  const startTime = getInstrumentationTimestamp()
  let error: unknown
  try {
    cachedInstrumentationModule = interopDefault(
      await require(
        path.join(
          projectDir,
          distDir,
          'server',
          `${INSTRUMENTATION_HOOK_FILENAME}.js`
        )
      )
    )
    return cachedInstrumentationModule
  } catch (err: unknown) {
    if (
      isError(err) &&
      err.code !== 'ENOENT' &&
      err.code !== 'MODULE_NOT_FOUND' &&
      err.code !== 'ERR_MODULE_NOT_FOUND'
    ) {
      error = err
      throw err
    }
  } finally {
    instrumentationModuleLoadTiming ??= {
      startTime,
      endTime: getInstrumentationTimestamp(),
      error,
    }
  }
}

Copyasync function registerInstrumentation(projectDir: string, distDir: string) {
  // Ensure registerInstrumentation is not called in production build
  if (process.env.NEXT_PHASE === 'phase-production-build') {
    return
  }
  if (!instrumentationModulePromise) {
    instrumentationModulePromise = getInstrumentationModule(projectDir, distDir)
  }
  let instrumentation: InstrumentationModule | undefined
  try {
    instrumentation = await instrumentationModulePromise
  } catch (err) {
    // A load error is only exportable when a provider was already installed.
    traceInstrumentationModuleLoad()
    throw err
  }
  if (instrumentation?.register) {
    const startTime = getInstrumentationTimestamp()
    let error: unknown
    try {
      await instrumentation.register()
      extendInstrumentationAfterRegistration()
    } catch (err: any) {
      error = err
      err.message = `An error occurred while loading instrumentation hook: ${err.message}`
      throw err
    } finally {
      const endTime = getInstrumentationTimestamp()
 
      // register() commonly installs the provider, so emit both lifecycle
      // spans afterward with their original timestamps.
      traceInstrumentationModuleLoad()
      traceBackdatedInstrumentationSpan(
        InstrumentationSpan.register,
        'register instrumentation',
        { startTime, endTime, error }
      )
    }
  } else {
    traceInstrumentationModuleLoad()
  }
}

Copyapply(compiler: any) {
  this.traceTopLevelHooks(compiler)
  this.traceCompilationHooks(compiler)
  this.compiler = compiler
}
 
traceHookPair(
  spanName: string | (() => string),
  startHook: any,
  stopHook: any,
  {
    parentSpan,
    attrs,
    onStart,
    onStop,
  }: {
    parentSpan?: (...params: any[]) => Span
    attrs?: any
    onStart?: (span: Span, ...params: any[]) => void
    onStop?: (span: Span, ...params: any[]) => void
  } = {}
) {
  let span: Span | undefined
  startHook.tap(
    { name: pluginName, stage: -Infinity },
    (...params: any[]) => {
      const name = typeof spanName === 'function' ? spanName() : spanName
      const attributes = attrs ? attrs(...params) : attrs
      span = parentSpan
        ? parentSpan(...params).traceChild(name, attributes)
        : this.runWebpackSpan.traceChild(name, attributes)
 
      if (onStart) onStart(span, ...params)
    }
  )
  stopHook.tap({ name: pluginName, stage: Infinity }, (...params: any[]) => {
    // `stopHook` may be triggered when `startHook` has not in cases
    // where `stopHook` is used as the terminating event for more
    // than one pair of hooks.
    if (!span) {
      return
    }
 
    if (onStop) onStop(span, ...params)
    span.stop()
  })
}

CopymoduleHooks.loader.tap(
  pluginName,
  (loaderContext: any, module: any) => {
    const moduleSpan = moduleSpansByCompilation
      .get(compilation)
      ?.get(module)
    loaderContext.currentTraceSpan = moduleSpan
  }
)
 
compilation.hooks.succeedModule.tap(pluginName, (module: any) => {
  moduleSpansByCompilation?.get(compilation)?.get(module)?.stop()
})

CopymoduleHooks.loader.tap(
  pluginName,
  (loaderContext: any, module: any) => {
    const moduleSpan = moduleSpansByCompilation
      .get(compilation)
      ?.get(module)
    loaderContext.currentTraceSpan = moduleSpan
  }
)

Copyconst TRACE_LABELS_SEAL = [
  'module assets',
  'create chunk assets',
  'asset render',
  'asset emit',
  'store asset',
]

Copyexport async function startTurboTraceServerCli(
  file: string,
  port: number | undefined,
  mcpPort: number | undefined
) {
  process.title = `next internal trace (v${process.env.__NEXT_VERSION})`
  const wsPort = port ?? DEFAULT_WS_PORT
  const httpPort = mcpPort ?? wsPort + 1
 
  let bindings
  try {
    bindings = await loadBindings()
  } catch {
    console.error(
      'Error: Could not load native bindings. The trace server requires native (non-WASM) bindings.'
    )
    process.exit(1)
  }
 
  let handle
  try {
    // Start the WebSocket trace server on a background thread (non-blocking).
    handle = bindings.turbo.startTurbopackTraceServerHandle(file, wsPort)
  } catch (err) {
    console.error(
      `Error: Could not start trace server for "${file}": ${err instanceof Error ? err.message : err}`
    )
    process.exit(1)
  }
 
  console.log(
    `Turbopack trace server started. View trace at https://trace.nextjs.org?port=${wsPort}`
  )
 
  // Create the MCP server.
  const mcpServer = new McpServer({
    name: 'Next.js Trace Server MCP',
    version: '0.1.0',
  })
 
  mcpServer.registerTool(
    'query_spans',
    {
      description: [
        'Query spans from a turbopack trace file: timing, CPU, attributes, allocation counters, and TurboMalloc live-memory samples.',
        '',
        'Navigation: pass a result `id` as `parent` to drill in. `search` is recursive over the whole subtree and returns full path IDs, so you can find a span without knowing where it lives. `depth` > 1 returns that many levels nested inline; `pageSize` (default 20, max 500) widens a page.',
        '',
        'Every response is paged: `totalCount` is how many matched in all, `totalPages` how many pages that is. Getting exactly `pageSize` results does not mean there are no more — check `totalCount`. Search cost scales with subtree size, so prefer scoping `parent` (or lowering `maxDepth`) over repeated root searches on a large trace.',
        '',
        'Allocations: `allocations` / `deallocations` / `allocationCount` and `persistentAllocations`, each with a `self*` counterpart excluding children. Comparing a total to its `self` shows whether a span allocates directly or only through descendants.',
        '',
        '`persistentAllocations` ranks allocators; it is NOT retained memory. It is allocated-minus-freed per TurboMalloc counters, which never see turbo-tasks cell or cache drops, so a total far above real peak RSS is expected rather than a leak. For absolute memory use `memorySummary` (count/start/end/min/peak/maxPressure, precomputed from `memorySamples`).',
        '',
        "But live heap is process-wide: a span's samples are just the global series sliced to its time range, so concurrent spans report identical memory however much each allocated. Rank concurrent work by the allocation fields, never by memory.",
        '',
        "Frees are charged to whichever span was on the stack at free time, not the one that allocated. A child with large `selfAllocations` under a parent with large `selfDeallocations` means the parent drops the child's arena — bounded, not leaking. Large `selfPersistentAllocations` with no such counterpart above it is the shape worth suspecting.",
        '',
        'For aggregated groups every allocation field is a group total, while `cpuDuration`, `correctedDuration` and `memorySamples` describe the example span only. `firstSpanId` is first in execution order; use `heaviestSpanId` to reach the member holding the most bytes.',
        '',
        'Set `outputType: "json"` for full precision and the raw `memorySamples` entries `[tsOffsetTicks, bytes, pressure, active_worker_threads]` (active_worker_threads excludes parked and blocking-pool threads); markdown is a human summary.',
      ].join('\n'),
      inputSchema: {
        parent: z
          .string()
          .optional()
          .describe(
            'Span ID to enumerate children of. Omit for root-level spans. Use the `id` field from a previous result.'
          ),
        aggregated: z
          .boolean()
          .optional()
          .describe(
            'When true (default), aggregate spans with the same name into a single entry. Set to false to see individual raw spans.'
          ),
        sort: z
          .enum(['value', 'name', 'allocations', 'persistent-allocations'])
          .optional()
          .describe(
            'Sort mode: "value" for corrected duration descending, "name" for alphabetical, "allocations" for total allocated bytes descending, "persistent-allocations" for `persistentAllocations` descending. Omit for execution order.'