Merge "Doc change: Update Play for Edu docs for full launch." into klp-docs
diff --git a/core/java/android/os/Trace.java b/core/java/android/os/Trace.java
index bb3d296..3249bcb 100644
--- a/core/java/android/os/Trace.java
+++ b/core/java/android/os/Trace.java
@@ -22,9 +22,12 @@
* Writes trace events to the system trace buffer. These trace events can be
* collected and visualized using the Systrace tool.
*
- * This tracing mechanism is independent of the method tracing mechanism
+ * <p>This tracing mechanism is independent of the method tracing mechanism
* offered by {@link Debug#startMethodTracing}. In particular, it enables
* tracing of events that occur across multiple processes.
+ * <p>For information about using the Systrace tool, read <a
+ * href="{@docRoot}tools/debugging/systrace.html">Analyzing Display and Performance
+ * with Systrace</a>.
*/
public final class Trace {
/*
diff --git a/docs/html/tools/debugging/debugging-tracing.jd b/docs/html/tools/debugging/debugging-tracing.jd
index 8653da6..bd4afbc 100644
--- a/docs/html/tools/debugging/debugging-tracing.jd
+++ b/docs/html/tools/debugging/debugging-tracing.jd
@@ -38,8 +38,7 @@
<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>
+ you can load the log files in Traceview, which displays the log data in two panels:</p>
<ul>
<li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread and method
@@ -53,12 +52,11 @@
<h3 id="timelinepanel">Timeline Panel</h3>
- <p>The image below shows a close up of the timeline panel. Each thread’s execution is shown
+ <p>Figure 1 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>
+ selected method.</p>
<img src="{@docRoot}images/traceview_timeline.png"
alt="Traceview timeline panel"
@@ -94,23 +92,31 @@
<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.
+ methods such as {@link android.os.Debug#startMethodTracing()} and {@link
+ android.os.Debug#stopMethodTracing()}, to start and stop logging of trace information to disk.
+ This option is very precise because
+ you can specify exactly where to start and stop logging trace data in your code.</li>
+ <li>Use the method profiling feature of DDMS to generate trace logs. This option is less
+ precise because you do not modify code, but rather specify when to start and stop logging with
+ DDMS. Although you have less control on exactly where logging starts and stops,
+ this option is useful if you don't have access to the application's code, or if you do
+ not need precise log timing.
</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 2.1 and earlier devices must
+ <li>If you are using the {@link android.os.Debug} class,
+ your application must have permission to write to external storage
+ ({@link android.Manifest.permission#READ_EXTERNAL_STORAGE}). </li>
+ <li>If you are using DDMS:
+ <ul>
+ <li>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
+ <li>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>
+ </li>
</ul>
<p>This document focuses on using the {@link android.os.Debug} class to generate trace data. For more information on using DDMS
@@ -134,22 +140,22 @@
Debug.stopMethodTracing();
</pre>
- <p>When your application calls startMethodTracing(), the system creates a file called
+ <p>When your application calls {@link android.os.Debug#startMethodTracing() 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
+ {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}, at which time it writes
+ the buffered data to the output file. If the system
+ reaches the maximum buffer size before you call {@link android.os.Debug#stopMethodTracing()
+ stopMethodTracing()}, 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
+ <p>Interpreted code runs more slowly when profiling is enabled. Don't try to generate
+ absolute timings from the profiler results (such as, "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.
+ the code faster or slower relative to a previous profiling run.</p>
<h2 id="copyingfiles">Copying Trace Files to a Host Machine</h2>
@@ -189,7 +195,7 @@
"{@docRoot}images/tracedump.png"
width="485"
height="401" />
- <p class="image-caption"><strong>Figure 3.</strong> Screenshot of dmtracedump</p>
+ <p class="img-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>