completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

Deep tracing with Perfetto

Record a full Chrome trace with the categories you choose, read the compositor, raster and GPU tracks in Perfetto, and answer questions with SQL.

By the end, you can
  • 01
    Choose trace categoriesStart a full Chrome trace with the categories your question needs, and say what Chrome records when you name none.
  • 02
    Read a trace in the Perfetto UIFind processes, threads and nested slices, and read a slice's details: its category, its duration and its thread time.
  • 03
    Follow a frame across threadsRead the main thread, the compositor, a raster worker, Viz and the GPU main thread around one slow tap.
  • 04
    Ask a trace questions in SQLRun PerfettoSQL in the trace processor, and use the standard library's ready-made tables.

One slow tap, seen from every thread

Asha opens the Mint tea page on her phone. She taps Add to basket. For about a quarter of a second, nothing changes. Then the header says Basket: 1. Here is the tap in three of Chrome's screenshots:

Three of Chrome's screenshots of the Mint tea page during the tap. Before the tap, the header says Basket: 0. While the main thread runs the click's code, it still says Basket: 0. Only in the last screenshot, after the task, does it say Basket: 1.Asha tapsBeforeThe Mint tea page. The header says Basket: 0. A small leaf sits next to the title.Basket: 0The main thread is busyDuringThe same page while the click's code runs. The header still says Basket: 0.Still Basket: 0The new count showsAfterThe same page once the frame with the new count is on the screen. The header says Basket: 1.Basket: 1one tap, left to right
Three of Chrome's screenshots of the tap. While the click's code runs, the page still says Basket: 0.

Ravi built the page. He already knows the first answer. In The Performance panel, he recorded taps like this one. The click showed up as one long task on the main thread. The page's own code is slow.

But the page has a small leaf next to the title. A CSS animation keeps it swaying. So Ravi has two more questions. Did the leaf freeze too? What did Chrome's other threads do while the main thread was busy? And one for later: how can he ask the same question of fifty recordings, without clicking through each one?

The answer is a deep trace. A trace is a recording of what the browser did: a long list of events, each with a start time and a length. A deep trace records the whole browser, every process and every thread, with the parts you choose. Perfetto is the open-source tool that reads it. It has a web page to look at the trace, and a program that answers questions about it in SQL. The course traced Asha's tap, and asked Perfetto three questions:

Three answers from one tracePop out in the code editor (opens in a new tab)JavaScript
// Three answers from one trace of Asha's tap, in milliseconds (ms).const trace = { mainThreadBusy: 201.2, compositorDraws: 11, pressToScreen: 243 }; console.log(`The main thread was busy for ${trace.mainThreadBusy} ms.`);console.log(`Meanwhile, the compositor drew ${trace.compositorDraws} frames.`);console.log(`Basket: 1 reached the screen ${trace.pressToScreen} ms after the press.`);
  • Line 1 is a comment. Every time is in milliseconds (ms), thousandths of a second.
  • Line 2 holds three numbers Perfetto found in the trace.
  • Line 4 prints The main thread was busy for 201.2 ms.
  • Line 5 prints Meanwhile, the compositor drew 11 frames.
  • Line 6 prints Basket: 1 reached the screen 243 ms after the press.

So the leaf didn't freeze. Another thread, the compositor, kept drawing new frames while the main thread ran the click. Why it matters: a long task blocks the main thread's work, like the basket text, but not everything on the screen.

Real-life analogyEvery player wears a tracker

A football coach wants to know why a goal went in. The match video shows the ball. But every player also wore a tracker. After the match, the coach lines up every tracker on the same clock. Now she sees what each player did in that second. Then she asks the same question about every match of the season.

In real life: One player's tracker
In Perfetto: One thread's track, like CrRendererMain
In real life: The team the player is in
In Perfetto: The process the thread lives in, like the renderer
In real life: One match clock for every tracker
In Perfetto: One clock for every event in the trace
In real life: Choosing what the trackers record
In Perfetto: Choosing trace categories
In real life: "Who ran most in the last minute?" for every match
In Perfetto: One SQL query, run on every trace
The main idea

