README.md
1# Purgatorio
2
3[link on wikipedia](https://en.wikipedia.org/wiki/Purgatorio)
4
5
6
7Purgatorio is a visualization tool for simpleperf traces. It's based on [libsimpleperf](https://source.corp.google.com/android/system/extras/simpleperf/;l=1?q=simpleperf&sq=package:%5Eandroid$),
8[Bokeh](https://bokeh.org/) and [D3 flamegraphs](https://github.com/spiermar/d3-flame-graph).
9
10The main difference from [Inferno](https://source.corp.google.com/android/system/extras/simpleperf/scripts/inferno/;l=1) is that Purgatorio focuses on visualizing system-wide traces (the ones with the `-a` argument) on a time-organized sequence, and allow the user to interact with the graph by zooming, hovering on samples and visualize a flame graph for specific samples (be it restricted by time interval, set of threads or whatever subset).
11
12## Obtaining the sources
13
14 git clone sso://user/balejs/purgatorio
15
16## Getting ready
17
18**NOTE**: In theory it should work on most OSes, but Purgatorio has been tested on gLinux only. Any feedback, recommendations and patches to get it work elsewhere will be welcome (balejs@).
19
20Purgatorio tends to be self-contained, but Bokeh and some of its dependencies aren't shipped with the default python libraries, hence they require to be installed with pip3. Assuming they already have python3 installed, Purgatorio hopefuls should follow these steps:
21
22 $ sudo apt-get install python3-pip
23 $ pip3 install jinja2 bokeh pandas
24
25Run `python3 purgatorio.py -h` for a list of command-line arguments.
26
27## Example
28
29One can trace a Camera warm launch with:
30
31 $ adb shell simpleperf record --trace-offcpu --call-graph fp -o /data/local/camera_warm_launch.data -a
32 [launch camera here, then press ctrl + c]
33 $ adb pull /data/local/camera_warm_launch.data
34
35And then run:
36
37 python3 purgatorio.py camera_warm_launch.data
38
39If you get lots of "Failed to read symbols" messages, and backtraces in the diagram don't show the symbols you're interested into, you might want to try [building a symbols cache](https://chromium.googlesource.com/android_ndk/+/refs/heads/master/simpleperf/doc/README.md#how-to-solve-missing-symbols-in-report) for the trace, then run purgatorio again with:
40
41 python3 purgatorio.py camera_warm_launch.data -u [symbols cache]
42
43# Purgatorio interface
44The Purgatorio User Interface is divided in three areas:
45
46## Main Graph
47It's the area to the left, including process names and color-coded dots grouped by process. It's used to navigate throungh the trace and identify samples of ineterest. By hovering on a sample (or set of samples) their callstacks will be visualized over the graph. When selecting a et of samples, their aggregated data will be visualized in the other sections of the UI. Multiple sections of the graph can be aggregated by holding down the [ctrl] button during selection.
48
49The toolbox to the right can be used to configure interactions with the graph:
50
51
52
53## Flame graph
54The flame graph is located in the upper right portion. Once samples are selected in the main graph, the flame graph will show an interactive visualization for their aggregated callstacks. In this case the selection included mostly samples for com.google.android.GoogleCamera
55
56
57
58It's possible to select a given stack entry to zoom on it and look at entry deeper in the callstack
59
60
61
62When studiyng system issues it's often useful to visualize an inverted callstack. This can be done by clicking the related check box. The graph below is the same as in the first flame graph above, but with call stack inverted. In this case, inverted visualization directly points at [possible issues with io](http://b/158783580#comment12)
63
64
65
66## Sample table
67It's located in the lower right and counts samples by thread (for direct flame graphs) or symbol (for inverted flame graphs). Table columns can be sorted by clicking on their respective layers, and selecting specific lines filters the contents of the flame graph to the selected threads or symbols. Multiple lines can be selected at the same time.
68
69
70
