| page.title=Profiling with Traceview and dmtracedump |
| parent.title=Debugging |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| |
| <ol> |
| <li> |
| <a href="#traceviewLayout">Traceview Layout</a> |
| |
| <ol> |
| <li><a href="#timelinepanel">Timeline Panel</a></li> |
| |
| <li><a href="#profilepanel">Profile Panel</a></li> |
| </ol> |
| </li> |
| |
| <li><a href="#creatingtracefiles">Creating Trace Files</a></li> |
| |
| <li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li> |
| |
| <li><a href="#runningtraceview">Viewing Trace Files in Traceview</a></li> |
| |
| <li><a href="#dmtracedump">Using dmtracedump</a></li> |
| |
| <li><a href="#knownissues">Traceview Known Issues</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>Traceview is a graphical viewer for execution logs that you create by using the {@link |
| android.os.Debug} class to log tracing information in your code. Traceview can help you debug |
| your application and profile its performance.</p> |
| |
| <h2 id="traceviewLayout">Traceview Layout</h2> |
| |
| <p>When you have a trace log file (generated by adding tracing code to your application or by DDMS), |
| you can have Traceview load the log files and display their data in a window visualizes your application |
| in two panels:</p> |
| |
| <ul> |
| <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread and method |
| started and stopped</li> |
| |
| <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside |
| a method</li> |
| </ul> |
| |
| <p>The sections below provide addition information about the traceview output panes.</p> |
| |
| <h3 id="timelinepanel">Timeline Panel</h3> |
| |
| <p>The image below shows a close up of the timeline panel. Each thread’s execution is shown |
| in its own row, with time increasing to the right. Each method is shown in another color (colors |
| are reused in a round-robin fashion starting with the methods that have the most inclusive time). |
| The thin lines underneath the first row show the extent (entry to exit) of all the calls to the |
| selected method. The method in this case is <code>LoadListener.nativeFinished()</code> and it was selected in |
| the profile view.</p> |
| |
| <img src="{@docRoot}images/traceview_timeline.png" |
| alt="Traceview timeline panel" |
| width="893" |
| height="284" /> |
| <p class="img-caption"><strong>Figure 1.</strong> The Traceview Timeline Panel</p> |
| |
| <h3 id="profilepanel">Profile Panel</h3> |
| |
| <p>Figure 2 shows the profile pane, a summary of all the time spent |
| in a method. The table shows both the inclusive and exclusive times (as well as the percentage of |
| the total time). Exclusive time is the time spent in the method. Inclusive time is the time spent |
| in the method plus the time spent in any called functions. We refer to calling methods as |
| "parents" and called methods as "children." When a method is selected (by clicking on it), it |
| expands to show the parents and children. Parents are shown with a purple background and children |
| with a yellow background. The last column in the table shows the number of calls to this method |
| plus the number of recursive calls. The last column shows the number of calls out of the total |
| number of calls made to that method. In this view, we can see that there were 14 calls to |
| <code>LoadListener.nativeFinished();</code> looking at the timeline panel shows that one of those calls took |
| an unusually long time.</p> |
| |
| <img src="{@docRoot}images/traceview_profile.png" |
| alt="Traceview profile panel." |
| width="892" |
| height="630" /> |
| <p class="img-caption"><strong>Figure 2.</strong> The Traceview Profile Panel</p> |
| |
| <h2 id="creatingtracefiles">Creating Trace Files</h2> |
| |
| <p>To use Traceview, you need to generate log files containing the trace information you want to |
| analyze.</p> |
| |
| <p>There are two ways to generate trace logs:</p> |
| <ul> |
| <li>Include the {@link android.os.Debug} class in your code and call its |
| methods to start and stop logging of trace information to disk. This method is very precise because |
| you can specify in your code exactly where to start and stop logging trace data.</li> |
| <li>Use the method profiling feature of DDMS to generate trace logs. This method is less |
| precise since you do not modify code, but rather specify when to start and stop logging with |
| a DDMS. Although you have less control on exactly where the data is logged, this method is useful |
| if you don't have access to the application's code, or if you do not need the precision of the first method. |
| </li> |
| </ul> |
| |
| <p>Before you start generating trace logs, be aware of the following restrictions:</p> |
| <ul> |
| <li>If you are using the {@link android.os.Debug} class, your device or emulator must have an SD card |
| and your application must have permission to write to the SD card. </li> |
| <li>If you are using DDMS, Android 1.5 devices are not supported.</li> |
| <li>If you are using DDMS, Android 2.1 and earlier devices must |
| have an SD card present and your application must have permission to write to the SD card. |
| <li>If you are using DDMS, Android 2.2 and later devices do not need an SD card. The trace log files are |
| streamed directly to your development machine.</li> |
| </ul> |
| |
| <p>This document focuses on using the {@link android.os.Debug} class to generate trace data. For more information on using DDMS |
| to generate trace data, see <a href="ddms.html#profiling">Using the Dalvik Debug Monitor Server.</a> |
| </p> |
| |
| <p>To create the trace files, include the {@link android.os.Debug} class and call one of the |
| {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. In the call, you |
| specify a base name for the trace files that the system generates. To stop tracing, call {@link |
| android.os.Debug#stopMethodTracing() stopMethodTracing()}. These methods start and stop method |
| tracing across the entire virtual machine. For example, you could call |
| {@link android.os.Debug#startMethodTracing() startMethodTracing()} in |
| your activity's {@link android.app.Activity#onCreate onCreate()} method, and call |
| {@link android.os.Debug#stopMethodTracing() stopMethodTracing()} in that activity's |
| {@link android.app.Activity#onDestroy()} method.</p> |
| <pre> |
| // start tracing to "/sdcard/calc.trace" |
| Debug.startMethodTracing("calc"); |
| // ... |
| // stop tracing |
| Debug.stopMethodTracing(); |
| </pre> |
| |
| <p>When your application calls startMethodTracing(), the system creates a file called |
| <code><trace-base-name>.trace</code>. This contains the binary method trace data and a |
| mapping table with thread and method names.</p> |
| |
| <p>The system then begins buffering the generated trace data, until your application calls |
| stopMethodTracing(), at which time it writes the buffered data to the output file. If the system |
| reaches the maximum buffer size before stopMethodTracing() is called, the system stops tracing |
| and sends a notification to the console.</p> |
| |
| <p>Interpreted code will run more slowly when profiling is enabled. Don't try to generate |
| absolute timings from the profiler results (i.e. "function X takes 2.5 seconds to run"). The |
| times are only useful in relation to other profile output, so you can see if changes have made |
| the code faster or slower.</p> |
| |
| <p>When using the Android emulator, you must specify an SD card when you create your AVD because the trace files |
| are written to the SD card. Your application must have permission to write to the SD card as well. |
| |
| <h2 id="copyingfiles">Copying Trace Files to a Host Machine</h2> |
| |
| <p>After your application has run and the system has created your trace files |
| <code><trace-base-name>.trace</code> on a device or emulator, you must copy those files to |
| your development computer. You can use <code>adb pull</code> to copy the files. Here's an example |
| that shows how to copy an example file, calc.trace, from the default location on the emulator to |
| the /tmp directory on the emulator host machine:</p> |
| <pre> |
| adb pull /sdcard/calc.trace /tmp |
| </pre> |
| |
| <h2 id="runningtraceview">Viewing Trace Files in Traceview</h2> |
| |
| <p>To run Traceview and view the trace files, enter <code>traceview |
| <trace-base-name></code>. For example, to run Traceview on the example files copied in the |
| previous section, use:</p> |
| <pre> |
| traceview /tmp/calc |
| </pre> |
| |
| <p class="note"><strong>Note:</strong> If you are trying to view the trace logs of an application |
| that is built with ProGuard enabled (release mode build), some method and member names might be obfuscated. |
| You can use the Proguard <code>mapping.txt</code> file to figure out the original unobfuscated names. For more information |
| on this file, see the <a href="{@docRoot}tools/help/proguard.html">Proguard</a> documentation.</p> |
| |
| <h2 id="dmtracedump">Using dmtracedump</h2> |
| |
| <p><code>dmtracedump</code> is a tool that gives you an alternate way of generating |
| graphical call-stack diagrams from trace log files. The tool uses the Graphviz Dot utility to |
| create the graphical output, so you need to install Graphviz before running dmtracedump.</p> |
| |
| <p>The dmtracedump tool generates the call stack data as a tree diagram, with each call |
| represented as a node. It shows call flow (from parent node to child nodes) using arrows. The |
| diagram below shows an example of dmtracedump output.</p> |
| <img src= |
| "{@docRoot}images/tracedump.png" |
| width="485" |
| height="401" /> |
| <p class="image-caption"><strong>Figure 3.</strong> Screenshot of dmtracedump</p> |
| |
| <p>For each node, dmtracedump shows <code><ref> |
| <em>callname</em> (<inc-ms>, <exc-ms>,<numcalls>)</code>, where</p> |
| |
| <ul> |
| <li><code><ref></code> -- Call reference number, as used in trace logs</li> |
| |
| <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, |
| including all child methods)</li> |
| |
| <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, |
| not including any child methods)</li> |
| |
| <li><code><numcalls></code> -- Number of calls</li> |
| </ul> |
| |
| <p>The usage for dmtracedump is:</p> |
| <pre> |
| dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name> |
| </pre> |
| |
| <p>The tool then loads trace log data from <code><trace-base-name>.data</code> and |
| <code><trace-base-name>.key</code>. The table below lists the options for dmtracedump.</p> |
| |
| <table> |
| <tr> |
| <th>Option</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr> |
| <td><code>-d <trace-base-name></code></td> |
| |
| <td>Diff with this trace name</td> |
| </tr> |
| |
| <tr> |
| <td><code>-g <outfile></code></td> |
| |
| <td>Generate output to <outfile></td> |
| </tr> |
| |
| <tr> |
| <td><code>-h</code></td> |
| |
| <td>Turn on HTML output</td> |
| </tr> |
| |
| <tr> |
| <td><code>-o</code></td> |
| |
| <td>Dump the trace file instead of profiling</td> |
| </tr> |
| |
| <tr> |
| <td><code>-d <trace-base-name></code></td> |
| |
| <td>URL base to the location of the sortable javascript file</td> |
| </tr> |
| |
| <tr> |
| <td><code>-t <percent></code></td> |
| |
| <td>Minimum threshold for including child nodes in the graph (child's inclusive time as a |
| percentage of parent inclusive time). If this option is not used, the default threshold |
| is 20%.</td> |
| </tr> |
| </table> |
| |
| |
| |
| <h2 id="knownissues">Traceview Known Issues</h2> |
| |
| <dl> |
| <dt>Threads</dt> |
| |
| <dd> |
| Traceview logging does not handle threads well, resulting in these two problems: |
| |
| <ol> |
| <li>If a thread exits during profiling, the thread name is not emitted;</li> |
| |
| <li>The VM reuses thread IDs. If a thread stops and another starts, they may get the same |
| ID.</li> |
| </ol> |
| </dd> |
| |
| </dl> |