A deep trace records what every thread in every process did, on one clock, from the categories you choose. Perfetto shows it as tracks, and answers questions about it in SQL. First pick the categories your question needs. Then read the tracks. Then count with SQL.

How the course recorded the tap:

  • Chrome 157.0.8103.52, headless, with a phone-sized screen.
  • Tracing started before the page loaded, through the DevTools protocol, for the whole browser.
  • The course clicked Add to basket with the mouse, waited, then stopped tracing.
  • Each list of categories was traced three times, taking turns, each time in a new browser.
  • The screenshots come from one more visit of the same tap, traced through the tab: Chrome takes screenshots only for a tab.
  • The SQL ran in Perfetto's trace processor, from the v59.1 release.

Categories decide what a trace records

Chrome's code is full of trace events. Each one has a name, like Display::DrawAndSwap. Each one also has a category: a label for the part of Chrome it comes from. Chrome lists its categories in one file. Four examples:

  • cc: the compositor, the part of Chrome that draws frames from layers.
  • viz: Viz, which puts every frame together in the GPU process.
  • gpu: the GPU process running drawing commands.
  • toplevel: every task, on every thread.

When a trace starts, you hand Chrome a list of categories. Chrome only records events whose category is on the list. Viz, for example, draws each frame inside TRACE_EVENT0("viz", "Display::DrawAndSwap"). With viz off, that event never reaches the file.

Real-life analogyMicrophones at a school concert

A school records its concert. Each microphone picks up one part of the band: the drums, the choir, the piano. Before pressing Record, you switch on the microphones you want. The one inside the piano stays off unless you ask for it by name. Every microphone you add makes the recording bigger.

In real life: One microphone, for one part of the band
In Chrome: One category, like cc or viz
In real life: Switching microphones on before you press Record
In Chrome: The list of categories in Tracing.start
In real life: The microphone inside the piano, off unless you ask for it
In Chrome: A disabled-by-default- category
In real life: A bigger recording for every microphone you add
In Chrome: A bigger trace for every category you add

Some categories are off unless you name them

Some category names start with disabled-by-default-. Chrome's own comment says this prefix also gives the category the "slow" tag. And it says "slow" and "debug" categories are off by default. Perfetto's docs explain the name: slow categories "record enough data that they can affect the interactive performance" of the program. DevTools' own timeline events are one of them: disabled-by-default-devtools.timeline. So are JavaScript samples.

Three lists for the same tap

What does DevTools' Performance panel ask for? Its code at Chrome 157 has a default list. With the panel's default settings, it adds JavaScript samples and screenshots. Both are on by default: samples stay on until you disable them, and so do screenshots. That's 21 names. None of them is cc, viz or gpu.

What if you give no list at all? Chrome's code has a rule for that: if no categories are named, it turns on "the default ones". That means *, everything. But in Perfetto's settings, * means "all non-slow/debug categories". Nothing that starts with disabled-by-default- gets in.

The course traced the same tap three ways. The third list is the lesson's own: DevTools' names, plus toplevel, cc, viz and gpu. Here is how a script starts that trace:

Starting a full trace with chosen categoriesJavaScript
const cdp = await browser.newBrowserCDPSession();await cdp.send("Tracing.start", {  transferMode: "ReturnAsStream",  streamFormat: "proto",  traceConfig: {    includedCategories: [...devtoolsCategories, "toplevel", "cc", "viz", "gpu"],  },});

To stop, the script calls Tracing.end. Chrome answers with a tracingComplete event and a handle to the stream. The course read it piece by piece and saved it as a file. Inside Chrome, the list becomes Perfetto's own settings: first every category off, then each one you named turned on. A script can also pass Perfetto's settings directly, as perfettoConfig.

You don't need a script. Perfetto's UI has a Record new trace page that records Chrome, with the Perfetto UI extension installed. Chrome's own chrome://tracing page is one of its internal debugging pages. In Chrome 157 it says "Internal debugging pages are currently disabled." until you turn them on at chrome://chrome-urls.

