android_frameworks_base/docs/html/tools/help/am-logcat.jd

page.title=logcat Monitor
parent.title=Android Monitor
parent.link=android-monitor.html
page.tags=monitor
@jd:body
<div id="qv-wrapper">
  <div id="qv">
    <h2>
      In this document
    </h2>

    <ol>
      <li>
        <a href="#format">logcat Message Format</a>
      </li>

      <li>
        <a href="#running">Displaying a Running App in the logcat Monitor</a>
      </li>

      <li>
        <a href="#level">Setting the Log Level</a>
      </li>

      <li>
        <a href="#searching">Searching logcat Messages</a>
      </li>

      <li>
        <a href="#filtering">Filtering logcat Messages</a>
      </li>

      <li>
        <a href="#logheader">Configuring the logcat Header Display</a>
      </li>

      <li>
        <a href="#stack">Moving Up and Down the Stack Trace</a>
      </li>

      <li>
        <a href="#logend">Moving to the End of the Log</a>
      </li>

      <li>
        <a href="#printing">Printing the Log</a>
      </li>

      <li>
        <a href="#clearing">Clearing the Log</a>
      </li>

      <li>
        <a href="#restarting">Restarting the Log</a>
      </li>
    </ol>

    <h2>
      See also
    </h2>

    <ol>
      <li>
        <a href="{@docRoot}tools/debugging/debugging-log.html">Reading and Writing Logs</a>
      </li>
      <li>
        <a href="{@docRoot}tools/help/android-monitor.html">Android Monitor</a>
      </li>

      <li><a href="{@docRoot}tools/help/am-memory.html">Memory Monitor</a>
      </li>

      <li><a href="{@docRoot}tools/help/am-cpu.html">CPU Monitor</a>
      </li>

      <li><a href="{@docRoot}tools/help/am-gpu.html">GPU Monitor</a>
      </li>

      <li>
        <a href="{@docRoot}tools/help/am-network.html">Network Monitor</a>
      </li>
    </ol>

    <h2>
      Dependencies and Prerequisites
    </h2>

    <ul>
      <li>Enable ADB integration through <strong>Tools</strong> &gt; <strong>Android</strong> &gt;
      <strong>Enable ADB Integration</strong>.
      </li>
  <li>
    <a href="{@docRoot}tools/help/monitor.html">Android Device Monitor</a> can’t be running.
  </li>
    </ul>
  </div>
</div>

<p>
  The Android logging system provides a mechanism for collecting and viewing system debug output.
  logcat Monitor displays messages that you added to your app by using the <a href=
  "{@docRoot}reference/android/util/Log.html">Log</a> class, as well as system
  messages, such as stack traces when the emulator throws an error or a garbage collection occurs.
  The monitor displays messages in real time and also keeps a history so you can view older
  messages.
</p>

<p>
  To display just the information of interest, you can create filters, modify how much information
  is displayed in messages, set priority levels, display messages produced by app code
  only, and search the log. By default, logcat Monitor shows the log output related to the running
  application only.
</p>

<p>
  You can traverse the stack trace when your app throws an exception, as well as view the
  associated code. This feature can help you fix exceptions and improve app operation.
</p>

<h2 id="format">
  logcat Message Format
</h2>

<p>
  Every Android log message has a tag and a priority associated with it. The tag of a system
  log message
  is a short string indicating the system component from which the message originates (for example,
  <code>ActivityManager</code>). A user-defined tag can be any string that you find helpful, such
  as the name of the current class (the recommended tag). You define it in a <code>Log</code>
  method call, for example:
</p>

<pre>
Log.d(tag, message);
</pre>
<p>
  The priority is one of the following values:
</p>

<ul>
  <li>
    <strong>V</strong> — Verbose (lowest priority)
  </li>

  <li>
    <strong>D</strong> — Debug
  </li>

  <li>
    <strong>I</strong> — Info
  </li>

  <li>
    <strong>W</strong> — Warning
  </li>

  <li>
    <strong>E</strong> — Error
  </li>

  <li>
    <strong>A</strong> — Assert
  </li>
</ul>

<p>
  The log message format is:
</p>

<pre class="no-pretty-print">
<em>date time PID-TID/package priority/tag: message</em>
</pre>

<p>
  For example, the following log message has a priority of <code>V</code> and a tag of
  <code>AuthZen</code>:
</p>

<pre class="no-pretty-print">
12-10 13:02:50.071 1901-4229/com.google.android.gms V/AuthZen: Handling delegate intent.
</pre>
<p>
  PID stands for process identifier and TID is thread identifier; they can be the same if there’s
  only one thread.
