am af623b99: am bb146981: am 29610421: Merge "Revised some text while reading...

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

    /*

  <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

  <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"

  <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

  to generate trace data, see <a href="ddms.html#profiling">Using the Dalvik Debug Monitor Server.</a>

    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>

      "{@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>