The systrace
tool helps analyze the performance of your application by capturing and
displaying execution times of your applications processes and other Android system processes. The
tool combines data from the Android kernel such as the CPU scheduler, disk activity and
application threads to generate an HTML report that shows an overall picture of an Android
device’s system processes for a given period of time.
The systrace
tool is particularly useful in diagnosing display problems where an
application is slow to draw or stutters while displaying motion or animation. For more information
on how to use systrace
, see Analyzing
Display and Performance with Systrace.
Usage
In order to run systrace
, the adb
tool and
Python must be installed and included in your development
computer's execution path. In order to generate a trace, you must connect a device running Android
4.1 (API Level 16) or higher to your development system using a USB debugging connection.
The syntax for running systrace
is as follows.
$> python systrace.py [options]
Here is an example execution run that sets trace tags and generates a trace from a connected Android device.
$> cd android-sdk/tools/systrace $> python systrace.py --set-tags gfx,view,wm $> adb shell stop $> adb shell start $> python systrace.py --disk --time=10 -o mynewtrace.html
Options
The table below lists the command line options for systrace
.
Option | Description |
---|---|
-o <FILE> |
Write the HTML trace report to the specified file. |
-t N, --time=N |
Trace activity for N seconds. Default value is 5 seconds. |
-b N, --buf-size=N |
Use a trace buffer size of N kilobytes. This option lets you limit the total size of the data collected during a trace. |
-d, --disk |
Trace disk input and output activity. This option requires root access on the device. |
-f, --cpu-freq |
Trace CPU frequency changes. Only changes to the CPU frequency are logged, so the initial frequency of the CPU when tracing starts is not shown. |
-i, --cpu-idle |
Trace CPU idle events. |
-l, --cpu-load |
Trace CPU load. This value is a percentage determined by the interactive CPU frequency governor. |
-s, --no-cpu-sched |
Prevent tracing of the CPU scheduler. This option allows for longer trace times by reducing the rate of data flowing into the trace buffer. |
-w, --workqueue |
Trace kernel work queues. This option requires root access on the device. |
--set-tags=<TAGS> |
Set the enabled trace tags in a comma separated list. The available tags are:
Note: When setting trace tags from the command line, you
must stop and restart the framework ( |
--link-assets |
Link to the original CSS or JS resources instead of embedding them in the HTML trace report. |
-h, --help |
Show the help message. |
You can set the trace tags for systrace
with your device's user
interface, by navigating to Settings > Developer options > Monitoring > Enable
traces.
Trace Viewing Shortcuts
The table below lists the keyboard shortcuts that are available while viewing a systrace
trace HTML report.
Key | Description |
---|---|
w | Zoom into the trace timeline. |
s | Zoom out of the trace timeline. |
a | Pan left on the trace timeline. |
d | Pan right on the trace timeline. |
e | Center the trace timeline on the current mouse location. |
g | Show grid at the start of the currently selected task. |
Shift+g | Show grid at the end of the currently selected task. |
Right Arrow | Select the next event on the currently selected timeline. |
Left Arrow | Select the previous event on the currently selected timeline. |
Double Click | Zoom into the trace timeline. |
Shift+Double Click | Zoom out of the trace timeline. |