One event, several categories

Some events carry a group of categories. The compositor's commit, for example, is in cc,benchmark. Perfetto's tracing code records a group if any one of its categories is on. Here is that rule as a small model:

When a group of categories is recordedPop out in the code editor (opens in a new tab)JavaScript
// A small model of Chrome's rule, written for this lesson.function kept(eventCategories, on) {  return eventCategories.split(",").some((category) => on.includes(category));} const on = ["devtools.timeline", "cc"];console.log(kept("cc,benchmark", on));console.log(kept("viz", on));console.log(kept("cc,disabled-by-default-devtools.timeline", on));
  • Lines 2 to 4 are the model. Line 3 splits the group at the commas, and checks whether any part is on.
  • Line 6 turns on two categories: devtools.timeline and cc.
  • Line 7 prints true: the commit's group holds cc.
  • Line 8 prints false: viz is off.
  • Line 9 prints true. The raster task's group holds a category that's off, but also cc.

Here are the sizes of the three traces of the same tap:

The same tap, three listsPop out in the code editor (opens in a new tab)JavaScript
// The same tap, traced with three lists of categories. Sizes in bytes.const sizes = { devtools: 2639134, none: 4524972, deep: 5007961 };const mb = (bytes) => (bytes / 1e6).toFixed(1); console.log(`DevTools' list: ${mb(sizes.devtools)} MB`);console.log(`No list: ${mb(sizes.none)} MB`);console.log(`The lesson's list: ${mb(sizes.deep)} MB`);
  • Line 2 holds each trace's size in bytes, from the trace with the middle size of three.
  • Line 3 turns bytes into megabytes (MB), millions of bytes.
  • Lines 5 to 7 print DevTools' list: 2.6 MB, No list: 4.5 MB and The lesson's list: 5.0 MB.
The same tap, traced three times with three lists of categories. DevTools' list: 2.6 MB, with JavaScript samples, no compositor steps. No list: 4.5 MB, with compositor steps, no JavaScript samples. The lesson's list: 5.0 MB, with JavaScript samples and compositor steps.DevTools' list2.6 MBJavaScript samples, no compositor stepsNo list4.5 MBcompositor steps, no JavaScript samplesThe lesson's list5.0 MBJavaScript samples and compositor steps
The same tap, traced with three lists. Each bar is the trace's size, to scale. Only the lesson's list holds both kinds of event.

No list made the trace far bigger than DevTools' list, and it still left things out. It held no JavaScript samples at all. DevTools' list had 39,779 of them, but none of the compositor's, Viz's or the GPU's steps. Only the lesson's list has both. Pick a list to see what each trace holds:

Playground: one tap, three lists of categories
DevTools' list21 names
Size of each trace
2.7 MB, 2.6 MB, 2.6 MB
Slices
10,139
Categories
38
Categories that are off unless named
6
JavaScript samples
39,779
Rows in chrome_event_latencies
0
ThreadStepTimes
CrRendererMainRunTask406
CrRendererMainProxyMain::BeginMainFrame0
CompositorScheduler::BeginImplFrame0
CompositorAnimationHost::TickAnimations0
CompositorProxyImpl::ScheduledActionDraw0
ThreadPoolForegroundWorkerRasterTask5
VizCompositorThreadDisplay::DrawAndSwap0
CrGpuMainRasterDecoderImpl::DoRasterCHROMIUM0
CrGpuMainSkiaOutputSurfaceImplOnGpu::SwapBuffers0
Try it yourself
DevTools' list: 2.6 MB

7 of the 9 steps are missing: only the main thread's tasks and the raster tasks made it in.

Real traces of the same tap in Chrome, on a phone-sized screen. Each list was traced three times, taking turns; the numbers are from the trace with the middle size.

Why it matters: choose categories for your question. To see the compositor and the GPU, add cc, viz and gpu. Don't switch everything on: the file grows, and slow categories cost time while you record.

Reading a trace in the Perfetto UI

