Telemetry: Profiling
Warning: Use these directions at your own risk: --profiler is deprecated and platform/tracing_controller.py should be used instead for scenarios requiring long-term support for profiling data collection.
Tracing
On all platforms, Telemetry can gather an about:tracing trace for each page in the page_set. To do so, simply pass the --profiler=trace flag. For example:
$ tools/perf/run_benchmark --profiler=trace page_cycler tools/perf/page_sets/typical_25.json
Instructions for opening the results will be printed.
CPU Profiling - Linux / Android and Mac
Linux / Android
In order for Linux profilers to display call graph information correctly, it is necessary to first build with profiling=1 (GYP) or enable_profiling = true (GN). To do so:
$ # Linux (GYP)
$ GYP_DEFINES='profiling=1' gclient runhooks
$ ninja -C out/Release chrome
$ # Android (GYP)
$ GYP_DEFINES="OS=android profiling=1 release_extra_cflags=-fno-omit-frame-pointer disable_pie=1" \
gclient runhooks
$ ninja -C out/Release chrome_public_apk
$ # GN
$ gn args out/Profiling
# include "enable_profiling = true"
$ export CHROMIUM_OUTPUT_DIR="$PWD/out/Profiling"
$ ninja -C out/Profiling chrome_public_apk
perf
On Linux and Android, Telemetry can gather a perf profile for each page in the page_set. To do so, pass the --profiler=perf flag. For example:
$ tools/perf/run_benchmark --profiler=perf kraken
Instructions for opening the results will be printed.
If the page_set you are profiling includes cross-origin navigations, it is necessary to pass --page-repeat=2 so that renderer process is not swapped out mid-profile on the second run. For example:
$ tools/perf/run_benchmark --profiler=perf --page-repeat=2 page_cycler tools/perf/page_sets/intl_ar_fa_he.json
You may find it useful to install a copy of perf from your distro's repository and use that instead of the included perfhost binary (e.g. for additional UI options), as long as you use the flags Telemetry suggests.
VTune
On x86 builds (including Android on x86) Telemetry can collect an Intel VTune profile for each page in the page_set. This requires VTune to be installed on your home system. To collect a profile, pass the --profiler=vtune flag. For example:
$ tools/perf/run_benchmark --profiler=vtune kraken
You can then open the results in the VTune GUI. Instructions for opening the results will be printed.
gprof
While not explicitly supported by Telemetry. It is possible to gather a gprof profile for the entire measurement run when running in single process mode. To do so, first build with profiling enabled, -fno-omit-frame-pointer and without position independent code:
$ GYP_DEFINES='profiling=1' gclient runhooks
$ ninja -C out/Release chrome
Then run with CPUPROFILE in the environment and --single-process. For example:
$ CPUPROFILE=/tmp/myprofile tools/perf/run_benchmark --extra-browser-args=--single-process sunspider
View the profile like so:
$ cpprof --gv out/Release/chrome /tmp/myprofile
systrace
Telemetry also supports recording an Android Systrace while running measurements:
$ tools/perf/run_benchmark --profiler=android-systrace kraken
The resulting trace file can be opened in Chrome by going to about:tracing and clicking on "Load".
Mac
On mac, Telemetry can gather an Instruments profile for each page in the page_set. To do so, pass the --profiler=iprofiler flags. For example:
$ tools/perf/run_benchmark --profiler=iprofiler octane
Instructions for opening the results will be printed. Once in Instruments, if symbols are not resolved, go to “File > Re-Symbolicate Document...” and browse to the *.dsym files for Chromium Framework and Chromium Helper.
Memory Profiling - Linux / Android
Linux / Android (C/C++)
On special instrumented builds of linux Android, Telemetry can gather TCMalloc heap dumps that can be then fed to Deep Memory Profiler . Please check that page for:
GYP_DEFINES for both platforms.
linux: environment variables
android: system properties (note: requires a rooted device)
Run any measurement with --profiler=tcmalloc-heap flags. For example:
$ tools/perf/run_benchmark -v --browser=android-content-shell --profiler=tcmalloc-heap memory.top_25
Once the measurement completes, the dump files will be in /tmp/{RANDOM}.
Follow instructions from the Deep Memory Profiler to generate the data and graphs.
Note: depending on the page set, there’ll be multiple directories under /tmp/{RANDOM}, one per page in the set. In each folder, there’ll be a mix of dumps per browser and renderer processes for that particular page. You may want to analyse the browser process across the entire page set, rather than just a particular page. To do so:
There’s a file called “browser.pid” on each one of the page directories.
Copy (or move) all dump files for that pid to say, “browser/”.
Run dmprof on that folder.
Android Memory Report
Telemetry can gather high level "memory report" for each page in the page_set. To do so, pass the --profiler=android-memreport flags. At the end of the test, it will print a link to the HTML page that was generated. This profile gives an overview of all memory (including mapped files, read-only, dirty, clean pages, etc..) but without any backtrace like the ones above. It does not require any instrumented build, as it gathers all information directly from /proc/PID/maps, etc..
Android Java
Telemetry can gather “heap profiles” for the java side for each page in the page_set. To do so, pass the --profiler=java-heap flags. For example:
$ tools/perf/run_benchmark -v --browser=android-content-shell --profiler=java-heap memory.top_25
The dump files will then be fetched in /tmp/{RANDOM} in the host, already converted to “hprof” format which can be used by tools like Eclipse’s MAT. This post from the android team contains useful instructions. Please note: android has a “zygote” process that contains pre-loaded resources for all apps. These resources will show up in the heap profile: they are actually shared across all apps, they aren't exclusive to the process being profiled.
Network Profiling - Linux / Android
Linux / Android
Telemetry can gather “tcpdump” network captures for each page in the page_set. To do so, pass the --profiler=tcpump flags. For example:
$ tools/perf/run_benchmark --browser=android-content-shell --profiler=tcpdump memory_measurement memory.top_25
The dump files will then be fetched in /tmp/{RANDOM}, and then can be opened in tools such as Wireshark.
On android, "tcpdump" binary will be downloaded from cloud storage and installed in the device automatically.
"Manual" Profiling - Android
Sometimes it's useful to drive the browser "manually" in order to run a specific profiler during a regular browsing session. This command:
$ tools/perf/record_android_profile.py --browser=android-chrome --profiler=perf
Will launch the browser and the associated profiler and wait until you hit enter. It will then fetch all profile data from the device and print instructions on how to open them.
You can also use adb_profile_chrome to record a perf profile from a running browser:
$ tools/android/adb_profile_chrome --browser=build --time 5 --perf