</p>

<h2 id="running">
  Displaying a Running App in the logcat Monitor
</h2>

<p>
  Follow these steps:
</p>

<ol>
  <li>Optionally connect a hardware device.
  </li>

  <li>
    <a href="{@docRoot}tools/help/android-monitor.html#displaying">Display Android Monitor</a>.
  </li>

  <li>Click the <strong>logcat</strong> tab.
  </li>

  <li>Open an app project and <a href=
  "{@docRoot}tools/building/building-studio.html#RunningApp">run it</a> on a hardware device or
  emulator.
  </li>
<p>
  By default, the logcat Monitor displays messages for the app running on the device or emulator:
</p>
<img src="{@docRoot}images/tools/am-logcatmon.png" />
<p>
  To change this default, see <a href="#filtering">Filtering logcat Messages</a>.
</p>
</ol>

<h2 id="level">
  Setting the Log Level
</h2>

<p>
  You can control how many messages appear in logcat Monitor by setting the log level. You can
  display all messages, or just the messages indicating the most severe conditions.
</p>

<p>
  Remember that logcat Monitor continues to collect all messages regardless of the log level setting.
  The setting just determines what logcat Monitor displays.
</p>

<p>
  Follow this step:
</p>

<ul>
  <li>In the <strong>Log level</strong> menu, select one of the following values:
  </li>

    <ul>
      <li>
        <strong>Verbose</strong> - Show all log messages (the default).
      </li>

      <li>
        <strong>Debug</strong> - Show debug log messages that are useful during development only,
        as well as the message levels lower in this list.
      </li>

      <li>
        <strong>Info</strong> - Show expected log messages for regular usage, as well as the
        message levels lower in this list.
      </li>

      <li>
        <strong>Warn</strong> - Show possible issues that are not yet errors, as well as the
        message levels lower in this list.
      </li>

      <li>
        <strong>Error</strong> - Show issues that have caused errors, as well as the message levels
        lower in this list.
      </li>

      <li>
        <strong>Assert</strong> - Show issues that the developer expects should never happen.
      </li>
    </ul>