The Perfetto UI is a web page, at ui.perfetto.dev. It opens Perfetto's own traces and the JSON ones DevTools saves. Click Open trace file, or drag the file onto the page. Your trace stays on your computer. Perfetto's docs say the UI "runs fully locally, in-browser", and the file isn't uploaded unless you click Share.

The course opened the lesson's trace there, and clicked the click's long task:

Two screenshots of the Perfetto UI with the lesson's trace. Top: the Renderer process's group, titled with the page's name, and its CrRendererMain track. The click's RunTask is selected; under it sit six more slices, down to FunctionCall. Bottom: the Details panel for the RunTask: its category, disabled-by-default-devtools.timeline, its start time, a duration of 201.2 ms, a thread duration of 200.3 ms, its thread and its process.ui.perfetto.devThe Perfetto UI's timeline: the Renderer group and the CrRendererMain track, with the selected RunTask and the slices nested under it.The Details panel: name RunTask, its category, start time, duration, thread duration, thread, process and SQL ID.A group per processRenderer, with the page's titleA track per threadCrRendererMain and its thread idSlices inside slicesoutside in, top to bottomClick a sliceits details open in a panel
The lesson's trace in the Perfetto UI. The click's task is selected on CrRendererMain, and the Details panel says what it is.
Real-life analogyA conductor's score

A conductor reads a score. Each instrument has its own line, and the lines are grouped by section: strings, brass, drums. A long note is drawn long. Reading straight down one bar shows what every instrument plays at that moment.

In real life: A section of the orchestra, like the strings
In Perfetto: A process, like Renderer
In real life: One line for each instrument
In Perfetto: One track for each thread
In real life: A long note, drawn long
In Perfetto: A long slice, drawn wide
In real life: Reading straight down one bar
In Perfetto: Seeing what every thread did at one moment

Here is what the picture shows:

  • Each process is a group. Its name ends with its process id. The renderer's group also shows the page's title, Mint tea | Leaf and Kettle.
  • Each thread gets a track: a row of its own. Its name ends with the thread's id, like CrRendererMain 4418718.
  • Each slice is one piece of work, as wide as it lasted. A slice that runs inside another sits one row below it.

To move around, Perfetto uses the keyboard:

The Details panel says what the selected task is. Its category is disabled-by-default-devtools.timeline. Its duration is 201.2 ms. Its thread duration is 200.3 ms: the time the thread was really running on the processor, not waiting. Chrome asks for it in the settings it builds from your list. Here the two are almost equal. The task spent its whole time working.

Now open the task the way the UI does. Each slice below is real, from the trace. Click one to see what the Details panel would list for it:

Playground: click a slice
Detailsslice 1 of 7
Name
RunTask
Category
disabled-by-default-devtools.timeline
Start
0.0 ms after the task began
Duration
201.2 ms
Depth
0
Thread
CrRendererMain [4418718]
Process
Renderer [54583]
Try it yourself
Depth 0: RunTask

The outermost slice: the whole task. Every slice below it sits inside it.

The click's task from the lesson's trace, from the outside in, as the Perfetto UI nests it. Times are in ms after the task began.

Read the slices from the outside in. The task handled an input event, dispatched it to the page, and called a JavaScript function. The innermost slice, FunctionCall, lasted 200.2 ms. That's the page's own click handler. Why it matters: the deepest wide slice is usually the code to fix.

Compositor, raster, and GPU tracks

In Inside the rendering engine, you followed one frame from a script to the screen. Five threads carry it. Processes and threads introduced them. Here they are, with the names Chrome gives them. Read each row across:

Five threads in the lesson's trace
ThreadProcessWhat it doesIts steps in the trace
CrRendererMainThe page's renderer.Runs the page's JavaScript, then style, layout and paint for each new frame.RunTask for each task, and ProxyMain::BeginMainFrame for a frame.
CompositorThe page's renderer.Begins each frame, moves compositor animations, and draws.Scheduler::BeginImplFrame, AnimationHost::TickAnimations and ProxyImpl::ScheduledActionDraw.
ThreadPoolForegroundWorkerThe page's renderer.Turns tiles, small squares of the page, into GPU commands.RasterTask.
VizCompositorThreadThe GPU process.Puts the frames of every surface together, and draws the result.Display::DrawAndSwap.
CrGpuMainThe GPU process.Runs the GPU commands, then swaps the finished frame onto the screen.RasterDecoderImpl::DoRasterCHROMIUM and SkiaOutputSurfaceImplOnGpu::SwapBuffers.

