Home | History | Annotate | Download | only in help
      1 page.title=Systrace
      2 parent.title=Tools
      3 parent.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   devices 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
     23 have <a href="http://www.python.org/">Python</a> installed and included in your development
     24 computer's execution path. In order to generate a trace, you must connect a device running Android
     25 4.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
     29 tools, or from the command line. The following sections describe how to run the tool using either
     30 of 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>,
     38 or 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 &gt; Perspectives &gt;
     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 &gt; Android &gt; 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
    106 level 18) and higher versus devices running Android 4.2 (API level 17) and lower. The following
    107 sections 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
    121 trace category tag. Here is an example execution run that sets trace tags and generates a trace
    122 from 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&nbsp;&lt;<em>FILE</em>&gt;</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&nbsp;&lt;<em>KFUNCS</em>&gt;<br>
    171         --ktrace=&lt;<em>KFUNCS</em>&gt;</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&nbsp;&lt;<em>APP_NAME</em>&gt;<br>
    216         --app=&lt;<em>APP_NAME</em>&gt;</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=&lt;<em>FROM_FILE</em>&gt;</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=&lt;<em>ASSET_DIR</em>&gt;</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 &lt;<em>DEVICE_SERIAL</em>&gt;<br>
    251     --serial=&lt;<em>DEVICE_SERIAL</em>&gt;</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
    263 two-step process. You must first set the trace tags you want to capture and then run the trace.
    264 Here is an example execution run that sets trace tags and generates a trace from a connected
    265 device.</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&nbsp;&lt;<em>FILE</em>&gt;</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,&nbsp;--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=&lt;<em>TAGS</em>&gt;</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
    387 your Android 4.2 and lower device by navigating to <strong>Settings &gt; Developer options &gt;
    388 Monitoring &gt; 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
    394 trace 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