1# Linux Profiling
2
3How to profile Chromium on Linux.
4
5See
6[Profiling Chromium and WebKit](https://sites.google.com/a/chromium.org/dev/developers/profiling-chromium-and-webkit)
7for alternative discussion.
8
9## CPU Profiling
10
11gprof: reported not to work (taking an hour to load on our large binary).
12
13oprofile: Dean uses it, says it's good. (As of 9/16/9 oprofile only supports
14timers on the new Z600 boxes, which doesn't give good granularity for profiling
15startup).
16
17TODO(willchan): Talk more about oprofile, gprof, etc.
18
19Also see
20https://sites.google.com/a/chromium.org/dev/developers/profiling-chromium-and-webkit
21
22### perf
23
24`perf` is the successor to `oprofile`. It's maintained in the kernel tree, it's
25available on Ubuntu in the package `linux-tools`.
26
27To capture data, you use `perf record`. Some examples:
28
29```shell
30# captures the full execution of the program
31perf record -f -g out/Release/chrome
32# captures a particular pid, you can start at the right time, and stop with
33# ctrl-C
34perf record -f -g -p 1234
35perf record -f -g -a  # captures the whole system
36```
37
38Some versions of the perf command can be confused by process renames. Affected
39versions will be unable to resolve Chromium's symbols if it was started through
40perf, as in the first example above. It should work correctly if you attach to
41an existing Chromium process as shown in the second example. (This is known to
42be broken as late as 3.2.5 and fixed as early as 3.11.rc3.g36f571. The actual
43affected range is likely much smaller. You can download and build your own perf
44from source.)
45
46The last one is useful on limited systems with few cores and low memory
47bandwidth, where the CPU cycles are shared between several processes (e.g.
48chrome browser, renderer, plugin, X, pulseaudio, etc.)
49
50To look at the data, you use:
51
52    perf report
53
54This will use the previously captured data (`perf.data`).
55
56### google-perftools
57
58google-perftools code is enabled when the `use_allocator` gn variable is set
59to `tcmalloc` (currently the default). That will build the tcmalloc library,
60including the cpu profiling and heap profiling code into Chromium. In order to
61get stacktraces in release builds on 64 bit, you will need to build with some
62extra flags enabled by setting `enable_profiling = true` in args.gn
63
64In order to enable cpu profiling, run Chromium with the environment variable
65`CPUPROFILE` set to a filename.  For example:
66
67    CPUPROFILE=/tmp/cpuprofile out/Release/chrome
68
69After the program exits successfully, the cpu profile will be available at the
70filename specified in the CPUPROFILE environment variable. You can then analyze
71it using the pprof script (distributed with google-perftools, installed by
72default on Googler Linux workstations). For example:
73
74    pprof --gv out/Release/chrome /tmp/cpuprofile
75
76This will generate a visual representation of the cpu profile as a postscript
77file and load it up using `gv`. For more powerful commands, please refer to the
78pprof help output and the google-perftools documentation.
79
80Note that due to the current design of google-perftools' profiling tools, it is
81only possible to profile the browser process.  You can also profile and pass the
82`--single-process` flag for a rough idea of what the render process looks like,
83but keep in mind that you'll be seeing a mixed browser/renderer codepath that is
84not used in production.
85
86For further information, please refer to
87http://google-perftools.googlecode.com/svn/trunk/doc/cpuprofile.html.
88
89## Heap Profiling
90
91### google-perftools
92
93#### Turning on heap profiles
94
95Follow the instructions for enabling profiling as described above in the
96google-perftools section under CPU Profiling.
97
98To turn on the heap profiler on a Chromium build with tcmalloc, use the
99`HEAPPROFILE` environment variable to specify a filename for the heap profile.
100For example:
101
102    HEAPPROFILE=/tmp/heapprofile out/Release/chrome
103
104After the program exits successfully, the heap profile will be available at the
105filename specified in the `HEAPPROFILE` environment variable.
106
107Some tests fork short-living processes which have a small memory footprint. To
108catch those, use the `HEAP_PROFILE_ALLOCATION_INTERVAL` environment variable.
109
110#### Dumping a profile of a running process
111
112To programmatically generate a heap profile before exit, use code like:
113
114    #include "third_party/tcmalloc/chromium/src/google/heap-profiler.h"
115
116    // "foobar" will be included in the message printed to the console
117    HeapProfilerDump("foobar");
118
119For example, you might hook that up to some action in the UI.
120
121Or you can use gdb to attach at any point:
122
1231.  Attach gdb to the process: `$ gdb -p 12345`
1241.  Cause it to dump a profile: `(gdb) p HeapProfilerDump("foobar")`
1251.  The filename will be printed on the console you started Chrome from; e.g.
126    "`Dumping heap profile to heap.0001.heap (foobar)`"
127
128#### Analyzing dumps
129
130You can then analyze dumps using the `pprof` script (distributed with
131google-perftools, installed by default on Googler Linux workstations; on Ubuntu
132it is called `google-pprof`). For example:
133
134    pprof --gv out/Release/chrome /tmp/heapprofile
135
136This will generate a visual representation of the heap profile as a postscript
137file and load it up using `gv`. For more powerful commands, please refer to the
138pprof help output and the google-perftools documentation.
139
140(pprof is slow. Googlers can try the not-open-source cpprof; Evan wrote an open
141source alternative [available on github](https://github.com/martine/hp).)
142
143#### Sandbox
144
145Sandboxed renderer subprocesses will fail to write out heap profiling dumps. To
146work around this, turn off the sandbox (via `export CHROME_DEVEL_SANDBOX=`).
147
148#### Troubleshooting
149
150*   "Hooked allocator frame not found": build with `-Dcomponent=static_library`.
151    `tcmalloc` gets confused when the allocator routines are in a different
152    `.so` than the rest of the code.
153
154#### More reading
155
156For further information, please refer to
157http://google-perftools.googlecode.com/svn/trunk/doc/heapprofile.html.
158
159## Paint profiling
160
161You can use Xephyr to profile how chrome repaints the screen. Xephyr is a
162virtual X server like Xnest with debugging options which draws red rectangles to
163where applications are drawing before drawing the actual information.
164
165    export XEPHYR_PAUSE=10000
166    Xephyr :1 -ac -screen 800x600 &
167    DISPLAY=:1 out/Debug/chrome
168
169When ready to start debugging issue the following command, which will tell
170Xephyr to start drawing red rectangles:
171
172    kill -USR1 `pidof Xephyr`
173
174For further information, please refer to
175http://cgit.freedesktop.org/xorg/xserver/tree/hw/kdrive/ephyr/README.
176