Chrome names each thread in its own code:

The raster worker is the surprise. In this trace, the renderer's raster tasks ran on threads called ThreadPoolForegroundWorker. Chrome's raster pool is a CategorizedWorkerPoolJob. It hands its work to Chrome's shared pool of threads, as jobs with the highest priority, user-blocking. You'll also see CompositorTileWorker1. That thread belongs to the browser process: it rasters Chrome's own window, not the page.

Here are the five tracks around the tap, to scale:

Five threads around the tap, to scale, from -10 to 260 ms after the click's task began. The renderer's main thread, CrRendererMain, runs the click's task for 201.2 ms, then a 34.9 ms task for the next frame. Meanwhile the renderer's Compositor thread draws 11 frames, about one every 17 ms, and Viz and CrGpuMain in the GPU process draw and swap each one. After the main thread's frame, a raster worker and the GPU raster the new basket text, and the frame with Basket: 1 is on the screen at 242.4 ms.RendererGPU processCrRendererMainCompositorraster workerVizCompositorThreadCrGpuMainthe click, 201.2 msnext frame0 ms50 ms100 ms150 ms200 ms250 msBasket: 1 on screen at 242.4 ms
The tap on five threads, to scale. While the main thread ran the click, the compositor drew 11 frames without it. Each thin mark is one draw or swap.
Real-life analogyThe puppet keeps dancing

At a puppet show, the writer goes backstage to write a new scene. The show doesn't stop. The puppeteer keeps moving the puppet that's already on stage. Only when the writer hands over the new scene do the painters make the scenery, and the stage crew show it.

In real life: The writer, busy with a new scene
In Chrome: CrRendererMain, running the click
In real life: The puppeteer, moving the puppet already on stage
In Chrome: The Compositor thread, moving the leaf
In real life: The painters of new scenery
In Chrome: The raster workers
In real life: The stage crew who show each scene to the audience
In Chrome: Viz and CrGpuMain in the GPU process

Read the picture from top to bottom:

  1. During the click. The main thread ran the click for 201.2 ms. Meanwhile, the Compositor thread drew 11 frames, about one every 17 ms. For each one, Viz drew the frame and CrGpuMain swapped it onto the screen. The leaf's animation runs on the compositor, as Compositor-friendly animation showed. So it never waited.
  2. The next frame. Then the main thread started the next frame. That task lasted 34.9 ms, but its thread duration was only 3.3 ms: it was waiting most of that time. At its end, it ran style, paint and the commit: the hand-over of the new frame to the compositor.
  3. To the screen. The compositor took the commit at 236.0 ms. A raster worker turned the new text into GPU commands at 236.1 ms, in 0.2 ms. CrGpuMain ran them at 236.6 ms. It swapped the frame with Basket: 1 onto the screen at 242.3 ms.

All times are in ms after the click's task began. Why it matters: a long task holds back every change the main thread makes, like the basket text. Animations on the compositor keep going. So split long tasks, as Breaking up long work shows, and animate with transform and opacity.

Asking a trace questions in SQL

Clicking answers one question about one trace. To ask many traces the same question, you write it in SQL, a language for asking tables questions. In More lab tools, you ran a first query. This section goes further.

The program is the trace processor. Perfetto ships it as trace_processor_shell, in each release on GitHub. The course used the v59.1 release:

Running one query on the lesson's traceShell
./trace_processor_shell query mint-tea-tap.pftrace.gz "SELECT COUNT(*) FROM slice"

