Investigating scroll/animation jank

You are noticing janks when you are scrolling a page, or during an animation. You want to investigate the jank. This document gives a quick overview of how you can do this.

Collecting a trace

The best way to debug a janky scroll/animation is to collect a trace during the event. There are detailed instructions for doing this here, but briefly, to collect a trace:

  • Close as many tabs/windows as possible. When a trace is collected, it collects traces from all running processes. Having a lot of tabs usually means there are a lot of processes too, and traces from all these processes can make it difficult to debug/investigate.
    • If the jank can be reproduced reliably, then a good option is to start a new instance of chrome in a test-only temporary profile (using --user-data-dir command-line flag).
  • Open up chrome:tracing in a new tab (or in a new window).
  • Click ‘Record’:

  • Select ‘Rendering’ in the dialog, and click ‘Record’:

  • Switch to the tab with the page in question.
  • Perform the action, e.g. scroll, or allow the animation to happen. Do this a few times to increase the chances of janks happening.
    • Note that you cannot collect trace for too long, because the trace-buffer can fill up pretty quickly.
  • Once you have noticed a jank, you can switch back to the chrome:tracing page, and click on ‘Stop’.

  • Click ‘Save’ to save the trace. This step is optional, but can be useful when sharing the trace with other developers, or attaching to a crbug, etc..

Quick tips for the trace-viewer

This document does not explain all the ways of navigating the trace-viewer, but some quick tips:

  • The trace includes trace-events from all the processes. This means the browser process, the gpu process, the utility processes, all the renderer processes, etc. Often, when you are investigating a jank, many of these processes are not particularly relevant. The most important processes to track are: the browser process, the gpu process, and the renderer process hosting the page you are investigating. You can click on ‘Processes’ to filter out the processes that are not interesting/relevant.

  • You can also click on the close-buttons for each process separately to hide them. You can always click on ‘Processes’ any time to show the process again if you want.

  • You can turn on ‘flow’ events, which are sometimes very useful (M79 or earlier; see more below).