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). Query for debug slice track

  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.

    Create a new debug slice track

  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. Resultant debug track

  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.

    Creating pivoted debug slice tracks

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

    Resultant pivoted debug slice tracks

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

  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.

    Create a new debug counter track

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

    Resultant pivoted debug counter track

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

    Create a new debug counter track

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

    Resultant pivoted debug counter track