Line 1 runs the query command on the lesson's trace file, then prints the rows. The file can stay gzipped. The trace processor reads the trace into tables:

  • slice: every slice, with its start ts, its length dur, its name, its category and its depth.
  • thread and process: every thread and process, with their names.
  • thread_track: which track belongs to which thread.

Times are in nanoseconds, billionths of a second. Dividing by 1e6, a million, gives milliseconds.

The language is PerfettoSQL. Any SQL that SQLite accepts works in it, plus a few additions with the word PERFETTO. INCLUDE PERFETTO MODULE brings in a module from Perfetto's standard library: tables and views someone already wrote. slices.with_context adds thread_slice: every slice, with its thread's and process's names on it. That saves joining four tables by hand.

Real-life analogyAsking the sports day results sheet

After sports day, every race is one row on a results sheet: the lane, the runner, the time. You don't watch the races again to answer "who was slowest?" or "how many races were run in lane 3?". You sort the sheet, or count its rows.

In real life: One row for every race
In SQL: One row for every slice
In real life: The runner's lane
In SQL: The thread, thread_name
In real life: The finishing time
In SQL: The length, dur
In real life: "Who was fastest?"
In SQL: ORDER BY dur, LIMIT 1
In real life: "How many races in lane 3?"
In SQL: COUNT(*) with WHERE thread_name = ...

The longest task

The longest main-thread taskSQL
INCLUDE PERFETTO MODULE slices.with_context;SELECT name, ROUND(dur / 1e6, 1) AS msFROM thread_sliceWHERE thread_name = 'CrRendererMain' AND name = 'RunTask'ORDER BY dur DESCLIMIT 1;
  • Line 1 brings in thread_slice.
  • Line 2 picks each slice's name, and its length in ms, rounded to 0.1.
  • Line 4 keeps the main thread's tasks.
  • Lines 5 and 6 sort the longest first, and keep one row.
What the longest-task query gaveText
name     ms
RunTask  201.2

One row: the click's task, 201.2 ms. The same as the Details panel showed.

Frames drawn during that task

Frames drawn while the main thread was busySQL
INCLUDE PERFETTO MODULE slices.with_context;WITH task AS (  SELECT ts, ts + dur AS done FROM thread_slice  WHERE thread_name = 'CrRendererMain' AND name = 'RunTask'  ORDER BY dur DESC LIMIT 1)SELECT thread_name, name, COUNT(*) AS timesFROM thread_slice, taskWHERE thread_slice.ts BETWEEN task.ts AND task.done  AND name IN ('ProxyImpl::ScheduledActionDraw', 'Display::DrawAndSwap',               'SkiaOutputSurfaceImplOnGpu::SwapBuffers')GROUP BY thread_name, nameORDER BY times;
  • Lines 2 to 6 find the longest task again, and name its start and its end task.
  • Line 7 picks the thread, the slice's name, and how many times it appears.
  • Line 9 keeps slices that started while the task ran.
  • Lines 10 and 11 keep three steps: the compositor's draw, Viz's draw, and the GPU's swap.
  • Line 12 counts them for each thread and name.
What the frames query gaveText
thread_name          name                                     times
Compositor           ProxyImpl::ScheduledActionDraw           11
CrGpuMain            SkiaOutputSurfaceImplOnGpu::SwapBuffers  11
VizCompositorThread  Display::DrawAndSwap                     11

Three threads, 11 each. That's where the overview's 11 frames came from: the compositor drew them, Viz put them together, and CrGpuMain swapped them onto the screen.

The compositor's steps, in order

To list a thread's slices in time order, sort by their start:

The compositor's steps after the task beganSQL
INCLUDE PERFETTO MODULE slices.with_context;WITH task AS (  SELECT ts FROM thread_slice  WHERE thread_name = 'CrRendererMain' AND name = 'RunTask'  ORDER BY dur DESC LIMIT 1)SELECT ROUND((thread_slice.ts - task.ts) / 1e6, 1) AS at_ms, nameFROM thread_slice, taskWHERE thread_name = 'Compositor' AND thread_slice.ts >= task.ts  AND name IN ('Scheduler::BeginImplFrame', 'AnimationHost::TickAnimations',               'ProxyImpl::ScheduledActionDraw')ORDER BY thread_slice.tsLIMIT 6;
  • Line 7 turns each start into ms after the task began.
  • Line 9 keeps the Compositor thread, from the task's start on.
  • Lines 10 and 11 keep its three frame steps.
  • Lines 12 and 13 sort them by start time, and keep the first six.
