1page.title=Systrace 2parent.title=Tools 3parent.link=index.html 4@jd:body 5 6 7<p>The 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 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 Systrace, see <a href="{@docRoot}tools/debugging/systrace.html">Analyzing 16 UI Performance with Systrace</a>.</p> 17 18<h2 id="requirements">Requirements</h2> 19 20<p>In order to run Systrace, you must have Android SDK Tools 20 or later installed. You must also 21have <a href="http://www.python.org/">Python</a> installed and included in your development 22computer's execution path. In order to generate a trace, you must connect a device running Android 234.1 (API Level 16) or higher to your development system using a 24<a href="{@docRoot}tools/device.html#setting-up">USB debugging connection</a>.</p> 25 26<p>The Systrace tool can be run either from one of the Android SDK's graphical user interface 27tools, or from the command line. The following sections describe how to run the tool using either 28of these methods.</p> 29 30 31<h2 id="gui">User Interface</h2> 32 33<p>The Systrace tool can be run from the 34<a href="{@docRoot}tools/help/adt.html">Android Developer Tools</a> (ADT) in Eclipse, 35<a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>, 36or the Android <a href="{@docRoot}tools/help/monitor.html">Device Monitor</a>. 37 38<p>To run the Systrace capture user interface:</p> 39 40<div class="toggle-content closed"> 41<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 42 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 43 />Using Eclipse</a></p> 44 45 <div class="toggle-content-toggleme"> 46 <ol> 47 <li>In Eclipse, open an Android application project.</li> 48 <li>Switch to the DDMS perspective, by selecting <strong>Window > Perspectives > 49 DDMS</strong>.</li> 50 <li>In the <strong>Devices</strong> tab, select the device on which to run a trace. If no 51 devices are listed, make sure your device is connected via USB cable and that debugging is 52 enabled on the device.</li> 53 <li>Click the Systrace icon <img src="{@docRoot}images/systrace/systrace-button.png" 54 style="margin:0"/> at the top of the <strong>Devices</strong> panel to configure tracing.</li> 55 <li>Set the tracing options and click <strong>OK</strong> to start the trace.</li> 56 </ol> 57 </div> 58</div> 59 60<div class="toggle-content closed"> 61<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 62 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 63 />Using Android Studio</a></p> 64 65 <div class="toggle-content-toggleme"> 66 <ol> 67 <li>In <a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>, open an 68 Android application project.</li> 69 <li>Open the Device Monitor by selecting <strong>Tools > Android > Android Device 70 Monitor</strong>.</li> 71 <li>In the <strong>Devices</strong> tab, select the device on which to run a trace. If no 72 devices are listed, make sure your device is connected via USB cable and that debugging is 73 enabled on the device.</li> 74 <li>Click the Systrace icon <img src="{@docRoot}images/systrace/systrace-button.png" 75 style="margin:0"/> at the top of the <strong>Devices</strong> panel to configure tracing.</li> 76 <li>Set the tracing options and click <strong>OK</strong> to start the trace.</li> 77 </ol> 78 </div> 79</div> 80 81<div class="toggle-content closed"> 82<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 83 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 84 />Using Device Monitor</a></p> 85 86 <div class="toggle-content-toggleme"> 87 <ol> 88 <li>Navigate to your SDK {@code tools/} directory.</li> 89 <li>Run the {@code monitor} program.</li> 90 <li>In the <strong>Devices</strong> tab, select the device on which to run a trace. If no 91 devices are listed, make sure your device is connected via USB cable and that debugging is 92 enabled on the device.</li> 93 <li>Click the Systrace icon <img src="{@docRoot}images/systrace/systrace-button.png" 94 style="margin:0"/> at the top of the <strong>Devices</strong> panel to configure tracing.</li> 95 <li>Set the tracing options and click <strong>OK</strong> to start the trace.</li> 96 </ol> 97 </div> 98</div> 99 100 101<h2 id="options">Command Line Usage</h2> 102 103<p>The Systrace tool has different command line options for devices running Android 4.3 (API 104level 18) and higher versus devices running Android 4.2 (API level 17) and lower. The following 105sections describe the different command line options for each version.</p> 106 107<p>The general syntax for running Systrace from the command line is as follows.</p> 108 109<pre> 110$ python systrace.py [options] [category1] [category2] ... [categoryN] 111</pre> 112 113<p>See the sections below for example Systrace sessions.</p> 114 115 116<h3 id="options-4.3">Android 4.3 and higher options</h3> 117 118<p>When you use Systrace on devices running Android 4.3 and higher, you can omit trace category tags 119to get the defaults, or you may manually specify tags for inclusion. Here is an example execution 120run that sets trace tags and generates a trace from a connected device.</p> 121 122<pre> 123$ cd <em>android-sdk</em>/platform-tools/systrace 124$ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm 125</pre> 126 127<p class="note"> 128 <strong>Tip:</strong> If you want to see the names of tasks in the trace output, you <em>must</em> 129 include the {@code sched} category in your command parameters. 130</p> 131 132<p>The table below lists the Systrace command line options for devices running Android 4.3 133(API level 18) and higher.</p> 134 135<table> 136 <tr> 137 <th>Option</th> 138 139 <th>Description</th> 140 </tr> 141 142 <tr> 143 <td><nobr><code>-h, --help</code></nobr></td> 144 145 <td>Show the help message.</td> 146 </tr> 147 148 <tr> 149 <td><code>-o <<em>FILE</em>></code></td> 150 151 <td>Write the HTML trace report to the specified file.</td> 152 </tr> 153 154 <tr> 155 <td><code>-t N, --time=N</code></td> 156 157 <td>Trace activity for <em>N</em> seconds. The default value is 5 seconds.</td> 158 </tr> 159 160 <tr> 161 <td><code>-b N, --buf-size=N</code></td> 162 163 <td>Use a trace buffer size of <em>N</em> kilobytes. This option lets you limit the total size 164 of the data collected during a trace.</td> 165 </tr> 166 167 <tr> 168 <td><code>-k <<em>KFUNCS</em>><br> 169 --ktrace=<<em>KFUNCS</em>></code></td> 170 171 <td>Trace the activity of specific kernel functions, specified in a comma-separated list.</td> 172 </tr> 173 174 <tr> 175 <td><code>-l, --list-categories</code></td> 176 177 <td>List the available tracing category tags. The available tags are: 178 179 <ul> 180 <li><code>gfx</code> - Graphics</li> 181 <li><code>input</code> - Input</li> 182 <li><code>view</code> - View</li> 183 <li><code>webview</code> - WebView</li> 184 <li><code>wm</code> - Window Manager</li> 185 <li><code>am</code> - Activity Manager</li> 186 <li><code>audio</code> - Audio</li> 187 <li><code>video</code> - Video</li> 188 <li><code>camera</code> - Camera</li> 189 <li><code>hal</code> - Hardware Modules</li> 190 <li><code>res</code> - Resource Loading</li> 191 <li><code>dalvik</code> - Dalvik VM</li> 192 <li><code>rs</code> - RenderScript</li> 193 <li><code>sched</code> - CPU Scheduling</li> 194 <li><code>freq</code> - CPU Frequency</li> 195 <li><code>membus</code> - Memory Bus Utilization</li> 196 <li><code>idle</code> - CPU Idle</li> 197 <li><code>disk</code> - Disk input and output</li> 198 <li><code>load</code> - CPU Load</li> 199 <li><code>sync</code> - Synchronization Manager</li> 200 <li><code>workq</code> - Kernel Workqueues</li> 201 </ul> 202 203 <p class="note"><strong>Note:</strong> Some trace categories are not supported on all 204 devices.</p> 205 206 <p class="note"><strong>Tip:</strong> If you want to see the names of tasks in the trace 207 output, you <em>must</em> include the {@code sched} category in your command parameters.</p> 208 209 </td> 210 </tr> 211 212 <tr> 213 <td><code>-a <<em>APP_NAME</em>><br> 214 --app=<<em>APP_NAME</em>></code></td> 215 216 <td>Enable tracing for applications, specified as a comma-separated list of 217 <a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package names</a>. 218 The apps must contain tracing instrumentation calls from the {@link android.os.Trace} class. 219 For more information, see <a href="{@docRoot}tools/debugging/systrace.html#app-trace">Analyzing 220 UI Performance with Systrace</a>. 221 </td> 222 </tr> 223 224 <tr> 225 <td><code>--from-file=<<em>FROM_FILE</em>></code></td> 226 227 <td>Create the interactive Systrace report from a file, instead of running a live trace.</td> 228 </tr> 229 230 <tr> 231 <td style="white-space:nowrap"> 232 <code>-e <<em>DEVICE_SERIAL</em>><br> 233 --serial=<<em>DEVICE_SERIAL</em>></code></td> 234 235 <td>Conduct the trace on a specific connected device, identified by its 236 <a href="{@docRoot}tools/help/adb.html#devicestatus">device serial number</a>.</td> 237 </tr> 238 239</table> 240 241 242<h3 id="options-pre-4.3">Android 4.2 and lower options</h3> 243 244<p>Using Systrace on the command line with devices running Android 4.2 and lower is typically a 245two-step process. You must first set the trace tags you want to capture and then run the trace. 246Here is an example execution run that sets trace tags and generates a trace from a connected 247device.</p> 248 249<pre> 250$ cd <em>android-sdk</em>/platform-tools/systrace 251$ python systrace.py --set-tags gfx,view,wm 252$ adb shell stop 253$ adb shell start 254$ python systrace.py --disk --time=10 -o mynewtrace.html 255</pre> 256 257<p>The table below lists the Systrace command line options for devices running Android 4.2 258(API level 17) and lower.</p> 259 260<table> 261 <tr> 262 <th>Option</th> 263 264 <th>Description</th> 265 </tr> 266 267 <tr> 268 <td><nobr><code>-h, --help</code></nobr></td> 269 270 <td>Show the help message.</td> 271 </tr> 272 273 <tr> 274 <td><code>-o <<em>FILE</em>></code></td> 275 276 <td>Write the HTML trace report to the specified file.</td> 277 </tr> 278 279 <tr> 280 <td><code>-t N, --time=N</code></td> 281 282 <td>Trace activity for <em>N</em> seconds. The default value is 5 seconds.</td> 283 </tr> 284 285 <tr> 286 <td><code>-b N, --buf-size=N</code></td> 287 288 <td>Use a trace buffer size of <em>N</em> kilobytes. This option lets you limit the total size 289 of the data collected during a trace.</td> 290 </tr> 291 292 <tr> 293 <td><code>-d, --disk</code></td> 294 295 <td>Trace disk input and output activity. This option requires root access on the device.</td> 296 </tr> 297 298 <tr> 299 <td><code>-f, --cpu-freq</code></td> 300 301 <td>Trace CPU frequency changes. Only changes to the CPU frequency are logged, so the initial 302 frequency of the CPU when tracing starts is not shown.</td> 303 </tr> 304 305 <tr> 306 <td><code>-i, --cpu-idle</code></td> 307 308 <td>Trace CPU idle events.</td> 309 </tr> 310 311 <tr> 312 <td><code>-l, --cpu-load</code></td> 313 314 <td>Trace CPU load. This value is a percentage determined by the interactive CPU frequency 315 governor.</td> 316 </tr> 317 318 <tr> 319 <td><nobr><code>-s, --no-cpu-sched</code></nobr></td> 320 321 <td>Prevent tracing of the CPU scheduler. This option allows for longer trace times by reducing 322 the rate of data flowing into the trace buffer.</td> 323 </tr> 324 325 <tr> 326 <td><nobr><code>-u, --bus-utilization</code></nobr></td> 327 328 <td>Trace the bus utilization levels. This option requires root access on the device.</td> 329 </tr> 330 331 <tr> 332 <td><code>-w, --workqueue</code></td> 333 334 <td>Trace kernel work queues. This option requires root access on the device.</td> 335 </tr> 336 337 <tr> 338 <td id="tags"><code>--set-tags=<<em>TAGS</em>></code></td> 339 340 <td>Set the enabled trace tags in a comma separated list. The available tags are: 341 <ul> 342 <li><code>gfx</code> - Graphics</li> 343 <li><code>input</code> - Input</li> 344 <li><code>view</code> - View</li> 345 <li><code>webview</code> - WebView</li> 346 <li><code>wm</code> - Window Manager</li> 347 <li><code>am</code> - Activity Manager</li> 348 <li><code>sync</code> - Synchronization Manager</li> 349 <li><code>audio</code> - Audio</li> 350 <li><code>video</code> - Video</li> 351 <li><code>camera</code> - Camera</li> 352 </ul> 353 <p class="note"><strong>Note:</strong> When setting trace tags from the command line, you 354 must stop and restart the framework ({@code $ adb shell stop; adb shell start}) for the 355 tag tracing changes to take effect.</p> 356 </td> 357 </tr> 358 359</table> 360 361<p>You can set the trace <a href="#tags">tags</a> for Systrace on 362your Android 4.2 and lower device by navigating to <strong>Settings > Developer options > 363Monitoring > Enable traces</strong>.</p> 364 365 366<h2 id="viewing-options">Trace Viewing Shortcuts</h2> 367 368<p>The table below lists the keyboard shortcuts that are available while viewing a Systrace 369trace HTML report.</p> 370 371<table> 372 <tr> 373 <th>Key</th> 374 375 <th>Description</th> 376 </tr> 377 378 <tr> 379 <td><strong>w</strong></td> 380 381 <td>Zoom into the trace timeline.</td> 382 </tr> 383 384 <tr> 385 <td><strong>s</strong></td> 386 387 <td>Zoom out of the trace timeline.</td> 388 </tr> 389 390 <tr> 391 <td><strong>a</strong></td> 392 393 <td>Pan left on the trace timeline.</td> 394 </tr> 395 396 <tr> 397 <td><strong>d</strong></td> 398 399 <td>Pan right on the trace timeline.</td> 400 </tr> 401 402 <tr> 403 <td><strong>e</strong></td> 404 405 <td>Center the trace timeline on the current mouse location.</td> 406 </tr> 407 408 <tr> 409 <td><strong>g</strong></td> 410 411 <td>Show grid at the start of the currently selected task.</td> 412 </tr> 413 414 <tr> 415 <td><strong>Shift+g</strong></td> 416 417 <td>Show grid at the end of the currently selected task.</td> 418 </tr> 419 420 <tr> 421 <td><strong>Right Arrow</strong></td> 422 423 <td>Select the next event on the currently selected timeline.</td> 424 </tr> 425 426 <tr> 427 <td><strong>Left Arrow</strong></td> 428 429 <td>Select the previous event on the currently selected timeline.</td> 430 </tr> 431 432</table> 433
