Merge "Document Debug Tracks on docs.perfetto.dev." into main
diff --git a/docs/analysis/debug-tracks.md b/docs/analysis/debug-tracks.md
new file mode 100644
index 0000000..e3c973c
--- /dev/null
+++ b/docs/analysis/debug-tracks.md
@@ -0,0 +1,33 @@
+# Debug Tracks
+
+Debug Tracks are a way to display tabular results from running a PerfettoSQL
+query as a new so-called "debug" track. Specifically, if the resultant table can
+be visualised in a slice format (for example, the
+[`slice`](sql-tables.autogen#slice) table), a debug track can be created from
+it.
+
+For a result table to be able to be visualised in a slice format, 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. (Optionally) a duration (the duration, in nanoseconds, of the slice) column.
+
+To create a new debug track:
+
+1. Run a SQL query, and ensure its results are `slice`-like (as described
+ above).
+ 
+1. Navigate to the Timeline view, and click on "Show debug track" to set up a
+ new debug track. 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.
+ 
+1. The debug 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). The debug
+ track may be manually unpinned and then it should appear on the top of other
+ unpinned tracks.
+ 
diff --git a/docs/images/debug-tracks/debug-tracks-create.png b/docs/images/debug-tracks/debug-tracks-create.png
new file mode 100644
index 0000000..c98b49b
--- /dev/null
+++ b/docs/images/debug-tracks/debug-tracks-create.png
Binary files differ
diff --git a/docs/images/debug-tracks/debug-tracks-query.png b/docs/images/debug-tracks/debug-tracks-query.png
new file mode 100644
index 0000000..99d2029
--- /dev/null
+++ b/docs/images/debug-tracks/debug-tracks-query.png
Binary files differ
diff --git a/docs/images/debug-tracks/debug-tracks-result.png b/docs/images/debug-tracks/debug-tracks-result.png
new file mode 100644
index 0000000..51d6fd2
--- /dev/null
+++ b/docs/images/debug-tracks/debug-tracks-result.png
Binary files differ
diff --git a/docs/toc.md b/docs/toc.md
index eca4ee7..d7c34e3 100644
--- a/docs/toc.md
+++ b/docs/toc.md
@@ -58,6 +58,7 @@
* [Deep linking to Perfetto UI](visualization/deep-linking-to-perfetto-ui.md)
* [Perfetto UI release process](visualization/perfetto-ui-release-process.md)
* [Pivot tables](analysis/pivot-tables.md)
+ * [Debug tracks](analysis/debug-tracks.md)
* [Core concepts](#)
* [Trace configuration](concepts/config.md)