What the steps query gaveText
at_ms  name
8.9    Scheduler::BeginImplFrame
9.0    AnimationHost::TickAnimations
24.6   ProxyImpl::ScheduledActionDraw
27.0   Scheduler::BeginImplFrame
27.0   AnimationHost::TickAnimations
43.0   ProxyImpl::ScheduledActionDraw

Two frames, three steps each. The compositor began a frame, moved the leaf at once, and drew the frame before the next one began.

A table from the standard library

The standard library also has modules for Chrome. chrome.event_latency builds chrome_event_latencies from Chrome's EventLatency events. Chrome starts one when an input is made, and ends it when the frame that shows its result is presented:

From input to the screenSQL
INCLUDE PERFETTO MODULE chrome.event_latency;SELECT event_type, ROUND(dur / 1e6, 1) AS ms, is_presentedFROM chrome_event_latenciesORDER BY ts;
  • Line 1 brings in the module.
  • Line 2 picks each input's type, its length in ms, and whether its frame reached the screen.
  • Lines 3 and 4 read the table, in time order.
What the latency query gaveText
event_type         ms     is_presented
MOUSE_MOVED_EVENT  0.7    0
MOUSE_PRESSED      243.0  1
MOUSE_RELEASED     242.9  1

The mouse moved onto the button: 0.7 ms, and no frame showed it. The press took 243.0 ms to reach the screen, and is_presented is 1. That's the overview's third number.

On the trace made with DevTools' list, the same query gave no rows. Chrome writes EventLatency in the group cc, benchmark, input and input.scrolling, and that list has none of them. A module is like a tested recipe: it only works if your trace has its ingredients. Try each question on both traces:

Playground: asking the trace in SQL
The query, and the rows it gavePerfettoSQL
INCLUDE PERFETTO MODULE slices.with_context;
SELECT name, ROUND(dur / 1e6, 1) AS ms
FROM thread_slice
WHERE thread_name = 'CrRendererMain' AND name = 'RunTask'
ORDER BY dur DESC
LIMIT 1;

On the lesson's trace

namems
RunTask201.2

On the trace made with DevTools' list

namems
RunTask201.7
Try it yourself
The longest main-thread task

On the lesson's trace: 1 row. On the trace made with DevTools' list: 1 row.

The SQL ran in Perfetto's trace processor, on two real traces of the same tap. The rows are what it printed.

Why it matters: write a question once, then run it on every trace you record. The same SQL works on a hundred traces as well as on one.

Which track answers it?

Each question below is about Asha's tap. Sort it by the track you would read to answer it:

Which track answers it?
  • How long the click handler ran
  • How long style and layout took after the click
  • Whether the leaf's animation moved while JavaScript ran
  • When the page's compositor drew a frame without the main thread
  • When the new basket text became GPU commands, tile by tile
  • When every surface's frame was put together into one picture
  • When the GPU ran the raster commands
  • When the frame with Basket: 1 was swapped onto the screen
Try it yourself
0 of 8 correct

Sort each question by the thread whose track answers it.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

Common mix-ups

  • "The Performance panel records everything." No. It asks for 21 categories. cc, viz and gpu aren't among them.
  • "Giving no list records everything." No. It records every category that isn't slow or debug. JavaScript samples and DevTools' timeline events stay out.
  • "More categories are always better." No. The trace grows, and slow categories cost time while you record. Add the ones your question needs.
  • "When the main thread is busy, nothing on the page moves." No. The compositor drew 11 frames during the click's task. Only changes that need the main thread wait.
  • "Raster always runs on CompositorTileWorker threads." No. In this trace, the page's tiles were rastered on ThreadPoolForegroundWorker threads. CompositorTileWorker1 belongs to the browser process.
  • "An empty result means nothing happened." No. The trace may lack the categories the table is built from, as chrome_event_latencies did with DevTools' list.
  • "Opening a trace in ui.perfetto.dev uploads it." No. The UI runs in your browser, and the file stays there unless you click Share.

