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