docs/html/tools/help/am-methodtrace.jd

page.title=Method Trace
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the CPU Monitor to perform a method trace on your app. View call stack and timing information in the method trace display.
page.image=tools/help/thumbnails/am_methodtrace.png
page.article=true

@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
<ol>
<li><a href="#display">Understanding the Method Trace Display</a></li>
  <li><a href="#trace">Performing a Method Trace in the CPU Monitor</a></li>
  <li><a href="#viewtrace">Viewing a Saved Method Trace</a></li>
  <li><a href="#sorttrace">Sorting Method Trace Data</a></li>
  <li><a href="#trace-files">Working with Method Trace Files</a></li>
</ol>

</div>
</div>


<p>
  You can start a method trace from the CPU Monitor. It lets you view the call stack and timing
  information for your app. This information can help you optimize and debug your app.
</p>

<h2 id="display">
  Understanding the Method Trace Display
</h2>

<p>
  The method trace looks similar to the following figure:
</p>
<img src="{@docRoot}images/tools/am-methodtrace.png" alt="Method Trace" />
<p></p>

<p>The display shows the following information:</p>

<table>
  <tr>
    <th scope="col">Field</th>
    <th scope="col">Description</th>
  </tr>

  <tr>
    <td><strong>Name</strong></td>
    <td>The name of the method.</td>
  </tr>

  <tr>
    <td><strong>Invocation Count</strong></td>
    <td>How many times the method was called.</td>
  </tr>

  <tr>
    <td><strong>Inclusive Time (microseconds)</strong></td>
    <td>Time spent in the method and all of its children, either wall clock or thread time,
          depending on your selection in the <strong>x-axis</strong> menu.</td>
  </tr>

  <tr>
    <td><strong>Exclusive Time (microseconds)</strong></td>
    <td>Time spent just in the method (excluding time spent in its children), either wall clock
          or thread time, depending on your selection in the <strong>x-axis</strong> menu.</td>
  </tr>
</table>

<p class="note"><strong>Note:</strong> Running the method trace significantly affects CPU timings.
  Use the method trace to understand the flow of the program, but not for performance timings.</p>

<h2 id="trace">
  Performing a Method Trace in the CPU Monitor
</h2>

<p>
  To perform a method trace:
</p>

<ol>
  <li>
    <a href="{@docRoot}tools/help/am-cpu.html#running">Display a running app in the CPU
    Monitor</a>.
  </li>

  <li>Start a trace by clicking Start Method Tracing <img src="{@docRoot}images/tools/am-imethodtrace.png"
    style="vertical-align:sub;margin:0;height:17px" alt="Start Method Tracing icon" /> to
  select it.
  </li>

  <li>To stop the trace, click Stop Method Tracing <img src="{@docRoot}images/tools/am-imethodtrace.png"
    style="vertical-align:sub;margin:0;height:17px" alt="Stop Method Tracing icon" /> to
  deselect it.
  </li>

<p>
  The method trace appears in the Code Editor area.
</p>

<p>
  Android Studio creates the method trace file
  with the filename <code><em>package_yyyy.mm.dd_hh.mm.ss</em>.trace</code>
  using the activity package (or project) name, year, month, day, hour, minute, and second of
  the capture, for example,
  <code>com.android.calc_2015.11.17_14.58.48.trace</code>.
</p>
  <li>Specify display options:
    <ul>
      <li>Select a <strong>Thread</strong>.
      </li>

      <li>Select an <strong>x-axis</strong> time for the graphic and the method list:
      </li>

        <ul>
          <li>
            <strong>Wall Clock Time</strong> - Total CPU time elapsed between the method call and
            return.
          </li>

          <li>
            <strong>Thread Time</strong> - Total time during which the JRE scheduled the
            thread during call processing. It’s less than or equal to the Wall Clock Time: less if
            the JRE interrupted the thread, and equal if it didn’t.
            The thread might not run continuously; when it’s not executing, that time is excluded.
            If threads are interrupted often and it’s not by design, the interruptions affect app
            performance. However, an example of a by-design use is synchronous operations that take
            a long time, such as file transfers and reads from disk, where the method could be the
            asynchronous wrapper for the synchronous reader.
          </li>
       </ul>

        <li>
          Optionally select <strong>Color by inclusive time</strong>.
        </li>
        </ul>



        <p>
          The graphic represents the wall clock or thread time for each method. Hover the cursor
          over the display to receive information about the method. This information also appears
          in the table.
        </p>
</ol>
        <h2 id="viewtrace">
          Viewing a Saved Method Trace
        </h2>

        <p>
          After you do a method trace, Android Studio automatically stores it so you can view it
          again.</p>

          <p>To examine a saved method trace:
        </p>

        <ol>
          <li>Click
          <img src="{@docRoot}images/tools/am-icaptures.png"
          style="vertical-align:sub;margin:0;height:17px"
          alt="Captures icon" /> in the main window.
          </li>
          <p>Or select <strong>View</strong> > <strong>Tools Windows</strong> >
          <strong>Captures</strong>.</p>

        <p>
          The <em>Captures</em> window appears.
        </p>

      <li>Open the <strong>Methods Tracing</strong> folder.
      </li>

      <li>Double-click the file to view it.
      </li>
</ol>

<h2 id="sorttrace">
  Sorting Method Trace Data
</h2>

<p>
  You can sort the data by method name, count, inclusive time, and exclusive
  time.</p>

  <p>To sort method trace data:</p>


<ul>
  <li>Click a column heading to sort the table by ascending or descending order.
  </li>
</ul>

<h2 id="trace-files">Working with Method Trace Files</h2>
<p>You can rename, locate, and delete a method trace file from within Android
Studio.</p>

<h3 id="renametrace">
  Renaming a method trace file
</h3>

<p>
  Rename a method trace file from within Android Studio so it
  continues to appear in the <em>Captures</em> window.</p>

  <p>To rename a method trace file:
</p>

<ol>
  <li>In the <em>Captures</em> window, right-click the file and select <strong>Rename</strong>.
  </li>

  <li>In the dialog, specify the name of the file and click <strong>OK</strong>.
  </li>
</ol>

<h3 id="locatetrace">
  Locating a method trace file on disk
</h3>

<p>
  You can quickly discover where Android Studio stored method trace files on
  disk.</p>

  <p>To locate a method trace file on disk:
</p>



<ul>
  <li>In the <em>Captures</em> window, right-click a method trace file and
  select <strong>Show</strong> or <strong>Reveal</strong>.
  </li>

<p>
  Android Studio opens an operating system file browser displaying the location where the file
  resides.
</p>
</ul>
<p class="note">
  <strong>Note:</strong> If you move a method trace file, Android Studio no longer displays the file
  in the <em>Captures</em> window. To display it, use <strong>File</strong> &gt;
  <strong>Open</strong>. Also, rename a file from the <em>Captures</em>
  window and not in the operating system file browser.
</p>

<h3 id="deletetrace">
  Deleting a method trace file
</h3>

<p>
  To delete a method trace file:
</p>

<ul>
  <li>In the <em>Captures</em> window, right-click a method trace file and select
  <strong>Delete</strong>.
  </li>
</ul>

<p>
  Android Studio deletes the file from the <em>Captures</em> dialog and from disk.
</p>