Practice exercises

Answer first, then use the hints.

Exercise 1 · Warm-upOne more group of categories

The lesson's four extra categories are on. What does this program print?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// A small model of Chrome's rule, written for this lesson.
function kept(eventCategories, on) {
  return eventCategories.split(",").some((category) => on.includes(category));
}

const on = ["devtools.timeline", "toplevel", "cc", "viz", "gpu"];
console.log(kept("input,benchmark,latencyInfo", on));

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upNanoseconds to milliseconds

    Perfetto stored this dur. What does the program print?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // Perfetto keeps every time in nanoseconds (ns).
    const dur = 16667000;
    console.log((dur / 1e6).toFixed(1));

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeCategories with no list

      In the trace made with no list, how many different categories did the slices carry?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeThe browser's own raster tasks

        On the lesson's trace, how many raster tasks ran on the browser process's CompositorTileWorker1?

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeOne slice's category

          Download the lesson's trace and open it in the Perfetto UI. Which category does the EventDispatch slice inside the click's task have?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeHow busy was the compositor?

            Write a query that adds up how long every Compositor thread spent in its RunTask slices, in ms. Run it on the lesson's trace, in the trace processor or in the Perfetto UI's query page. What does it give?

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask which category records it, and which thread's track shows it.

              The deep tracing quiz · 7 questionsScore: first tries count
              1. Question 1 of 7Which category must a trace include for Viz's Display::DrawAndSwap to be recorded?

                Choose an answer to see the explanation.

              2. Question 2 of 7What does the prefix disabled-by-default- on a category mean?

                Choose an answer to see the explanation.

              3. Question 3 of 7What does the category model print last?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // A small model of Chrome's rule, written for this lesson.
                function kept(eventCategories, on) {
                  return eventCategories.split(",").some((category) => on.includes(category));
                }
                
                const on = ["devtools.timeline", "cc"];
                console.log(kept("cc,benchmark", on));
                console.log(kept("viz", on));
                console.log(kept("cc,disabled-by-default-devtools.timeline", on));

                Choose an answer to see the explanation.

              4. Question 4 of 7While the main thread ran the click's long task, which thread kept drawing the leaf's frames?

                Choose an answer to see the explanation.

              5. Question 5 of 7In Perfetto's tables, what unit are ts and dur in?

                Choose an answer to see the explanation.

              6. Question 6 of 7What does INCLUDE PERFETTO MODULE slices.with_context; give your query?

                Choose an answer to see the explanation.

              7. Question 7 of 7chrome_event_latencies came back empty on the trace made with DevTools' list, though the course clicked. Why?

                Choose an answer to see the explanation.

              Key takeaways

              • A trace only holds the categories you turn on. Chrome records an event if any one of its categories is on.
              • DevTools' list has no cc, viz or gpu. No list at all leaves out every disabled-by-default category.
              • Start a full trace with Tracing.start on the browser's session, in the proto format, with your own list.
              • In the Perfetto UI, a process is a group, a thread is a track, and nested slices stack below each other.
              • Thread duration is the time a slice really ran. Much less than its duration means it was waiting.
              • The compositor, Viz and CrGpuMain keep drawing while the main thread is busy. Changes from the main thread wait.
              • The trace processor turns a trace into tables. The standard library adds ready-made ones, if the trace has their categories.

              Remember the one-liner.
              Choose the categories, read every thread on one clock, then ask the trace in SQL.

              Sources

              The facts on this page come from these docs and source files. Each source tree is pinned to the version the course used:

              Coming next: Congestion control, the first lesson on network internals. You've traced every thread inside the browser. Next, see why the same page loads at different speeds on the same network.

              CompleteFrontend Clear concepts. Working examples.