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

page.title=logcat Monitor
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 logcat Monitor to view system and user-defined log messages. You can filter the messages to display just the items that interest you.
page.image=tools/help/thumbnails/am-logcatmon2.png
page.article=true

@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 and Writing to a File</a>
      </li>

      <li>
        <a href="#clearing">Clearing and 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>
    </ol>

  </div>
</div>

<p>
  The Android logging system provides a mechanism for collecting and viewing system debug output.
  The logcat Monitor displays system messages, such as when a garbage collection occurs, as well as
  messages that you added to your app by using the <a href=
  "{@docRoot}reference/android/util/Log.html">Log</a> class.
  It 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, the logcat Monitor shows the log output related to the
  most recently run app only.
</p>

<p>
  When an app throws an exception, the logcat Monitor shows a message followed by the associated
  stack trace containing links to
  the code. This feature can help you fix errors 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,
  {@link android.app.ActivityManager}). 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
  {@link android.util.Log} 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>
  To display the log messages for a particular app:
</p>

<ol>
  <li>Meet the <a href=
  "{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
  </li>
 <li>Open an app project.
  </li>
  <li><a href=
  "{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on a hardware device or
  emulator.
  </li>
  <li>
    <a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
  </li>

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


<p>
  By default, the logcat Monitor displays just the log messages for your app running on the
  device or emulator:
</p>
<img src="{@docRoot}images/tools/am-logcatmon2.png" />
<p>
  To change this default, see <a href="#filtering">Filtering logcat Messages</a>.
</p>
<li>Optionally <a href=
  "{@docRoot}tools/help/am-basics.html#switching">select a different device, emulator, or process</a>.
  </li>
</ol>

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

<p>
  You can control how many messages appear in the 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 the logcat Monitor continues to collect all messages regardless of the log level setting.
  The setting just determines what the logcat Monitor displays.
</p>

<p>
  To set the log level:
</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 level
        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>
      To search the messages currently displayed in the logcat Monitor:
    </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 Enter to store the search string 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 the 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:
    </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 (the default). The logcat Monitor filters the log messages using the PID
            of the active app.
          </li>

          <li>
            <strong>No Filters</strong> - Apply no filters. The logcat Monitor
            displays all log messages from the device, regardless of which process you selected.
          </li>

          <li>
            <strong>Edit Filter Configuration</strong> - Create or modify a custom filter. For
            example, you could create a filter to view log messages from two apps at the same time.
          </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 the filter definition 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>
            <li>
              Make sure you see the log messages you want to examine.
            </li>
             <p>
              If you don't think you see the log messages you want, try selecting
              <strong>No filters</strong> and <a href="#searching">searching</a> for particular
              log messages.
            </p>
            </ol>

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

            <p>
              To 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>
             <p>
              To move up and down the stack trace, and view the associated code in the Code Editor:
            </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.
            </p>
            <p>
              To 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 and Writing to a File
</h2>
<p>
  To preserve log information, you can send the log to a printer, write the log to a PDF file, or
  copy and paste the log into a text file.
</p>
<p>
  To print the log or write it to a PDF file:
</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 Android Studio <em>Print</em> dialog, optionally change print parameters, and then click
    <strong>Print</strong>.
  </li>
  <li>
    In the operating system <em>Print</em> dialog, optionally change print parameters, and then click
    <strong>Print</strong>.
  </li>
  <p>
  You can set the parameters to send the log to a printer or write it to a PDF file.
</p>
</ol>
<p>
  To copy the log to a text file:
</p>
<ol>
  <li>In the logcat Monitor, select and then copy log text.
  </li>
  <p>Press Ctrl+A (⌘A) to select all.</p>
  <li>
    Open a text editor and paste the text into a file.
  </li>
</ol>

<h2 id="clearing">
  Clearing and Restarting the Log
</h2>
<p>
  To clear (flush) the entire log:
</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>


<p>
  If there's a problem and the log is no longer progressing, you can restart the log:
</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>