Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: Build a Trace Analyzer

Understand the Chrome trace file format by building a small analyzer: parse trace events, compute self time, find long tasks and top functions, and print a report.

A Performance recording can be saved as a JSON file (the download arrow in the panel). That file is not magic: it follows the Trace Event Format, a simple list of events that many tools read. In this project you build a small analyzer that reads such a file and prints the same kinds of answers the Performance panel gives you: total time per category, the longest tasks and the functions with the highest self time.

Building the tool teaches you what the panel does behind the scenes, and gives you something useful: a script you can run in a build pipeline on saved traces.

The sample below is a small hand-made trace, shaped like real traces but with invented names and numbers. Real traces contain hundreds of thousands of events and many more fields; the approach is the same.

The trace event format

A trace file is either a JSON array of events or an object with a traceEvents array. The fields you need:

Field Meaning
name Event name, such as RunTask, FunctionCall, Layout, Paint
cat Category string, such as devtools.timeline
ph Phase: X is a complete event with a duration, B and E begin and end, I instant, M metadata
ts Timestamp in microseconds
dur Duration in microseconds (for X events)
pid, tid Process and thread identifiers
args Extra data, e.g. args.data.functionName and args.data.url

Time units trip everyone up: the format uses microseconds, while DevTools shows milliseconds, so divide by 1000.

Step 1: parse and normalize

Start by turning events into a simple list with millisecond times and keeping only complete events on the main thread.

JS Step 1: parse the trace

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 2: find long tasks

Long tasks are RunTask events over 50 ms. Reuse the idea from the long-tasks lesson, and compute Total Blocking Time on the way.

JS Step 2: long tasks and TBT

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 3: self time per function

Self time needs the nesting: an event's children are the events fully inside it. We sort by start time (and longest first on ties), keep a stack of open events, and subtract each event's duration from its parent. The full program below assembles everything, so you can run it as one analyzer.

JS Step 3: the complete analyzer

Press Run (or Ctrl + Enter) to see the console output here.

No output.

You should find two long tasks (the 180 ms boot task and the 65 ms analytics task) and that parseConfig has the largest self time, 70 ms, even though bootApp has the biggest total. This is exactly the Bottom-Up view of the panel.

Ideas to extend it

  • Read the file from disk with Node (fs.readFileSync, JSON.parse) and run it on a real saved trace; filter to the thread named CrRendererMain using the thread_name metadata events.
  • Add the Layout Shift events (LayoutShift, with args.data.score) and compute CLS using session windows.
  • Report LCP from largestContentfulPaint::Candidate events.
  • Fail with a non-zero exit code when TBT exceeds a budget so the script can run in CI.
  • Group script time by origin to measure third-party cost.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In the Trace Event Format, in which unit is ts?

    ts and dur are microseconds; DevTools displays milliseconds.
  2. 2. What does ph: 'X' mean?

    X events carry both ts and dur.
  3. 3. How do you compute the self time of an event?

    Self time excludes time spent in nested calls.
  4. 4. How can you find the main thread's events in a real trace?

    Metadata events map thread ids to names; the main renderer thread is named CrRendererMain.

Summary

  • A saved trace is JSON with a traceEvents array; times are in microseconds.
  • Filter complete events, convert units, and rebuild nesting with a stack.
  • Self time = duration minus direct children; long tasks are RunTask events over 50 ms.
  • The same analysis powers Bottom-Up, long-task marks and TBT, and can run in CI.

Next: Practice: A DevTools Debugging Checklist