Debug Tracks

Debug Tracks are a way to display tabular results from running a PerfettoSQL query as a so-called "debug" track. Specifically, if the resultant table can be visualised in a slice format (ex: the slice table) or counter format (ex: the counter table), a debug track can be created from it.

For a result table to be visualised, it should include:

1. A name (the name of the slice) column.

2. A non-null timestamp (the timestamp, in nanoseconds, at the start of the slice) column.

3. (For slice tracks) a duration (the duration, in nanoseconds, of the slice) column.

4. (Optionally) the name of a column to pivot

   Note: Pivoting means allows you to create a single debug track per distinct value in the selected "pivot" column.

Creating Debug slice Tracks

To create slice tracks:

1. Run a SQL query, and ensure its results are slice-like (as described above).

2. Navigate to the "Show Timeline" view, and click on "Show debug track" to set up a new debug track. Select "slice" from the Track type dropdown.

   Note that the names of the columns in the result table do not necessarily have to be name, ts, or dur. Columns which semantically match but have a different name can be selected from the drop-down selectors.

   

3. The debug slice track is visible as a pinned track near the top of the Timeline view with slices from the table from which the track was created (note that slices with no/zero duration will be displayed as instant events). Debug tracks may be manually unpinned and will appear on the top of other unpinned tracks.

4. (Optional) Pivoted slice tracks are created by selecting a value from the "pivot" column.

   Note: You can enter queries into the search box directly by typing : to enter SQL mode.

   

   This will result in a debug slice track created for each distinct pivot value.

   

Creating Debug counter Tracks

You can create new debug counter tracks by following similar steps to the ones mentioned above:

1. Run a SQL query, and ensure its results are counter-like (as described above).

   

2. Navigate to the Timeline view, and click on "Show debug track" to set up a new debug track. Select "counter" from the Track type dropdown and the semantically matching column names of interest.

   

3. The counter track will appear as a pinned track near the top of the Timeline view.

   

4. (Optional) Pivoted counter tracks are created by selecting a value from the "pivot" column.

   

   This will result in a debug counter track created for each distinct pivot value.