xref: /aosp_15_r20/external/perfetto/docs/visualization/perfetto-ui.md (revision 6dbdd20afdafa5e3ca9b8809fa73465d530080dc) 
1# Perfetto UI
2
3[Perfetto UI](https://ui.perfetto.dev) enables you to view and analyze traces in
4the browser. It supports several different tracing formats, including the
5perfetto proto trace format and the legacy json trace format.
6
7## New Features
8What features have come to the UI recently? See below.
9
10### Tabs V2
11
12We've refreshed how the tabs in the details pane at the bottom of the
13timeline work.
14
15NOTE: Temporarily you can use the previous tab implementation via
16setting the [Tabs V2 feature flag](http://ui.perfetto.dev/#!/flags) to
17'Disabled'. Please file a bug with feedback on Tabs V2.
18
19The update aimed to address a few major UX concerns with the existing
20implementation while also making tabs extensible via plugins.
21
22UX concerns in TabsV1:
23- Tabs disappear and reappear when the user changes the selection causing surprise and confusion.
24- We try to guess the right tab to get focus and this guess is often incorrect.
25- 'Ephemeral tabs' (query results and SQL tables) work differently from
26  'permanent tabs ('Ftrace events' and 'Android Logs'). Ephemeral tabs can be closed while permanent tabs can not.
27- 'Current selection' tabs work differently to both 'ephemeral' and 'permanent' tabs and there can only be a single 'Current selection' tab
28  even when the current selection contains many different kinds of data.
29- Ephemeral tabs are not persisted into permalinks.
30
31![Tabs V2 demo](https://storage.googleapis.com/perfetto-misc/feature-tabs-v2.gif)
32
33TabsV2 is extensible via the [plugin mechanism](/docs/contributing/ui-plugins).
34Plugins can add new permanent and ephemeral tabs as well as new selection panels.
35
36### Custom visualisation with Vega and Vega-lite
37
38The `Viz` page available in the sidebar after you load the trace allows
39for custom visualisation using [Vega](https://vega.github.io/vega/) or
40[Vega-lite](https://vega.github.io/vega-lite/docs/).
41
42Type a Vega specification into the bottom editor pane and the
43visualisation will update in real time in the top pane.
44You can put arbitrary `trace_processor` SQL queries where the URL would
45go in a normal Vega visualisation.
46
47![Viz page](https://storage.googleapis.com/perfetto-misc/feature-viz-page.png)
48
49Try the following visualisation with the Android example trace:
50
51```json
52{
53  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
54  "data": {"url": "select cpu, dur from sched where utid != 0"},
55  "mark": "bar",
56  "encoding": {
57    "x": {
58      "field": "cpu"
59    },
60    "y": {"aggregate": "sum", "field": "dur"}
61  }
62}
63```
64
65### Command Palette
66Tired of remembering the location of buttons in the Perfetto UI?
67Commands to the rescue!
68
69![Command](https://storage.googleapis.com/perfetto-misc/feature-command-palette.gif)
70
71Commands are:
72- Discoverable & Searchable
73- Keyboard driven
74- Plugin-able
75- Context sensitive
76- ...with more added every day
77
78Access the command palette via `Ctrl-Shift-P` or by typing `>` in the
79search bar.
80
81### Changing the time format and offset
82
83![Time](https://storage.googleapis.com/perfetto-misc/feature-time.gif)
84
85The displayed timestamp format can be changed globally, cycling between seconds, raw nanoseconds and a new "timecode" format.
86We also have a new `TO_TIMECODE()` function in Trace Processor to print timestamps in the timecode format.
87
88## UI Tips and Tricks
89
90### Pivot Tables
91
92To use pivot tables in the Perfetto UI, you will need to enable the
93"Pivot tables" feature flag in the "Flags" tab under "Support" in the Sidebar.
94You can pop up a pivot table over the entire trace when clicking "p" on your
95keyboard. The "Edit" button opens a pop up window to add/remove and reorder
96columns and change the default sorting of aggregations.
97
98![Pivot table editor](/docs/images/pivot-tables/pivot-table-editor.png)
99
100Clicking on "Query" generates a table with the selected columns.
101Table cells with the expand icon can be expanded to show the next column values.
102The "name (stack)" column displays top level slices that can be expanded to show
103their descendants down to the last child.
104
105![Pivot table](/docs/images/pivot-tables/pivot-table.png)
106
107Area selection pops up a pre-filled pivot table restricted over the selected
108timestamps and track ids.
109
110![Pivot table area selection](/docs/images/pivot-tables/pivot-table-area-selection.png)
111
112### Disabling metrics
113
114Some metrics execute at trace load time to annotate the trace with
115additional tracks and events. You can stop these metrics from
116running by disabling them in the 'Flags' page:
117
118![Disable metrics from running at trace load time](/docs/images/perfetto-ui-disable-metrics.png)
119
120
121