1page.title=Analyzing Display and Performance with Systrace 2parent.title=Debugging 3parent.link=index.html 4@jd:body 5 6<div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li><a href="#overview">Overview</a> 11 </li> 12 <li><a href="#generate">Generating Traces</a> 13 <ol> 14 <li><a href="#limit-trace">Limiting trace data</a></li> 15 <li><a href="#config-categories">Configuring trace data categories</a></li> 16 <li><a href="#running">Running a trace</a></li> 17 </ol> 18 </li> 19 <li><a href="#analysis">Analyzing Traces</a> 20 <ol> 21 <li><a href="#long-processes">Long running processes</a></li> 22 <li><a href="#display-interupts">Interruptions in display execution</a></li> 23 </ol> 24 </li> 25 </ol> 26 <h2>See also</h2> 27 <ol> 28 <li><a href="{@docRoot}tools/help/systrace.html">Systrace</a> 29 </li> 30 </ol> 31 </div> 32</div> 33 34<p>After building features, eliminating bugs and cleaning up your code, you should spend some 35 time looking at the performance of your application. The speed and smoothness with which your 36 application draws pixels and performs operations has an significant impact on your users' 37 experience.</p> 38 39<p>Android applications operate within a shared resource environment, and the performance of 40 your application can be impacted by how efficiently it interacts with those resources in 41 the larger system. Applications also operate in a multithreaded environment, competing with other 42 threaded processes for resources, which can cause performance problems that are hard to diagnose. 43</p> 44 45<p>The {@code systrace} tool allows you to collect and review code execution data for your 46 application and the Android system. You can use this data to diagnose execution problems and 47 improve the performance of your application.</p> 48 49 50<h2 id="overview">Overview</h2> 51 52<p>{@code systrace} helps you analyze how the execution of your application fits into the larger 53 Android environment, letting you see system and applications process execution on a common 54 timeline. The tool allows you to generate highly detailed, interactive reports from devices 55 running Android 4.1 and higher, such as the report in figure 1.</p> 56 57<img src="{@docRoot}images/systrace/report.png" alt="Systrace example report" id="figure1" /> 58<p class="img-caption"> 59 <strong>Figure 1.</strong> An example {@code systrace} report on 5 seconds of process execution 60 for a running application and related Android system processes. 61</p> 62 63 64<h2 id="generate">Generating Traces</h2> 65 66<p>In order to create a trace of your application, you must perform a few setup steps. First, you 67 must have a device running Android 4.1 or higher. Setup the device for 68 <a href="{@docRoot}tools/device.html#setting-up">debugging</a>, connect it to your development 69 system and install your application. Some types of trace information, specifically disk activity 70 and kernel work queues, require root access to the device, but most {@code systrace} log data 71 only requires that the device be enabled for developer debugging.</p> 72 73 74<h3 id="limit-trace">Limiting trace data</h3> 75 76<p>The {@code systrace} tool can generate a potentially huge amount of data from applications 77 and system sources. To limit the amount of data the tool collects and make the data more relevant 78 to your analysis, use the following options:</p> 79 80<ul> 81 <li>Limit the amount of time covered by the trace with the {@code -t, --time} option. The default 82 length of a trace is 5 seconds.</li> 83 <li>Limit the size of the data collected by the trace with the {@code -b, --buf-size} option.</li> 84 <li>Specify what types of processes are traced using the {@code --set-tags} option and the 85 {@code --disk}, {@code --cpu-freq}, {@code --cpu-idle}, {@code --cpu-load} options.</li> 86</ul> 87 88 89<h3 id="config-categories">Configuring trace data categories</h3> 90 91<p>To use {@code systrace} effectively, you must specify the types of processes you want to trace. 92 The tool can gather the following types of process information:</p> 93 94<ul> 95 <li>General system processes such as graphics, audio and input processes (selected using trace 96 <a href="{@docRoot}tools/help/systrace.html#tags">Tags</a>).</li> 97 <li>Low level system information such as CPU, kernel and disk activity (selected using 98 <a href="{@docRoot}tools/help/systrace.html#options">Options</a>).</li> 99</ul> 100 101<p>To set trace tags for {@code systrace} using the command-line:</p> 102 103<ol> 104 <li>Use the {@code --set-tags} option: 105<pre> 106$> python systrace.py --set-tags=gfx,view,wm 107</pre> 108 </li> 109 <li>Stop and restart the {@code adb} shell to enable tracing of these processes. 110<pre> 111$> adb shell stop 112$> adb shell start 113</pre></li> 114</ol> 115 116<p>To set trace tags for {@code systrace} using the device user interface:</p> 117 118<ol> 119 <li>On the device connected for tracing, navigate to: <strong>Settings > 120 Developer options > Monitoring > Enable traces</strong>.</li> 121 <li>Select the categories of processes to be traced and click <strong>OK</strong>.</li> 122</ol> 123 124<p class="note"> 125 <strong>Note:</strong> The {@code adb} shell does not have to be stopped and restarted when 126 selecting trace tags using this method. 127</p> 128 129 130<h3 id="running">Running a trace</h3> 131 132<p>After you have configured the category tags for your trace, you can start collecting 133 information for analysis.</p> 134 135<p>To run a trace using the current trace tag settings:</p> 136 137<ol> 138 <li>Make sure the device is connected through a USB cable and is 139 <a href="{@docRoot}tools/device.html#setting-up">enabled for debugging</a>.</li> 140 <li>Run the trace with the low-level system trace options and limits you want, for example: 141<pre> 142$> python systrace.py --cpu-freq --cpu-load --time=10 -o mytracefile.html 143</pre> 144 </li> 145 <li>On the device, execute any user actions you want be included in the trace.</li> 146</ol> 147 148 149<h2 id="analysis">Analyzing Traces</h2> 150 151<p>After you have generated a trace using {@code systrace}, it lists the location of the output 152 file and you can open the report using a web browser. 153 How you use the trace data depends on the performance issues you are investigating. However, 154 this section provides some general instructions on how to analyze a trace.</p> 155 156<p>The reports generated by {@code systrace} are interactive, allowing you to zoom into and out of 157 the process execution details. Use the <em>W</em> key to zoom in, the <em>S</em> 158 key to zoom out, the <em>A</em> key to pan left and the <em>D</em> key to pan 159 right. Select a task in timeline using your mouse to get more information about the task. 160 For more information about the using the keyboard navigation shortcuts and navigation, see the 161 <a href="{@docRoot}tools/help/systrace.html#viewing-options">Systrace</a> reference 162 documentation.</p> 163 164<h3 id="long-processes">Long running processes</h3> 165 166<p>A well-behaved application executes many small operations quickly and with a regular rhythm, 167 with individual operations completing within few milliseconds, depending on the device 168 and the processes being performed, as shown in figure 2:</p> 169 170<img src="{@docRoot}images/systrace/process-rhythm.png" alt="Systrace exerpt of app processing" 171id="figure2" /> 172<p class="img-caption"> 173 <strong>Figure 2.</strong> Excerpt from a trace of a smoothly running application with a regular 174 execution rhythm. 175</p> 176 177<p>The trace excerpt in figure 2 shows a well-behaved application with 178 a regular process rhythm (1). The lower section of figure 2 shows a magnified section of 179 the trace indicated by the dotted outline, which reveals some irregularity in the process 180 execution. In particular, one of the wider task bars, indicated by (2), is taking slightly 181 longer (14 milliseconds) than other, similar tasks on this thread, which are averaging between 182 9 and 12 milliseconds to complete. This particular task execution length is likely not noticeable 183 to a user, unless it impacts another process with specific timing, such as a screen update.</p> 184 185<p>Long running processes show up as thicker than usual execution bars in a trace. These thicker 186 bars can indicate a problem in your application performance. When they show up in your 187 trace, zoom in on the process using the 188 <a href="{@docRoot}tools/help/systrace.html#viewing-options">keyboard navigation</a> shortcuts to 189 identify the task causing the problem, and click on the task to get more information. You should 190 also look at other processes running at the same time, looking for a thread in one process that is 191 being blocked by another process.</p> 192 193 194<h3 id="display-interupts">Interruptions in display execution</h3> 195 196<p>The {@code systrace} tool is particularly useful in analyzing application display slowness, 197 or pauses in animations, because it shows you the execution of your application across multiple 198 system processes. With display execution, drawing screen frames with a regular rhythm is essential 199 for good performance. Having a regular rhythm for display ensures that animations and motion are 200 smooth on screen. If an application drops out of this rhythm, the display can become jerky or slow 201 from the users perspective.</p> 202 203<p>If you are analyzing an application for this type of problem, examine the 204 <strong>SurfaceFlinger</strong> process in the {@code systrace} report where your application is 205 also executing to look for places where it drops out of its regular rhythm.</p> 206 207<img src="{@docRoot}images/systrace/display-rhythm.png" alt="Systrace exerpt of display processing" 208id="figure3" /> 209<p class="img-caption"> 210 <strong>Figure 3.</strong> Excerpt from a trace of an application showing interruptions in 211 display processing. 212</p> 213 214<p>The trace excerpt in figure 3 shows an section of a trace that indicates an interruption in the 215 device display. The section of the <strong>SurfaceFlinger</strong> process in top excerpt, 216 indicated by (1), shows that display frames are being missed. These 217 dropped frames are potentially causing the display to stutter or halt. Zooming into this problem 218 area in the lower trace, shows that a memory operation (image buffer dequeuing and allocation) in 219 the <strong>surfaceflinger</strong> secondary thread is taking a long time (2). This delay 220 causes the application to miss the display update window, indicated by the dotted 221 line. As the developer of this application, you should investigate other threads in your 222 application that may also be trying to allocate memory at the same time or otherwise blocking 223 memory allocation with another request or task.</p> 224 225<p>Regular, rhythmic execution of the <strong>SurfaceFlinger</strong> process is essential to smooth 226 display of screen content, particularly for animations and motion. Interruptions in the regular 227 execution pattern of this thread is not always an indication of a display problem with your 228 application. Further testing is required to determine if this is actually a performance problem 229 from a user perspective. Being able to identify display execution patterns like the example above 230 can help you detect display problems and build a smooth-running, high-performance application. 231</p> 232 233<p class="note"> 234 <strong>Note:</strong> When using {@code systrace} to analyze display problems, make sure 235 you activate the tracing tags for <strong>Graphics</strong> and <strong>Views</strong>. 236</p> 237 238<p>For more information on the command line options and keyboard controls for {@code systrace}, 239see the <a href="{@docRoot}tools/help/systrace.html">Systrace</a> reference page.</p>
