Merge "Revised some text while reading up on traceview. this is what's left of this older CL that was left for dead: I5528b476d8110df51d45aaf690d878f72bc75c9f" into klp-docs
This commit is contained in:
@ -22,9 +22,12 @@ import android.util.Log;
|
||||
* 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 {
|
||||
/*
|
||||
|
@ -38,8 +38,7 @@ parent.link=index.html
|
||||
<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 @@ parent.link=index.html
|
||||
|
||||
<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 @@ parent.link=index.html
|
||||
<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 @@ parent.link=index.html
|
||||
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 @@ traceview /tmp/calc
|
||||
"{@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>
|
||||
|
Reference in New Issue
Block a user