drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Scott Main
2013-11-13 02:50:49 +00:00
committed by Android (Google) Code Review
parent 2a91ecb129 c468240c1a
commit 29610421a3
2 changed files with 35 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
core/java/android/os/Trace.java
View File

@ -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 {
/*

56
docs/html/tools/debugging/debugging-tracing.jd
View File

@ -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&rsquo;s execution is shown
<p>Figure 1 shows a close up of the timeline panel. Each thread&rsquo;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>&lt;trace-base-name&gt;.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>&lt;ref&gt;
<em>callname</em> (&lt;inc-ms&gt;, &lt;exc-ms&gt;,&lt;numcalls&gt;)</code>, where</p>