blob: c90b0342d2a47a81130259c6fafdca1edf8d97cc [file] [log] [blame] [view]
# 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`](sql-tables.autogen#slice) table) or counter format
(ex: the [`counter`](sql-tables.autogen#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.
1. A non-null timestamp (the timestamp, in nanoseconds, at the start of the
slice) column.
1. (For `slice` tracks) a duration (the duration, in nanoseconds, of the slice)
column.
1. (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).
![Query for debug slice track](/docs/images/debug-tracks/slice-track-query.png)
1. 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.
![Create a new debug slice track](/docs/images/debug-tracks/slice-track-create.png)
1. 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.
![Resultant debug track](/docs/images/debug-tracks/slice-track-result.png)
1. (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.
![Creating pivoted debug slice tracks](/docs/images/debug-tracks/pivot-slice-tracks-create.png)
This will result in a debug slice track created for each distinct pivot
value.
![Resultant pivoted debug slice tracks](/docs/images/debug-tracks/pivot-slice-tracks-results.png)
## 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).
![Query for debug counter track](/docs/images/debug-tracks/counter-tracks-query.png)
1. 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.
![Create a new debug counter track](/docs/images/debug-tracks/counter-tracks-create.png)
1. The counter track will appear as a pinned track near the top of the Timeline view.
![Resultant pivoted debug counter track](/docs/images/debug-tracks/counter-tracks-results.png)
1. (Optional) Pivoted `counter` tracks are created by selecting a value from the
"pivot" column.
![Create a new debug counter track](/docs/images/debug-tracks/pivot-counter-tracks-create.png)
This will result in a debug counter track created for each distinct pivot
value.
![Resultant pivoted debug counter track](/docs/images/debug-tracks/pivot-counter-tracks-results.png)