What it does
When diagnosing performance problems it can be valuable to see what Chrome is doing "under the hood." One way to get a more detailed view into what's going on is to use the about:tracing tool.
How to record tracing runs (desktop)
Sometimes Chromium developers will ask for about:tracing results in a bug report to help us understand what's going on. Recording a tracing run is easy:
- Open up a new tab and type "about:tracing" in the Omnibox
- Hit "record"
- Switch back to the tab with the content you're debugging and do whatever it is that's slower than it should be (or behaving incorrectly). A few seconds of the bad activity is usually sufficient.
- Switch back to the tracing tab and hit "Stop tracing", then hit "Save"
- (Optional) If this is for a bug report, upload the output file as an attachment to bug. If the file is bigger than 10MB, zip it first (the files compress well, and files bigger than 10MB can be truncated during upload). IMPORTANT: Before attaching a trace to a bug keep in mind that it will contain the URL and Title of all open tabs, URLs of subresources used by each tab, extension IDs, hardware identifying details, and other similar information that you may not want to make public.
You can also record traces when starting chrome. Assuming $CHROME is set to the command you need on your OS to start chrome, the following will record the first 7 seconds of Chrome's lifetime into /tmp/foo.json
$CHROME --trace-startup --trace-startup-file=/tmp/foo.json --trace-startup-duration=7
How to record tracing runs (Android)
To record tracing runs on Android, you'll need your device running Chrome on Android with USB debugging enabled and attached to your computer. You'll also need ADB
, as well as a Chromium check-out (or John Mccutchan's stand-alone script). Note that this procedure currently only works on Linux and Mac.
With these prerequisites in place, follow the steps below to record a trace:
1. Launch the browser
$ build/android/adb_run_content_shell URL
or (Googlers only):
$ clank/bin/adb_run_chrome URL
2. Make a screen recording (optional)
$ build/android/screenshot.py --video
$ build/android/adb_profile_chrome --browser build --time 5 --view
Note: build here refers to the version of Chrome you are tracing. Other valid values are stable, beta (see --help for a full list).
You can also use additional command line flags to capture more data. For example:
1. Systrace: --systrace gfx,view,input,freq,sched
Captures data about system-level events. Generally useful categories are
sched = Kernel scheduling decisions
freq = CPU core frequency scaling
gfx = SurfaceFlinger events, Vsync
view = Android Framework events
input = Framework input event processing
adb shell atrace --list_categories shows the rest.
2. IPC messages: --trace-flow
Adds arrows showing IPC message flows, making it easier to see message traffic.
3. More trace categories, e.g.: --categories=disabled-by-default-cc.debug.scheduler,*
Adding more trace categories makes it possible to see events that are normally disabled. This particular example gives information about why the compositor scheduler decided to run a given action. To see the full list of categories, navigate to about://tracing on desktop Chrome and click on Record.
4. Frame viewer data: --trace-frame-viewer
Captures rich layer data from the compositor. This is useful for understanding how the DOM affects the compositor's layer tree structure. When viewing traces like this, make sure to launch Chrome (on the desktop) with the --enable-skia-benchmarking command line flag so that all features are available.
5. Perf profiling data: --perf
Perf is a sampling profiler which can help you find performance intensive parts of the source code. The --perf switch runs perf and automatically combines the data with all other enabled event sources.
You can also view the raw recorded perf data using the command line which is printed out by adb_profile_chrome.
Making a Good Recording
Step by step:
- Keep the recording to a max of 10 seconds
- Try to keep to 1 activity per recording. If you see two slowdowns, do one recording each. Or leave a second long pause between each.
- Pause and leave the computer completely idle for 2 seconds before and after demonstrating the slowdown. This helps make the slow part obvious in the recording.
- Start with only the tab you’re investigating and about:tracing open in a fresh browser session (see below for other methods of figuring out which tab is which if you need multiple).
- Set up the tab for investigation to right before the point where the problem will occur (e.g. right before an animation is going to be triggered, or right before part of the page that scrolls slowly)
- Start a tracing run in the about:tracing tab
- Switch to the tab under investigation
- Pause for a couple seconds to record empty space on the timeline (makes finding it later easier)
- Perform the action to trigger the bad performance behavior (e.g. start the animation or scroll the page). Keeping the recorded activity under 10 seconds is a good idea.
- Pause again
- Switch back to the about:tracing tab and stop the recording.
Tracing in Telemetry
For more repeatable trace recordings you may want to consider using Telemetry to automate the process. In particular the --profiler=trace and --profiler=android-systrace flags will save a trace for each tested page.