Debugging Tasks

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

Tools

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:

Android Debug Bridge (ADB)
Provides various device management capabilities, including moving and syncing files to the emulator, forwarding ports, and running a UNIX shell on the emulator.
Dalvik Debug Monitor Server (DDMS)
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.
Traceview
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.
logcat
Dumps a log of system messages. The messages include a stack trace when the emulator throws an error, as well as Log messages you've written from your application. To run logcat, execute adb logcat or, from DDMS, select Device > Run logcat.

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: v(String, String) (verbose), d(String, String) (debug), i(String, String) (information), w(String, String) (warning) and e(String, String) (error). For example:

Log.i("MyActivity", "MyClass.getView() — get item number " + position);

The logcat will then output something like:

I/MyActivity( 1557): MyClass.getView() — get item number 1

Logcat is also the place to look when debugging a web page in the Android Browser app. See Debugging Web Pages below.

For more information about all the development tools provided with the Android SDK, see the Tools document.

In addition to the above tools, you may also find the following useful for debugging:

Eclipse ADT plugin
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.
Developer Settings in the Dev Tools app
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 Debugging and Testing with Dev Tools below.

Debugging and Testing with Dev Tools

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.

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:

adb -e pull /system/app/Development.apk ./Development.apk

This copies the .apk file into the current directory. Then install it on your connected device with:

adb -d install Development.apk

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):

Debug app
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:
  • It will prevent Android from throwing an error if you pause on a breakpoint for a long time while debugging.
  • It will enable you to select the Wait for Debugger option to pause application startup until your debugger attaches (described next).
Wait for debugger
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 waitForDebugger() to your code.
Show screen updates
Flashes a momentary pink rectangle on any screen sections that are being redrawn. This is very useful for discovering unnecessary screen drawing.
Immediately destroy activities
Tells the system to destroy an activity as soon as it is stopped (as if Android had to reclaim memory).  This is very useful for testing the onSaveInstanceState(Bundle) / 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.
Show CPU usage
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. Note: You cannot turn this feature off once it is on, without restarting the emulator.
Show background
Displays a background pattern when no activity screens are visible. This typically does not happen, but can happen during debugging.

These settings will be remembered across emulator restarts.

Debugging Web Pages

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 WebChromeClient) supports most of the same APIs.

When you call a function from the Console APIs (in the DOM's window.console object), you will see the output in logcat as a warning. For example, if your web page executes the following JavaScript:

console.log("Hello World");

Then the logcat output from the Android Browser will look like this:

W/browser ( 202): Console: Hello World http://www.example.com/hello.html :82

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.)

The Android Browser (and 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:

  • console.log(String)
  • console.info(String)
  • console.warn(String)
  • console.error(String)

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.

If you've implemented a custom WebView in your application, then in order to receive messages that are sent through the Console APIs, you must provide a WebChromeClient that implements the onConsoleMessage() callback method. For example, assuming that the myWebView field references the WebView in your application, you can log debug messages like this:

myWebView.setWebChromeClient(new WebChromeClient() {
  public void onConsoleMessage(String message, int lineNumber, String sourceID) {
    Log.d("MyApplication", message + " -- From line " + lineNumber + " of " + sourceID);
  }
});

The onConsoleMessage() method will be called each time one of the Console methods is called from within your WebView.

When the "Hello World" log is executed through your WebView, it will now look like this:

D/MyApplication ( 430): Hello World -- From line 82 of http://www.example.com/hello.html

Note: The onConsoleMessage() callback method was added with API Level 7. If you are using a custom 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.

Top Debugging Tips

Dump the stack trace
To obtain a stack dump from emulator, you can log in with adb shell, use "ps" to find the process you want, and then "kill -3 ". The stack trace appears in the log file.
Display useful info on the emulator screen
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 Setting debug and test configurations on the emulator.
Get system state information from the emulator (dumpstate)
You can access dumpstate information from the Dalvik Debug Monitor Service tool. See dumpsys and dumpstate on the adb topic page.
Get application state information from the emulator (dumpsys)
You can access dumpsys information from the Dalvik Debug Monitor Service tool. See dumpsys and dumpstate on the adb topic page.
Get wireless connectivity information
You can get information about wireless connectivity using the Dalvik Debug Monitor Service tool. From the Device menu, select "Dump radio state".
Log trace data
You can log method calls and other tracing data in an activity by calling startMethodTracing(). See Running the Traceview Debugging Program for details.
Log radio data
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:
adb shell
logcat -b radio
Capture screenshots
The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select Device > Screen capture.
Use debugging helper classes
Android provides debug helper classes such as util.Log and Debug for your convenience.

Also see the Troubleshooting document for answers to some common developing and debugging issues.

Configuring Your IDE to Attach to the Debugging Port

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.

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 "Wait for debugger" in the Development settings panel the application will run when Eclipse connects, so you will need to set any breakpoints you want before connecting.

Changing either the application being debugged or the "Wait for debugger" 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.

↑ Go to top