How to Debug and Analyze Next.js Trace Files with Jaeger?

[smitpatel1010]

Summary

I’m currently working with the Next.js trace file (.next/trace) generated during the build process. While this file provides valuable trace data, analyzing it in a structured tool like Jaeger would greatly enhance debugging and performance insights. However, I haven’t found any official or community-provided scripts/tools to convert the Next.js trace file into a Jaeger-compatible JSON format.

Here’s what I’m aiming for:

• A way to map the trace file's data (e.g., traceEvents) into Jaeger’s span model, including details like operation names, timestamps, durations, and parent-child relationships.
• A utility or guideline to bridge the format gap between Next.js traces and Jaeger’s trace ingestion requirements.

Questions:

1. Are there any existing tools, scripts, or practices for converting Next.js trace files to Jaeger-compatible formats?
2. Is there any documentation on the schema or structure of the Next.js trace file to help build such a conversion script?

Additional information

No response

Example

No response

[smitpatel1010]

@timneutkens I think you mentioned #66326 (comment) here that you use some different tool. can you please mention which tool do you use?
Upload the .next/trace file to https://gist.github.com/ -- Please don't run trace-to-tree yourself, as I use some other tools (e.g. Jaeger) that require the actual trace file.

[m-sanders]

I am going down this rabbit hole as we speak.

I am confused why Next.js has taken a "give a man a fish" approach here to debugging trace files rather than teaching us all to fish with some lovely documentation.

I've discovered a rust CLI tool in scripts that will send traces to Jaeger. I'm going to have a go at running Jaeger, compiling the script and attempt to ingest the trace file.

[timneutkens]

The Jaeger setup is undocumented intentionally. It's not the recommended way to interpret these. There are docs for the recommended way: https://nextjs.org/docs/app/guides/local-development#turbopack-tracing (also supports .next/trace for webpack traces)

[timneutkens]

Dev/Build tracing is now documented here: https://nextjs.org/docs/app/guides/local-development#turbopack-tracing

[m-sanders]

Thank you for the official solution!

I would still say that I've found the undocumented Jaeger approach to be easier to explore and get to the bottom of performance issues than the Turbopack tracing UI ;)