docs/html/guide/developing/debug-tasks.jd

page.title=Debugging Tasks
@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#tools">Tools</a></li>
    <li><a href="#additionaldebugging">Debug with Dev Tools</a></li>
    <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li>
    <li><a href="#toptips">Top Debugging Tips</a></li>
    <li><a href="#ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</a></li>
  </ol>
</div>
</div>

<p>This document offers some helpful guidance to debugging applications on Android.


<h2 id="tools">Tools</h2>

<p>The Android SDK includes a set of tools to help you debug and profile
your applications. Here are some tools that you'll use most often:</p>

<dl>
  <dt><strong><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge
(ADB)</a></strong></dt>
  <dd>Provides various device management capabilities, including
    moving and syncing files to the emulator, forwarding ports, and running a UNIX
    shell on the emulator.</dd>
  <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server
(DDMS)</a></strong></dt>
  <dd>A graphical program that
        supports port forwarding (so you can set up breakpoints in your code in your
        IDE), screen captures on the emulator, thread and stack information,
        and many other features. You can also run logcat to retrieve your Log messages.</dd>
  </dd>
  <dt><strong><a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a></strong></dt>
  <dd>A graphical viewer that displays trace file data for method calls and times saved by
  your application, which can help you profile the performance of your application.</dd>
  <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt>
  <dd>Dumps a log of system
      messages. The messages include a stack trace when the emulator throws an error,
      as well as {@link android.util.Log} messages you've written from your application. To run
      logcat, execute <code>adb logcat</code> or, from DDMS, select <strong>Device > Run
      logcat</strong>.
      <p>{@link android.util.Log} is a logging
      class you can use to print out messages to the logcat. You can read messages
      in real time if you run logcat on DDMS (covered next). Common logging methods include:
      {@link android.util.Log#v(String,String)} (verbose), {@link
      android.util.Log#d(String,String)} (debug), {@link android.util.Log#i(String,String)}
      (information), {@link android.util.Log#w(String,String)} (warning) and {@link
      android.util.Log#e(String,String)} (error). For example:</p>
<pre class="no-pretty-print">
Log.i("MyActivity", "MyClass.getView() &mdash; get item number " + position);
</pre>
      <p>The logcat will then output something like:</p>
<pre class="no-pretty-print">
I/MyActivity( 1557): MyClass.getView() &mdash; get item number 1
</pre>
      <p>Logcat is also the place to look when debugging a web page in the Android Browser app. See
<a href="#DebuggingWebPages">Debugging Web Pages</a> below.</p>
</dl>

<p>For more information about all the development tools provided with the Android SDK, see the <a
href="{@docRoot}guide/developing/tools/index.html">Tools</a> document.</p>

<p>In addition to the above tools, you may also find the following useful for debugging:
<dl>
  <dt><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse ADT
plugin</strong></a></dt>
  <dd>The ADT Plugin for Eclipse integrates a number of the Android development tools (ADB, DDMS,
logcat output, and other functionality), so that you won't work with them directly but will utilize
them through the Eclipse IDE.</dd>
  <dt><strong>Developer Settings in the Dev Tools app</strong></dt>
  <dd>The Dev Tools application included in the emulator system image exposes several settings
        that provide useful information such as CPU usage and frame rate. See <a
href="#additionaldebugging">Debugging and Testing with Dev Tools</a> below.</dd>
</dl>

<h2 id="additionaldebugging">Debugging and Testing with Dev Tools</h2>

<p>With the Dev Tools application, you can enable a number of settings on your device that will
make it easier to test and debug your applications.</p>

<p>The Dev Tools application is installed by default
on all system images included with the SDK, so you can use it with the Android Emulator. If you'd
like to install the Dev Tools application on a real development device, you can copy the
application from your emulator and then install it on your device using ADB. To copy the
application from a running emulator, execute:
</p>
<pre>
adb -e pull /system/app/Development.apk ./Development.apk
</pre>
<p>This copies the .apk file into the current directory. Then install it on your connected device
with:</p>
<pre>
adb -d install Development.apk
</pre>

<p>To get started, launch the Dev Tools application and
select Development Settings. This will open the Development Settings page with the
following options (among others):</p>

<dl>
    <dt><strong>Debug app</strong></dt>
    <dd>Lets you select the application to debug. You do not need to set this to attach a debugger,
    but setting this value has two effects:
        <ul>
            <li>It will prevent Android from throwing an error if you pause on
                    a breakpoint for a long time while debugging.</li>
            <li>It will enable you to select the <em>Wait for Debugger</em> option
                to pause application startup until your debugger attaches (described
                next). </li>
        </ul>
    </dd>
    <dt><strong>Wait for debugger</strong></dt>
    <dd>Blocks the selected application from loading until a debugger attaches. This
            way you can set a breakpoint in onCreate(), which is important to debug
            the startup process of an Activity. When you change this option, any
            currently running instances of the selected application will be killed.
            In order to check this box, you must have selected a debug application
            as described in the previous option. You can do the same thing by adding
            {@link android.os.Debug#waitForDebugger()} to your code.</dd>
    <dt><strong>Show screen updates</strong></dt>
    <dd>Flashes a momentary pink rectangle on any screen sections that are being
            redrawn. This is very useful for discovering unnecessary screen drawing.</dd>
    <dt><strong>Immediately destroy activities</strong></dt>
    <dd>Tells the
        system to destroy an activity as soon as it is stopped (as if Android had to
        reclaim memory).&nbsp; This is very useful for testing the {@link android.app.Activity#onSaveInstanceState}
        / {@link android.app.Activity#onCreate(android.os.Bundle)} code path, which would
        otherwise be difficult to force. Choosing this option will probably reveal
        a number of problems in your application due to not saving state.</dd>
    <dt><strong>Show CPU usage</strong></dt>
    <dd>Displays CPU meters at the
        top of the screen, showing how much the CPU is being used. The top red bar
        shows overall CPU usage, and the green bar underneath it shows the CPU time
        spent in compositing the screen. <em>Note: You cannot turn this feature off
        once it is on, without restarting the emulator.</em> </dd>
    <dt><strong>Show background</strong></dt>
    <dd>Displays a background pattern
        when no activity screens are visible. This typically does not happen, but
        can happen during debugging.</dd>
</dl>

<p>These settings will be remembered across emulator restarts.</p>

<h2 id="DebuggingWebPages">Debugging Web Pages</h2>

<p>If you're developing a web application for Android devices, you can debug your JavaScript in the
Android Browser using the Console APIs, which will output messages to logcat. If you're familiar
debugging web pages with Firefox's FireBug or WebKit's Web Inspector, then you're probably familiar
with the Console APIs. The Android Browser (and the {@link android.webkit.WebChromeClient}) supports
most of the same APIs.</p>

<p>When you call a function from the Console APIs (in the DOM's {@code window.console} object),
you will see the output in logcat as a warning. For example, if your web page
executes the following JavaScript:</p>
<pre class="no-pretty-print">
console.log("Hello World");
</pre>
<p>Then the logcat output from the Android Browser will look like this:</p>
<pre class="no-pretty-print">
W/browser ( 202): Console: Hello World http://www.example.com/hello.html :82
</pre>

<p>All Console messages from the Android Browser are tagged with the name "browser" on Android
platforms running API Level 7 or higher. On platforms running API Level 6 or lower, Browser
messages are tagged with the name "WebCore". The Android Browser also formats console messages
with the log message
preceded by "Console:" and then followed by the address and line number where the
message occurred. (The format for the address and line number will appear different from the example
above on platforms running API Level 6 or lower.)</p>

<p>The Android Browser (and {@link android.webkit.WebChromeClient}) does not implement all of the
Console APIs provided by Firefox or other WebKit-based browsers. Primarily, you need to depend
on the basic text logging functions:</p>
<ul>
  <li>{@code console.log(String)}</li>
  <li>{@code console.info(String)}</li>
  <li>{@code console.warn(String)}</li>
  <li>{@code console.error(String)}</li>
</ul>
<p>Although the Android Browser may not fully implement other Console functions, they will not raise
run-time errors, but may not behave the same as they do on other desktop browsers.</p>

<p>If you've implemented a custom {@link android.webkit.WebView} in your application, then in order
to receive messages that are sent through the Console APIs, you must provide a {@link
android.webkit.WebChromeClient} that implements the {@link
android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
method. For example, assuming that the {@code myWebView} field references the {@link
android.webkit.WebView} in your application, you can log debug messages like this:</p>
<pre>
myWebView.setWebChromeClient(new WebChromeClient() {
  public void onConsoleMessage(String message, int lineNumber, String sourceID) {
    Log.d("MyApplication", message + " -- From line " + lineNumber + " of " + sourceID);
  }
});
</pre>
<p>The {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
onConsoleMessage()} method will be called each time one of the Console methods is called from
within your {@link android.webkit.WebView}.</p>
<p>When the "Hello World" log is executed through your {@link android.webkit.WebView}, it will
now look like this:</p>
<pre class="no-pretty-print">
D/MyApplication ( 430): Hello World -- From line 82 of http://www.example.com/hello.html
</pre>

<p class="note"><strong>Note:</strong> The {@link
android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
method was added with API Level 7. If you are using a custom {@link
android.webkit.WebView} on a platform running API Level 6 or lower, then your Console messages will
automatically be sent to logcat with the "WebCore" logging tag.</p>




<h2 id="toptips">Top Debugging Tips</h2>

<dl>
<dt><strong>Dump the stack trace</strong></dt>
<dd>To obtain a stack dump from emulator, you can log
in with <code>adb shell</code>, use &quot;ps&quot; to find the process you
want, and then &quot;kill -3 &quot;. The stack trace appears in the log file.
</dd>

<dt><strong>Display useful info on the emulator screen</strong></dt>
<dd>The device can display useful information such as CPU usage or highlights
around redrawn areas. Turn these features on and off in the developer settings
window as described in <a href="#additionaldebugging">Setting debug and test
configurations on the emulator</a>.
</dd>

<dt><strong>Get system state information from the emulator (dumpstate)</strong></dt>
<dd>You can access dumpstate information from the Dalvik Debug Monitor Service
tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and
dumpstate</a> on the adb topic page.</dd>

<dt><strong>Get application state information from the emulator (dumpsys)</strong></dt>
<dd>You can access dumpsys information from the Dalvik Debug Monitor Service
tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and
dumpstate</a> on the adb topic page.</dd>

<dt><strong>Get wireless connectivity information</strong></dt>
<dd>You can get information about wireless connectivity using the Dalvik Debug
Monitor Service tool. From the <strong>Device</strong> menu, select &quot;Dump
radio state&quot;.</dd>

<dt><strong>Log trace data</strong></dt>
<dd>You can log method calls and other tracing data in an activity by calling
{@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a
href="{@docRoot}guide/developing/tools/traceview.html">Running the Traceview Debugging
Program</a> for details. </dd>

<dt><strong>Log radio data</strong></dt>
<dd>By default, radio information is not logged to the system (it is a lot of
data). However, you can enable radio logging using the following commands:

<pre class="no-pretty-print">
adb shell
logcat -b radio
</pre>
</dd>

<dt><strong>Capture screenshots</strong></dt>
<dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select
<strong>Device > Screen capture</strong>.</dd>

<dt><strong>Use debugging helper classes</strong></dt>
<dd>Android provides debug helper classes such as {@link android.util.Log
    util.Log} and {@link android.os.Debug} for your convenience. </dd>
</dl>

<p>Also see the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document
for answers to some common developing and debugging issues.</p>


<h2 id="ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</h2>

<p>DDMS will assign a specific debugging port to every virtual machine that it
    finds on the emulator. You must either attach your IDE to that
    port (listed on the Info tab for that VM), or you can use a default port 8700
    to connect to whatever application is currently selected on the list of discovered
    virtual machines.</p>
<p>Your IDE should attach to your application running on the emulator, showing you
    its threads and allowing you to suspend them, inspect their state, and set breakpoints.
    If you selected &quot;Wait for debugger&quot; in the Development settings panel
    the application will run when Eclipse connects, so you will need to set any breakpoints
    you want before connecting.</p>
<p>Changing either the application being debugged or the &quot;Wait for debugger&quot;
    option causes the system to kill the selected application if it is currently
        running. You can use this to kill your application if it is in a bad state
        by simply going to the settings and toggling the checkbox.</p>