</ul>

    <h2 id="searching">
      Searching logcat Messages
    </h2>

    <p>
      You can search the messages currently displayed in logcat Monitor. Follow these steps:
    </p>

    <ol>
      <li>Optionally select <strong>Regex</strong> if you want to use a regular expression
      search pattern.
      </li>

      <li>Type a character sequence in the search field <img src="{@docRoot}images/tools/am-isearch.png"
        style="vertical-align:sub;margin:0;height:17px" alt="Search icon" />.
      </li>

    <p>
      The logcat Monitor display changes accordingly.
    </p>
  </li>

  <li>Press <strong>Enter</strong> to store the sequence in the menu during this session.
  </li>

  <li>To repeat a search, choose it from the search menu. Select or deselect
  <strong>Regex</strong> as needed (the setting isn’t remembered).
  </li>
 </ol>

    <h2 id="filtering">
      Filtering logcat Messages
    </h2>

    <p>
      One way to reduce the log output to a manageable level is to restrict it by using a filter.
    </p>

    <p class="note">
      <strong>Note:</strong> The filter applies to your full logcat history, not just those messages
      currently displayed in logcat Monitor. Make sure your other display options are set
      appropriately so you can see the filter output you want to examine.
    </p>

    <p>
      To define and apply a filter, follow these steps:
    </p>

    <ol>
      <li>In the filter menu, select a filter option:
        <ul>
          <li>
            <strong>Show only selected application</strong> - Display the messages produced by the
            app code only.
          </li>

          <li>
            <strong>No Filters</strong> - Apply no filters (the default).
          </li>

          <li>
            <strong>Edit Filter Configuration</strong> - Create or modify a custom filter.
          </li>
        </ul>

        <p>
          After you define filters, you can also select them in the menu. To remove them from the
          menu, delete them.
        </p>

          <li>If you selected <strong>Edit Filter Configuration</strong>, create or modify a
          filter.
            <ol type="a">
              <li>Specify the filter parameters in the <em>Create New Logcat Filter</em> dialog:
              </li>


            <ul>
              <li>
                <strong>Filter Name</strong> - Type the name of a filter you want to define, or
                select it in the left pane to modify an existing filter. The name can contain
                lowercase characters, underscores, and digits only.
              </li>

              <li>
                <strong>Log Tag</strong> - Optionally specify a tag. For more information, see
                <a href="#format">logcat Message Format</a>.
              </li>

              <li>
                <strong>Log Message</strong> - Optionally specify log message text. For more
                information, see <a href="#format">logcat Message Format</a>.
              </li>

              <li>
                <strong>Package Name</strong> - Optionally specify a package name. For more
                information, see <a href="#format">logcat Message Format</a>.
              </li>

              <li>
                <strong>PID</strong> - Optionally specify a process ID. For more information, see
                <a href="#format">logcat Message Format</a>.
              </li>

              <li>
                <strong>Log Level</strong> - Optionally select a log level. For more information,
                see <a href="#level">Setting the Log Level</a>.
              </li>

              <li>
                <strong>Regex</strong> - Select this option to use regular expression syntax for
                that parameter.
              </li>
            </ul>

            <li>
              Click <strong>+</strong> to add it to the left pane.
            </li>

            <p>
              To remove a filter, select it in the left pane and click <strong>-</strong>.
            </p>

            <li>
              When you’re finished, click <strong>OK</strong>. If you click
              <strong>Cancel</strong>, any filter additions or modifications are lost.
            </li>
            </ol>
            </ol>

            <h2 id="logheader">
              Configuring the logcat Header Display
            </h2>

            <p>
              You can customize the header display to show just the information you’re interested
              in:
            </p>

            <ul>
              <li>Select Use Soft Wraps <img src="{@docRoot}images/tools/am-isoftwraps.png"
                style="vertical-align:sub;margin:0;height:17px" alt="Use Soft Wraps icon" />
                to see the entire
              message and prevent it from running off of the right edge.
              </li>

              <li>Click Configure Logcat Header <img src="{@docRoot}images/tools/am-igear.png"
                style="vertical-align:sub;margin:0;height:17px" alt="Configure Logcat header icon" />
                to specify
              elements of the messages that you want to show or hide, and then click
              <strong>OK</strong>.
              </li>
            </ul>

            <p>
              For more information about message elements, see <a href=
              "#format">logcat Message Format</a>.
            </p>

            <h2 id="stack">
              Moving Up and Down the Stack Trace
            </h2>

            <p>
              When the app throws an exception, the message includes a stack trace of method calls.
              logcat
              Monitor lets you quickly locate stack traces in the log and view the associated code
              in the Code Editor. If needed (and possible), the decompiler derives source code that
              you can view.
            </p>

            <ul>
              <li>Click Up the Stack Trace <img src="{@docRoot}images/tools/am-iupstack.png"
                style="vertical-align:sub;margin:0;height:17px" alt="Up the Stack Trace icon" />
                to move to the
              previous method in relation to the current position in the log.
              </li>

              <li>Click Down the Stack Trace <img src="{@docRoot}images/tools/am-idownstack.png"
                style="vertical-align:sub;margin:0;height:17px" alt="Down the Stack Trace icon" />
                to move to
              the next method in relation to the current position in the log.
              </li>
            </ul>

            <h2 id="logend">
              Moving to the End of the Log
            </h2>

            <p>
              Clicking a particular message stops the display of messages. You can quickly move to
              the end of the log to see the real-time message flow.
            </p>

<ul>
          <li>Click Scroll to the End <img src="{@docRoot}images/tools/am-iscrollend.png"
            style="vertical-align:sub;margin:0;height:17px" alt="Scroll to the End icon" />.
          </li>

          <li>Press the End key.
          </li>

          <li>Scroll or press the Page Down key until you reach the end.
</li>
</ul>

<h2 id="printing">
  Printing the Log
</h2>
<p>
  Follow these steps:
</p>
<ol>
  <li>Click Print <img src="{@docRoot}images/tools/am-iprint.png"
    style="vertical-align:sub;margin:0;height:17px" alt="Print icon" />.
  </li>
  <li>
    In the <em>Print</em> dialog, optionally change print parameters, and then click
    <strong>Print</strong>.
</ol>

<h2 id="clearing">
  Clearing the Log
</h2>
<p>
  To clear (flush) the entire log, follow this step:
</p>
<ul>
  <li>Click Clear logcat <img src="{@docRoot}images/tools/am-iclear.png"
    style="vertical-align:sub;margin:0;height:17px" alt="Clear logcat icon" />.
  </li>
</ul>



<h2 id="restarting">
  Restarting the Log
</h2>

<p>
  If there is a problem and the log is no longer progressing, you can restart the log. Follow this
  step:
</p>

<ul>
  <li>Click Restart <img src="{@docRoot}images/tools/am-irestart.png"
    style="vertical-align:sub;margin:0;height:17px" alt="Restart icon" />.
  </li>
</ul>