am c098ff66: am bbdfada0: Merge "docs: Systrace tool documentation" into jb-dev
* commit 'c098ff668bf9ff9abd15a2b7352e0c498fa38e3f':
docs: Systrace tool documentation
diff --git a/docs/html/images/systrace/display-rhythm.png b/docs/html/images/systrace/display-rhythm.png
new file mode 100644
index 0000000..a249161
--- /dev/null
+++ b/docs/html/images/systrace/display-rhythm.png
Binary files differ
diff --git a/docs/html/images/systrace/process-rhythm.png b/docs/html/images/systrace/process-rhythm.png
new file mode 100644
index 0000000..7498cc7
--- /dev/null
+++ b/docs/html/images/systrace/process-rhythm.png
Binary files differ
diff --git a/docs/html/images/systrace/report.png b/docs/html/images/systrace/report.png
new file mode 100644
index 0000000..a642960
--- /dev/null
+++ b/docs/html/images/systrace/report.png
Binary files differ
diff --git a/docs/html/tools/debugging/systrace.jd b/docs/html/tools/debugging/systrace.jd
new file mode 100644
index 0000000..287abe6
--- /dev/null
+++ b/docs/html/tools/debugging/systrace.jd
@@ -0,0 +1,239 @@
+page.title=Analyzing Display and Performance with Systrace
+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="#overview">Overview</a>
+ </li>
+ <li><a href="#generate">Generating Traces</a>
+ <ol>
+ <li><a href="#limit-trace">Limiting trace data</a></li>
+ <li><a href="#config-categories">Configuring trace data categories</a></li>
+ <li><a href="#running">Running a trace</a></li>
+ </ol>
+ </li>
+ <li><a href="#analysis">Analyzing Traces</a>
+ <ol>
+ <li><a href="#long-processes">Long running processes</a></li>
+ <li><a href="#display-interupts">Interruptions in display execution</a></li>
+ </ol>
+ </li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}tools/help/systrace.html">Systrace</a>
+ </li>
+ </ol>
+ </div>
+</div>
+
+<p>After building features, eliminating bugs and cleaning up your code, you should spend some
+ time looking at the performance of your application. The speed and smoothness with which your
+ application draws pixels and performs operations has an significant impact on your users'
+ experience.</p>
+
+<p>Android applications operate within a shared resource environment, and the performance of
+ your application can be impacted by how efficiently it interacts with those resources in
+ the larger system. Applications also operate in a multithreaded environment, competing with other
+ threaded processes for resources, which can cause performance problems that are hard to diagnose.
+</p>
+
+<p>The {@code systrace} tool allows you to collect and review code execution data for your
+ application and the Android system. You can use this data to diagnose execution problems and
+ improve the performance of your application.</p>
+
+
+<h2 id="overview">Overview</h2>
+
+<p>{@code systrace} helps you analyze how the execution of your application fits into the larger
+ Android environment, letting you see system and applications process execution on a common
+ timeline. The tool allows you to generate highly detailed, interactive reports from devices
+ running Android 4.1 and higher, such as the report in figure 1.</p>
+
+<img src="{@docRoot}images/systrace/report.png" alt="Systrace example report" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> An example {@code systrace} report on 5 seconds of process execution
+ for a running application and related Android system processes.
+</p>
+
+
+<h2 id="generate">Generating Traces</h2>
+
+<p>In order to create a trace of your application, you must perform a few setup steps. First, you
+ must have a device running Android 4.1 or higher. Setup the device for
+ <a href="{@docRoot}tools/device.html#setting-up">debugging</a>, connect it to your development
+ system and install your application. Some types of trace information, specifically disk activity
+ and kernel work queues, require root access to the device, but most {@code systrace} log data
+ only requires that the device be enabled for developer debugging.</p>
+
+
+<h3 id="limit-trace">Limiting trace data</h3>
+
+<p>The {@code systrace} tool can generate a potentially huge amount of data from applications
+ and system sources. To limit the amount of data the tool collects and make the data more relevant
+ to your analysis, use the following options:</p>
+
+<ul>
+ <li>Limit the amount of time covered by the trace with the {@code -t, --time} option. The default
+ length of a trace is 5 seconds.</li>
+ <li>Limit the size of the data collected by the trace with the {@code -b, --buf-size} option.</li>
+ <li>Specify what types of processes are traced using the {@code --set-tags} option and the
+ {@code --disk}, {@code --cpu-freq}, {@code --cpu-idle}, {@code --cpu-load} options.</li>
+</ul>
+
+
+<h3 id="config-categories">Configuring trace data categories</h3>
+
+<p>To use {@code systrace} effectively, you must specify the types of processes you want to trace.
+ The tool can gather the following types of process information:</p>
+
+<ul>
+ <li>General system processes such as graphics, audio and input processes (selected using trace
+ <a href="{@docRoot}tools/help/systrace.html#tags">Tags</a>).</li>
+ <li>Low level system information such as CPU, kernel and disk activity (selected using
+ <a href="{@docRoot}tools/help/systrace.html#options">Options</a>).</li>
+</ul>
+
+<p>To set trace tags for {@code systrace} using the command-line:</p>
+
+<ol>
+ <li>Use the {@code --set-tags} option:
+<pre>
+$> python systrace.py --set-tags=gfx,view,wm
+</pre>
+ </li>
+ <li>Stop and restart the {@code adb} shell to enable tracing of these processes.
+<pre>
+$> adb shell stop
+$> adb shell start
+</pre></li>
+</ol>
+
+<p>To set trace tags for {@code systrace} using the device user interface:</p>
+
+<ol>
+ <li>On the device connected for tracing, navigate to: <strong>Settings >
+ Developer options > Monitoring > Enable traces</strong>.</li>
+ <li>Select the categories of processes to be traced and click <strong>OK</strong>.</li>
+</ol>
+
+<p class="note">
+ <strong>Note:</strong> The {@code adb} shell does not have to be stopped and restarted when
+ selecting trace tags using this method.
+</p>
+
+
+<h3 id="running">Running a trace</h3>
+
+<p>After you have configured the category tags for your trace, you can start collecting
+ information for analysis.</p>
+
+<p>To run a trace using the current trace tag settings:</p>
+
+<ol>
+ <li>Make sure the device is connected through a USB cable and is
+ <a href="{@docRoot}tools/device.html#setting-up">enabled for debugging</a>.</li>
+ <li>Run the trace with the low-level system trace options and limits you want, for example:
+<pre>
+$> python systrace.py --cpu-freq --cpu-load --time=10 -o mytracefile.html
+</pre>
+ </li>
+ <li>On the device, execute any user actions you want be included in the trace.</li>
+</ol>
+
+
+<h2 id="analysis">Analyzing Traces</h2>
+
+<p>After you have generated a trace using {@code systrace}, it lists the location of the output
+ file and you can open the report using a web browser.
+ How you use the trace data depends on the performance issues you are investigating. However,
+ this section provides some general instructions on how to analyze a trace.</p>
+
+<p>The reports generated by {@code systrace} are interactive, allowing you to zoom into and out of
+ the process execution details. Use the <em>W</em> key to zoom in, the <em>S</em>
+ key to zoom out, the <em>A</em> key to pan left and the <em>D</em> key to pan
+ right. Select a task in timeline using your mouse to get more information about the task.
+ For more information about the using the keyboard navigation shortcuts and navigation, see the
+ <a href="{@docRoot}tools/help/systrace.html#viewing-options">Systrace</a> reference
+ documentation.</p>
+
+<h3 id="long-processes">Long running processes</h3>
+
+<p>A well-behaved application executes many small operations quickly and with a regular rhythm,
+ with individual operations completing within few milliseconds, depending on the device
+ and the processes being performed, as shown in figure 2:</p>
+
+<img src="{@docRoot}images/systrace/process-rhythm.png" alt="Systrace exerpt of app processing"
+id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Excerpt from a trace of a smoothly running application with a regular
+ execution rhythm.
+</p>
+
+<p>The trace excerpt in figure 2 shows a well-behaved application with
+ a regular process rhythm (1). The lower section of figure 2 shows a magnified section of
+ the trace indicated by the dotted outline, which reveals some irregularity in the process
+ execution. In particular, one of the wider task bars, indicated by (2), is taking slightly
+ longer (14 milliseconds) than other, similar tasks on this thread, which are averaging between
+ 9 and 12 milliseconds to complete. This particular task execution length is likely not noticeable
+ to a user, unless it impacts another process with specific timing, such as a screen update.</p>
+
+<p>Long running processes show up as thicker than usual execution bars in a trace. These thicker
+ bars can indicate a problem in your application performance. When they show up in your
+ trace, zoom in on the process using the
+ <a href="{@docRoot}tools/help/systrace.html#viewing-options">keyboard navigation</a> shortcuts to
+ identify the task causing the problem, and click on the task to get more information. You should
+ also look at other processes running at the same time, looking for a thread in one process that is
+ being blocked by another process.</p>
+
+
+<h3 id="display-interupts">Interruptions in display execution</h3>
+
+<p>The {@code systrace} tool is particularly useful in analyzing application display slowness,
+ or pauses in animations, because it shows you the execution of your application across multiple
+ system processes. With display execution, drawing screen frames with a regular rhythm is essential
+ for good performance. Having a regular rhythm for display ensures that animations and motion are
+ smooth on screen. If an application drops out of this rhythm, the display can become jerky or slow
+ from the users perspective.</p>
+
+<p>If you are analyzing an application for this type of problem, examine the
+ <strong>SurfaceFlinger</strong> process in the {@code systrace} report where your application is
+ also executing to look for places where it drops out of its regular rhythm.</p>
+
+<img src="{@docRoot}images/systrace/display-rhythm.png" alt="Systrace exerpt of display processing"
+id="figure3" />
+<p class="img-caption">
+ <strong>Figure 3.</strong> Excerpt from a trace of an application showing interruptions in
+ display processing.
+</p>
+
+<p>The trace excerpt in figure 3 shows an section of a trace that indicates an interruption in the
+ device display. The section of the <strong>SurfaceFlinger</strong> process in top excerpt,
+ indicated by (1), shows that display frames are being missed. These
+ dropped frames are potentially causing the display to stutter or halt. Zooming into this problem
+ area in the lower trace, shows that a memory operation (image buffer dequeuing and allocation) in
+ the <strong>surfaceflinger</strong> secondary thread is taking a long time (2). This delay
+ causes the application to miss the display update window, indicated by the dotted
+ line. As the developer of this application, you should investigate other threads in your
+ application that may also be trying to allocate memory at the same time or otherwise blocking
+ memory allocation with another request or task.</p>
+
+<p>Regular, rhythmic execution of the <strong>SurfaceFlinger</strong> process is essential to smooth
+ display of screen content, particularly for animations and motion. Interruptions in the regular
+ execution pattern of this thread is not always an indication of a display problem with your
+ application. Further testing is required to determine if this is actually a performance problem
+ from a user perspective. Being able to identify display execution patterns like the example above
+ can help you detect display problems and build a smooth-running, high-performance application.
+</p>
+
+<p class="note">
+ <strong>Note:</strong> When using {@code systrace} to analyze display problems, make sure
+ you activate the tracing tags for <strong>Graphics</strong> and <strong>Views</strong>.
+</p>
+
+<p>For more information on the command line options and keyboard controls for {@code systrace},
+see the <a href="{@docRoot}tools/help/systrace.html">Systrace</a> reference page.</p>
\ No newline at end of file
diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd
index 447d39c..0f94395 100644
--- a/docs/html/tools/help/index.jd
+++ b/docs/html/tools/help/index.jd
@@ -55,6 +55,9 @@
<dt><a href="proguard.html">ProGuard</a></dt>
<dd>Shrinks, optimizes, and obfuscates your code by removing unused code and renaming
classes, fields, and methods with semantically obscure names.</dd>
+ <dt><a href="systrace.html">Systrace</a></dt>
+ <dd>Lets you analyze the execution of your application in the context of system processes,
+ to help diagnose display and performance issues.</dd>
<dt><a href="sqlite3.html">sqlite3</a></dt>
<dd>Lets you access the SQLite data files created and used by Android applications.</dd>
<dt><a href="traceview.html">traceview</a></dt>
diff --git a/docs/html/tools/help/systrace.jd b/docs/html/tools/help/systrace.jd
new file mode 100644
index 0000000..010cc78
--- /dev/null
+++ b/docs/html/tools/help/systrace.jd
@@ -0,0 +1,234 @@
+page.title=Systrace
+parent.title=Tools
+parent.link=index.html
+@jd:body
+
+
+<p>The {@code systrace} tool helps analyze the performance of your application by capturing and
+ displaying execution times of your applications processes and other Android system processes. The
+ tool combines data from the Android kernel such as the CPU scheduler, disk activity and
+ application threads to generate an HTML report that shows an overall picture of an Android
+ device’s system processes for a given period of time.</p>
+
+<p>The {@code systrace} tool is particularly useful in diagnosing display problems where an
+ application is slow to draw or stutters while displaying motion or animation. For more information
+ on how to use {@code systrace}, see <a href="{@docRoot}tools/debugging/systrace.html">Analyzing
+ Display and Performance with Systrace</a>.</p>
+
+
+<h2 id="usage">Usage</h2>
+
+<p>In order to run {@code systrace}, the {@code adb} tool and
+<a href="http://www.python.org/">Python</a> must be installed and included in your development
+computer's execution path. In order to generate a trace, you must connect a device running Android
+4.1 (API Level 16) or higher to your development system using a USB debugging connection.</p>
+
+<p>The syntax for running {@code systrace} is as follows.</p>
+
+<pre>
+$> python systrace.py [options]
+</pre>
+
+<p>Here is an example execution run that sets trace tags and generates a trace from a connected
+Android device.</p>
+
+<pre>
+$> cd <em>android-sdk</em>/tools/systrace
+$> python systrace.py --set-tags gfx,view,wm
+$> adb shell stop
+$> adb shell start
+$> python systrace.py --disk --time=10 -o mynewtrace.html
+</pre>
+
+
+
+<h2 id="options">Options</h2>
+
+<p>The table below lists the command line options for {@code systrace}.</p>
+
+<table>
+ <tr>
+ <th>Option</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>-o <<em>FILE</em>></code></td>
+
+ <td>Write the HTML trace report to the specified file.</td>
+ </tr>
+
+ <tr>
+ <td><code>-t N, --time=N</code></td>
+
+ <td>Trace activity for N seconds. Default value is 5 seconds.</td>
+ </tr>
+
+ <tr>
+ <td><code>-b N, --buf-size=N</code></td>
+
+ <td>Use a trace buffer size of N kilobytes. This option lets you limit the total size of the
+ data collected during a trace.</td>
+ </tr>
+
+ <tr>
+ <td><code>-d, --disk</code></td>
+
+ <td>Trace disk input and output activity. This option requires root access on the device.</td>
+ </tr>
+
+ <tr>
+ <td><code>-f, --cpu-freq</code></td>
+
+ <td>Trace CPU frequency changes. Only changes to the CPU frequency are logged, so the initial
+ frequency of the CPU when tracing starts is not shown.</td>
+ </tr>
+
+ <tr>
+ <td><code>-i, --cpu-idle</code></td>
+
+ <td>Trace CPU idle events.</td>
+ </tr>
+
+ <tr>
+ <td><code>-l, --cpu-load</code></td>
+
+ <td>Trace CPU load. This value is a percentage determined by the interactive CPU frequency
+ governor.</td>
+ </tr>
+
+ <tr>
+ <td><nobr><code>-s, --no-cpu-sched</code></nobr></td>
+
+ <td>Prevent tracing of the CPU scheduler. This option allows for longer trace times by reducing
+ the rate of data flowing into the trace buffer.</td>
+ </tr>
+
+ <tr>
+ <td><code>-w, --workqueue</code></td>
+
+ <td>Trace kernel work queues. This option requires root access on the device.</td>
+ </tr>
+
+ <tr>
+ <td id="tags"><code>--set-tags=<<em>TAGS</em>></code></td>
+
+ <td>Set the enabled trace tags in a comma separated list. The available tags are:
+ <ul>
+ <li><code>gfx</code> - Graphics</li>
+ <li><code>input</code> - Input</li>
+ <li><code>view</code> - View</li>
+ <li><code>webview</code> - WebView</li>
+ <li><code>wm</code> - Window Manager</li>
+ <li><code>am</code> - Activity Manager</li>
+ <li><code>sync</code> - Sync Manager</li>
+ <li><code>audio</code> - Audio</li>
+ <li><code>video</code> - Video</li>
+ <li><code>camera</code> - Camera</li>
+ </ul>
+ <p class="note"><strong>Note:</strong> When setting trace tags from the command line, you
+ must stop and restart the framework ({@code $> adb shell stop; adb shell start}) for the
+ tag tracing changes to take effect.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>--link-assets</code></td>
+
+ <td>Link to the original CSS or JS resources instead of embedding them in the HTML trace
+ report.</td>
+ </tr>
+
+ <tr>
+ <td><nobr><code>-h, --help</code></nobr></td>
+
+ <td>Show the help message.</td>
+ </tr>
+
+</table>
+
+<p>You can set the trace <a href="#tags">tags</a> for {@code systrace} with your device's user
+interface, by navigating to <strong>Settings > Developer options > Monitoring > Enable
+traces</strong>.</p>
+
+
+<h2 id="viewing-options">Trace Viewing Shortcuts</h2>
+
+<p>The table below lists the keyboard shortcuts that are available while viewing a {@code systrace}
+trace HTML report.</p>
+
+<table>
+ <tr>
+ <th>Key</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><strong>w</strong></td>
+
+ <td>Zoom into the trace timeline.</td>
+ </tr>
+
+ <tr>
+ <td><strong>s</strong></td>
+
+ <td>Zoom out of the trace timeline.</td>
+ </tr>
+
+ <tr>
+ <td><strong>a</strong></td>
+
+ <td>Pan left on the trace timeline.</td>
+ </tr>
+
+ <tr>
+ <td><strong>d</strong></td>
+
+ <td>Pan right on the trace timeline.</td>
+ </tr>
+
+ <tr>
+ <td><strong>e</strong></td>
+
+ <td>Center the trace timeline on the current mouse location.</td>
+ </tr>
+
+ <tr>
+ <td><strong>g</strong></td>
+
+ <td>Show grid at the start of the currently selected task.</td>
+ </tr>
+
+ <tr>
+ <td><strong>Shift+g</strong></td>
+
+ <td>Show grid at the end of the currently selected task.</td>
+ </tr>
+
+ <tr>
+ <td><strong>Right Arrow</strong></td>
+
+ <td>Select the next event on the currently selected timeline.</td>
+ </tr>
+
+ <tr>
+ <td><strong>Left Arrow</strong></td>
+
+ <td>Select the previous event on the currently selected timeline.</td>
+ </tr>
+
+ <tr>
+ <td><strong>Double Click</strong></td>
+
+ <td>Zoom into the trace timeline.</td>
+ </tr>
+
+ <tr>
+ <td><strong>Shift+Double Click</strong></td>
+
+ <td>Zoom out of the trace timeline.</td>
+ </tr>
+
+</table>
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs
index f3936b8..5e2b9f7 100644
--- a/docs/html/tools/tools_toc.cs
+++ b/docs/html/tools/tools_toc.cs
@@ -114,6 +114,7 @@
<li><a href="<?cs var:toroot ?>tools/debugging/improving-w-lint.html"><span class="en">Improving Your Code with lint</span></a></li>
<li><a href="<?cs var:toroot ?>tools/debugging/debugging-ui.html"><span class="en">Optimizing your UI</span></a></li>
<li><a href="<?cs var:toroot ?>tools/debugging/debugging-tracing.html"><span class="en">Profiling with Traceview and dmtracedump</span></a></li>
+ <li><a href="<?cs var:toroot ?>tools/debugging/systrace.html"><span class="en">Analysing Display and Performance with Systrace</span></a></li>
<li><a href="<?cs var:toroot ?>tools/debugging/debugging-devtools.html"><span class="en">Using the Dev Tools App</span></a></li>
</ul>
</li>
@@ -159,6 +160,7 @@
</ul>
</li>
<li><a href="<?cs var:toroot ?>tools/help/proguard.html">ProGuard</a></li>
+ <li><a href="<?cs var:toroot ?>tools/help/systrace.html">Systrace</a></li>
<li><a href="<?cs var:toroot ?>tools/help/gltracer.html">Tracer for OpenGL ES</a></li>
<li><a href="<?cs var:toroot ?>tools/help/traceview.html">Traceview</a></li>
<li><a href="<?cs var:toroot ?>tools/help/zipalign.html">zipalign</a></li>
