This guide explains how to navigate around and interpret a
Systrace
report. To interpret a Perfetto report,
see the
Trace Processor
documentation.
Elements of a typical report
Systrace generates an output HTML file that contains a series of sections. The
report lists the threads of each process. If a given thread renders UI frames,
the report also indicates the rendered frames along the timeline. Time passes in
the forward direction as you move left to right across the report.
From top to bottom, the report contains the following sections.
User interactions
The first section contains bars that represent specific user interactions within
your app or game, such as tapping on the device's screen. These interactions
serve as useful time markers.
CPU activity
The next section shows bars that represent thread activity within each CPU. The
bars show CPU activity across all apps, including your app or game.
The CPU activity section is expandable, allowing you to view clock frequency for
each CPU. Figure 1 shows an example of a collapsed CPU activity section, and
Figure 2 shows an expanded version that displays clock frequency:
System events
The histograms in this section show specific system-level events, such as
texture counts and the total size of specific objects.
A histogram worth checking more closely is the one labeled
SurfaceView
. The
count represents the number of composed frame buffers that have been passed into
the display pipeline and are waiting to be shown on the device's screen. Because
most devices are double- or triple-buffered, this count is almost always 0, 1,
or 2.
Other histograms depicting the Surface Flinger process, including VSync events
and UI thread swap work, appear in Figure 3:
Display frames
This section, often the tallest in the report, depicts a multicolored line
followed by stacks of bars. These shapes represent the status and frame stack of
a particular thread that's been created. Each level of the stack represents a
call to
beginSection()
, or the beginning of a
custom trace
event
that you've defined for your app
or game.
The multicolored line above each stack of bars represents a particular thread's
set of statuses over time. Each segment of the line can contain one of the
following colors:
- Green: Running
- The thread is completing work related to a process or is responding to an
interrupt.
- Blue: Runnable
- The thread is available to run but isn't currently scheduled.
- White: Sleeping
- The thread has no work to do, perhaps because the thread is blocked on a mutex
lock.
- Orange: Uninterruptable sleep
- The thread is blocked on I/O or waiting for a disk operation to complete.
- Purple: Interruptable sleep
- The thread is blocked on another kernel operation, usually memory management.
Keyboard shortcuts
The following table lists the keyboard shortcuts that are available while
viewing a Systrace report:
Key
|
Description
|
W
|
Zoom in to the trace timeline.
|
A
|
Pan left on the trace timeline.
|
S
|
Zoom out of the trace timeline.
|
D
|
Pan right on the trace timeline.
|
E
|
Center the trace timeline on the current mouse location.
|
M
|
Frame the current selection.
|
1
|
Change the currently-active selection model to the "select" mode.
Corresponds to the 1st button that appears in the mouse selector
toolbar (see image to the right).
|
|
2
|
Change the currently-active selection model to the "pan" mode.
Corresponds to the 2nd button that appears in the mouse selector
toolbar (see image to the right).
|
|
3
|
Change the currently-active selection model to the "zoom" mode.
Corresponds to the 3rd button that appears in the mouse selector
toolbar (see image to the right).
|
|
4
|
Change the currently-active selection model to the "timing" mode.
Corresponds to the 4th button that appears in the mouse selector
toolbar (see image to the right).
|
|
G
|
Show grid at the start of the currently-selected task.
|
Shift + G
|
Show grid at the end of the currently-selected task.
|
Left Arrow
|
Select the previous event on the currently-selected timeline.
|
Right Arrow
|
Select the next event on the currently-selected timeline.
|
Investigate performance problems
When interacting with a Systrace report, you can inspect device CPU usage over
the duration of the recording. For help navigating the HTML report, see the
keyboard shortcuts
section, or click the
?
button in
the top-right corner of the report.
The sections below explain how to inspect information in the report to find and
fix performance problems.
When navigating around a Systrace report, you can identify performance concerns
more easily by doing one or more of the following:
- Select a time interval of interest by drawing a rectangle around the time
interval.
- Mark or highlight a problem area using the ruler tool.
- Show each display refresh operation by clicking
View Options > Highlight
VSync
.
Inspect UI frames and alerts
As shown in Figure 4, a Systrace report lists each process that renders UI
frames and indicates each rendered frame along the timeline. Frames that render
within the 16.6 milliseconds required to maintain a stable 60 frames per second
are indicated with green frame circles. Frames that take longer than 16.6
milliseconds to render are indicated with yellow or red frame circles.
Clicking on a frame circle highlights it and provides additional information
about the work done by the system to render that frame, including alerts. The
report also shows you the methods that the system was executing while rendering
that frame. You can investigate those methods to determine potential causes of
UI jank.
After you select a slow frame, you may see an alert in the bottom pane of the
report. The alert shown in Figure 5 calls out that the primary problem with the
frame is that too much time is spent inside
ListView
recycling and rebinding. There
are links to the relevant events in the trace that explain more about what the
system is doing during this time.
To see each alert that the tool discovered in your trace, as well as the number
of times that the device triggered each alert, click the
Alerts
tab at
the far right of the window, as shown in Figure 6. The
Alerts
panel helps
you see which problems occur in the trace and how often they contribute to jank.
You can think of this panel as a list of bugs to be fixed. Often, a small change
or improvement in one area can remove an entire set of alerts.
If you see too much work being done on the UI thread, use one of the following
approaches to help determine which methods are consuming too much CPU time:
- If you have an idea as to which methods could be causing bottlenecks, add
trace markers to these methods. To learn more, see the guide on how to
define
custom events in your code
.
- If you're unsure as to the source of UI bottlenecks, use the
CPU
Profiler
that's available in Android Studio.
You can
generate trace logs
, and
then import and inspect them using the CPU Profiler.