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