• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.title=Systrace
2parent.title=Tools
3parent.link=index.html
4@jd:body
5
6
7<p>The {@code systrace} tool helps analyze the performance of your application by capturing and
8  displaying execution times of your applications processes and other Android system processes. The
9  tool combines data from the Android kernel such as the CPU scheduler, disk activity and
10  application threads to generate an HTML report that shows an overall picture of an Android
11  device’s system processes for a given period of time.</p>
12
13<p>The {@code systrace} tool is particularly useful in diagnosing display problems where an
14  application is slow to draw or stutters while displaying motion or animation. For more information
15  on how to use {@code systrace}, see <a href="{@docRoot}tools/debugging/systrace.html">Analyzing
16  Display and Performance with Systrace</a>.</p>
17
18
19<h2 id="usage">Usage</h2>
20
21<p>In order to run {@code systrace}, the {@code adb} tool and
22<a href="http://www.python.org/">Python</a> must be installed and included in your development
23computer's execution path. In order to generate a trace, you must connect a device running Android
244.1 (API Level 16) or higher to your development system using a USB debugging connection.</p>
25
26<p>The syntax for running {@code systrace} is as follows.</p>
27
28<pre>
29$> python systrace.py [options]
30</pre>
31
32<p>Here is an example execution run that sets trace tags and generates a trace from a connected
33Android device.</p>
34
35<pre>
36$> cd <em>android-sdk</em>/tools/systrace
37$> python systrace.py --set-tags gfx,view,wm
38$> adb shell stop
39$> adb shell start
40$> python systrace.py --disk --time=10 -o mynewtrace.html
41</pre>
42
43
44
45<h2 id="options">Options</h2>
46
47<p>The table below lists the command line options for {@code systrace}.</p>
48
49<table>
50  <tr>
51    <th>Option</th>
52
53    <th>Description</th>
54  </tr>
55
56  <tr>
57    <td><code>-o&nbsp;&lt;<em>FILE</em>&gt;</code></td>
58
59    <td>Write the HTML trace report to the specified file.</td>
60  </tr>
61
62  <tr>
63    <td><code>-t N, --time=N</code></td>
64
65    <td>Trace activity for N seconds. Default value is 5 seconds.</td>
66  </tr>
67
68  <tr>
69    <td><code>-b N, --buf-size=N</code></td>
70
71    <td>Use a trace buffer size of N kilobytes. This option lets you limit the total size of the
72    data collected during a trace.</td>
73  </tr>
74
75  <tr>
76    <td><code>-d, --disk</code></td>
77
78    <td>Trace disk input and output activity. This option requires root access on the device.</td>
79  </tr>
80
81  <tr>
82    <td><code>-f, --cpu-freq</code></td>
83
84    <td>Trace CPU frequency changes. Only changes to the CPU frequency are logged, so the initial
85    frequency of the CPU when tracing starts is not shown.</td>
86  </tr>
87
88  <tr>
89    <td><code>-i, --cpu-idle</code></td>
90
91    <td>Trace CPU idle events.</td>
92  </tr>
93
94  <tr>
95    <td><code>-l, --cpu-load</code></td>
96
97    <td>Trace CPU load. This value is a percentage determined by the interactive CPU frequency
98    governor.</td>
99  </tr>
100
101  <tr>
102    <td><nobr><code>-s,&nbsp;--no-cpu-sched</code></nobr></td>
103
104    <td>Prevent tracing of the CPU scheduler. This option allows for longer trace times by reducing
105    the rate of data flowing into the trace buffer.</td>
106  </tr>
107
108  <tr>
109    <td><code>-w, --workqueue</code></td>
110
111    <td>Trace kernel work queues. This option requires root access on the device.</td>
112  </tr>
113
114  <tr>
115    <td id="tags"><code>--set-tags=&lt;<em>TAGS</em>&gt;</code></td>
116
117    <td>Set the enabled trace tags in a comma separated list. The available tags are:
118      <ul>
119        <li><code>gfx</code> - Graphics</li>
120        <li><code>input</code> - Input</li>
121        <li><code>view</code> - View</li>
122        <li><code>webview</code> - WebView</li>
123        <li><code>wm</code> - Window Manager</li>
124        <li><code>am</code> - Activity Manager</li>
125        <li><code>sync</code> - Sync Manager</li>
126        <li><code>audio</code> - Audio</li>
127        <li><code>video</code> - Video</li>
128        <li><code>camera</code> - Camera</li>
129      </ul>
130      <p class="note"><strong>Note:</strong> When setting trace tags from the command line, you
131      must stop and restart the framework ({@code $&gt; adb shell stop; adb shell start}) for the
132      tag tracing changes to take effect.</p>
133    </td>
134  </tr>
135
136  <tr>
137    <td><code>--link-assets</code></td>
138
139    <td>Link to the original CSS or JS resources instead of embedding them in the HTML trace
140    report.</td>
141  </tr>
142
143  <tr>
144    <td><nobr><code>-h, --help</code></nobr></td>
145
146    <td>Show the help message.</td>
147  </tr>
148
149</table>
150
151<p>You can set the trace <a href="#tags">tags</a> for {@code systrace} with your device's user
152interface, by navigating to <strong>Settings &gt; Developer options &gt; Monitoring &gt; Enable
153traces</strong>.</p>
154
155
156<h2 id="viewing-options">Trace Viewing Shortcuts</h2>
157
158<p>The table below lists the keyboard shortcuts that are available while viewing a {@code systrace}
159trace HTML report.</p>
160
161<table>
162  <tr>
163    <th>Key</th>
164
165    <th>Description</th>
166  </tr>
167
168  <tr>
169    <td><strong>w</strong></td>
170
171    <td>Zoom into the trace timeline.</td>
172  </tr>
173
174  <tr>
175    <td><strong>s</strong></td>
176
177    <td>Zoom out of the trace timeline.</td>
178  </tr>
179
180  <tr>
181    <td><strong>a</strong></td>
182
183    <td>Pan left on the trace timeline.</td>
184  </tr>
185
186  <tr>
187    <td><strong>d</strong></td>
188
189    <td>Pan right on the trace timeline.</td>
190  </tr>
191
192  <tr>
193    <td><strong>e</strong></td>
194
195    <td>Center the trace timeline on the current mouse location.</td>
196  </tr>
197
198  <tr>
199    <td><strong>g</strong></td>
200
201    <td>Show grid at the start of the currently selected task.</td>
202  </tr>
203
204  <tr>
205    <td><strong>Shift+g</strong></td>
206
207    <td>Show grid at the end of the currently selected task.</td>
208  </tr>
209
210  <tr>
211    <td><strong>Right Arrow</strong></td>
212
213    <td>Select the next event on the currently selected timeline.</td>
214  </tr>
215
216  <tr>
217    <td><strong>Left Arrow</strong></td>
218
219    <td>Select the previous event on the currently selected timeline.</td>
220  </tr>
221
222  <tr>
223    <td><strong>Double Click</strong></td>
224
225    <td>Zoom into the trace timeline.</td>
226  </tr>
227
228  <tr>
229    <td><strong>Shift+Double Click</strong></td>
230
231    <td>Zoom out of the trace timeline.</td>
232  </tr>
233
234</table>
235