Quick-Start Guide: Android DDMS - Appendixes - Introduction to Android Application Development, Fourth Edition (2014)

Introduction to Android Application Development, Fourth Edition (2014)

Part VI. Appendixes

C. Quick-Start Guide: Android DDMS

The Dalvik Debug Monitor Server (DDMS) is a debugging tool provided with the Android SDK. Developers use DDMS to provide a window into the emulator or the actual device for debugging purposes as well as file and process management. It’s a blend of several tools: a task manager, a profiler, a file explorer, an emulator console, and a logging console. This Quick-Start Guide is not complete documentation of the DDMS functionality. Instead, it is designed to get you up and running with common tasks. See the DDMS documentation provided with the Android SDK for a complete list of features.

When this appendix discusses an IDE, the focus is on the Android IDE. Whenever we refer to the Android IDE, the same instructions apply to Eclipse with the ADT plugin. Because the Android IDE and Eclipse with the ADT plugin are equivalent, from here on we will mention only the Android IDE.

Using DDMS with the Android IDE and as a Standalone Application

If you use the Android IDE, the DDMS tool is tightly integrated with your development environment as a perspective. By using the DDMS perspective (shown in Figure C.1, using the File Explorer to browse files on the emulator instance), you can explore any emulator instances running on the development machine and any Android devices connected via USB.

Image

Figure C.1 The Android IDE DDMS perspective with one emulator and one Android device connected in the Devices pane.

If you’re not using the Android IDE, the DDMS tool is also available within the /tools directory of the Android SDK, and you can launch it as a separate application, in which case it runs in its own process.

Image Tip

There should be only one instance of the DDMS tool running at a given time. This includes the Android IDE perspective. Other DDMS launches are ignored; if you have the Android IDE running and try to launch DDMS from the command line, you might see question marks instead of process names, and you will see debug output stating that the instance of DDMS is being ignored.

Image Warning

Not all DDMS features are available for both emulators and devices. Certain features, such as the Emulator Control features, are available only for emulators. Most devices are more secure than the emulator. Thus, the File Explorer may be limited to just public areas of the device, unlike on the emulator.

Getting Up to Speed Using Key Features of DDMS

Whether you use DDMS from the Android IDE or as a standalone tool, be aware of a few key features:

Image The Devices pane displays running emulators and connected devices in the top-left corner.

Image The set of Threads, Heap, Allocation Tracker, Network Statistics, File Explorer, and System Information tabs on the right side are populated with data when a specific process on an emulator or device is highlighted in the Devices pane.

Image The Emulator Control pane provides features such as the ability to send GPS information and to simulate incoming calls and SMS messages to emulators.

Image The LogCat window enables you to monitor the output of the Android logging console for a given device or emulator. This is where calls to Log.i(), Log.e(), and other log messages display.

Now let’s look at how to use each of these DDMS features in more detail.

Image Tip

Another Android IDE perspective provides direct access to the Hierarchy Viewer tool, which can be used for debugging and performance-tuning your application user interface. See Appendix A, “Mastering the Android Development Tools,” for more details about this tool.

Working with Processes, Threads, and the Heap

One of the most useful features of DDMS is the ability to interact with processes. Each Android application runs in its own VM with its own user ID on the operating system. Using the Devices pane of DDMS, you can browse all instances of the VM running on a device, each identified by its package name. For example, you can perform the following tasks:

Image Attach and debug applications in the Android IDE

Image Monitor threads

Image Monitor the heap

Image Stop processes

Image Force garbage collection (GC)

Attaching a Debugger to an Android Application

Although you’ll use the Android IDE debug configurations to launch and debug your applications most of the time, you can also use DDMS to choose which application to debug and attach directly. To attach a debugger to a process, you need to have the package source code open in your Android IDE workspace. Now perform the following steps to debug:

1. On the emulator or device, verify that the application you want to debug is running.

2. In DDMS, find that application’s package name in the Devices pane and highlight it.

3. Click the little green bug button (Image) to debug that application.

4. Switch to the Debug perspective of the Android IDE as necessary; debug as you would normally.

Stopping a Process

You can use DDMS to kill an Android application by following these steps:

1. On the emulator or device, verify that the application you want to stop is running.

2. In DDMS, find that application’s package name in the Devices pane and highlight it.

3. Click the red stop sign button (Image) to stop that process.

Monitoring Thread Activity of an Android Application

You can use DDMS to monitor thread activity of an individual Android application by following these steps:

1. On the emulator or device, verify that the application you want to monitor is running.

2. In DDMS, find that application’s package name in the Devices pane and highlight it.

3. Click the button with three black arrows (Image) to display the threads of that application. They appear in the right portion of the Threads pane.

4. On the Threads pane, you can choose a specific thread and click the Refresh button to drill down within that thread. The resulting classes in use display below.

Image Note

You can also start thread profiling using the button with three black arrows and a red dot (Image).

For example, in Figure C.2, we see the Threads pane contents for the package named com.introtoandroid.myfirstandroidapp running on the emulator.

Image

Figure C.2 Using the DDMS Threads pane.

Monitoring Heap Activity

You can use DDMS to monitor the heap statistics of an individual Android application. The heap statistics are updated after every garbage collection (GC) via these steps:

1. On the emulator or device, verify that the application you want to monitor is running.

2. In DDMS, find that application’s package name in the Devices pane and highlight it.

3. Click the green cylinder button (Image) to display the heap information for that application. The statistics appear in the Heap pane. This data updates after every GC. You can also cause GC operations from the Heap pane using the button Cause GC.

4. On the Heap pane, you can choose a specific type of object. The resulting graph in use displays at the bottom of the Heap pane, as shown in Figure C.3.

Image

Figure C.3 Using the DDMS Heap pane.

Image Tip

When using the Allocation Tracker and Heap monitor, keep in mind that not all memory your app uses will be accounted for in this view. This tool shows the allocations within the Dalvik VM. Some calls allocate memory on the native heap. For example, many image manipulation calls in the SDK will result in memory allocated natively and not show up in this view.

Prompting Garbage Collection

You can use DDMS to force GC to run by following these steps:

1. On the emulator or device, verify that the application you want to run GC for is running.

2. In DDMS, find that application’s package name in the Devices pane and highlight it.

3. Click the garbage can button (Image) to cause GC to run for the application. The results can be viewed in the Heap pane.

Creating and Using an HPROF File

HPROF files can be used to inspect the heap and for profiling and performance purposes. You can use DDMS to create an HPROF file for your application by following these steps:

1. On the emulator or device, verify that the application you want the HPROF data for is running.

2. In DDMS, find that application’s package name in the Devices pane and highlight it.

3. Click the HPROF button (Image) to create an HPROF dump to be generated for the application. The files will be generated in the /data/misc/ directory.

For example, in Figure C.4, you can see the HPROF dump response in the Android IDE. You are switched to the Debug perspective, and a graphical trace is displayed.

Image

Figure C.4 Using the Android IDE to inspect HPROF profiling information.

Once you have Android-generated HPROF data, you can convert it to a standard HPROF file format using the Android SDK tool called hprof-conv. You can use whichever profiling tool you prefer to examine the information.

Image Note

You can generate HPROF files in Android using several other methods. For example, you can do it programmatically using the Debug class. The monkey tool also has options for generating HPROF files as it runs.

Using the Allocation Tracker

You can use DDMS to monitor memory allocated by a specific Android application. The memory allocation statistics are updated on demand by the developer. Follow these steps to track memory allocations:

1. On the emulator or device, verify that the application you want to monitor is running.

2. In DDMS, find that application’s package name in the Devices pane and highlight it.

3. Switch to the Allocation Tracker pane on the right pane.

4. Click the Start Tracking button to start tracking memory allocations and the Get Allocations button to get the allocations at a given time.

5. To stop tracking allocations, click the Stop Tracking button.

For example, in Figure C.5, we see the Allocation Tracker pane contents for an application running on the emulator.

Image

Figure C.5 Using the DDMS Allocation Tracker pane.

The Android developer website has a write-up on memory analysis at http://android-developers.blogspot.com/2011/03/memory-analysis-for-android.html.

Viewing Network Statistics

You can use DDMS to analyze the network usage of your applications. This tool is useful for providing information about when your application performs network data transfers. The Android class TrafficStats is used to add network statistics analysis code to your application. To distinguish among different types of data transfers in your application, you simply apply a TrafficStats tag in your code before executing the transfer. Knowing network statistics should help you make better decisions about how to optimize your network data transfer code. In Figure C.6, we see theNetwork Statistics pane contents for a Nexus 4 device.

Image

Figure C.6 Using the DDMS Network Statistics pane.

Working with the File Explorer

You can use DDMS to browse and interact with the Android file system on an emulator or device (although it’s somewhat limited on devices without root access). You can access application files, directories, and databases, as well as pull and push files to the Android system, provided you have the appropriate permissions.

For example, in Figure C.7, we see the File Explorer pane contents for the emulator.

Image

Figure C.7 Using the DDMS File Explorer pane.

Browsing the File System of an Emulator or Device

To browse the Android file system, follow these steps:

1. In DDMS, choose the emulator or device you want to browse in the Devices pane.

2. Switch to the File Explorer pane. You see a directory hierarchy.

3. Browse to a directory or file location.

Keep in mind that directory listings in the File Explorer might take a moment to update when contents change.

Image Note

Some device directories, such as the /data directory, might not be accessible from the DDMS File Explorer.

Table C.1 shows some important areas of the Android file system. Although the exact directories may vary from device to device, the directories listed are the most common.

Image

Table C.1 Important Directories in the Android File System

Copying Files from the Emulator or Device

You can use the File Explorer to copy files or directories from an emulator or a device file system to your computer by following these steps:

1. Using the File Explorer, browse to the file or directory to copy and highlight it.

2. From the top-right corner of the File Explorer, click the disk button with the arrow (Image) to pull the file from the device. Alternatively, you can pull down the drop-down menu next to the buttons and choose Pull File.

3. Type in the path where you want to save the file or directory on your computer and click Save.

Copying Files to the Emulator or Device

You can use the File Explorer to copy files to an emulator or a device file system from your computer by following these steps:

1. Using the File Explorer, browse to the file or directory to copy and highlight it.

2. From the top-right corner of the File Explorer, click the phone button with the arrow (Image) to push a file to the device. Alternatively, you can pull down the drop-down menu next to the buttons and choose Push File.

3. Select the file or directory on your computer and click Open.

Image Tip

The File Explorer also supports some drag-and-drop operations. This is the only way to push directories to the Android file system; however, copying directories to the Android file system is not recommended because there’s no delete option for them. You need to delete directories programmatically if you have the permissions to do so. Alternatively, the adb shell can be used with rmdir, but you still need permissions to do so. That said, you can drag a file or directory from your computer to the File Explorer and drop it in the location you want.

Deleting Files on the Emulator or Device

You can use the File Explorer to delete files (one at a time, and not directories) on the emulator or device file system. Follow these steps:

1. Using the File Explorer, browse to the file you want to delete and highlight it.

2. In the top-right corner of the File Explorer, click the red minus button (Image) to delete the file.

Image Warning

Be careful. There is no confirmation. The file is deleted immediately and is not recoverable.

Working with the Emulator Control

You can use DDMS to interact with instances of the emulator using the Emulator Control pane. You must select the emulator you want to interact with for the Emulator Control pane to work. You can use the Emulator Control pane to do the following:

Image Change telephony status

Image Simulate incoming voice calls

Image Simulate incoming SMS messages

Image Send a location fix (GPS coordinates)

Change Telephony Status

To simulate changing the telephony status using the Emulator Control pane (shown in Figure C.8), use the following steps:

1. In DDMS, choose the emulator whose telephony status you want to change.

2. Switch to the Emulator Control pane. You work with the Telephony Status.

3. Select the desired options from Voice, Speed, Data, and Latency.

4. For example, when changing the Data option from Home to Roaming, you should see a notification in the status bar that the device is now in roaming mode.

Image

Figure C.8 Using the DDMS Emulator Control pane.

Simulating Incoming Voice Calls

To simulate an incoming voice call using the Emulator Control pane (shown in Figure C.8), use the following steps:

1. In DDMS, choose the emulator you want to call in the Devices pane.

2. Switch to the Emulator Control pane. You work with the Telephony Actions.

3. Input the incoming phone number. This can include only numbers, +, and #.

4. Select the Voice radio button.

5. Click the Send button.

6. In the emulator, your phone is ringing. Answer the call.

7. The emulator can end the call as normal, or you can end the call in DDMS using the Hang Up button.

Simulating Incoming SMS Messages

DDMS provides the most stable method for sending incoming SMS messages to the emulator. You send an SMS much as you initiated the voice call. To simulate an incoming SMS message using the Emulator Control pane (shown in Figure C.8, top), use the following steps:

1. In DDMS, choose the emulator you want to send a message to in the Devices pane.

2. Switch to the Emulator Control pane. You work with the Telephony Actions.

3. Input the incoming phone number. This may include only numbers, +, and #.

4. Select the SMS radio button.

5. Type in your SMS message.

6. Click the Send button.

7. Over in the emulator, you receive an SMS notification.

Sending a Location Fix

The steps for sending GPS coordinates to the emulator are covered in Appendix B, “Quick-Start Guide: The Android Emulator.” Simply input the GPS information into the Emulator Control pane (shown in Figure C.8, bottom), click Send, and use the Maps application on the emulator to get the current position.

Working with the System Information Pane

You can use DDMS to analyze the system information of instances of the emulator using the System Information pane. You must select the emulator you want to analyze for the System Information pane to work. You can use the System Information pane like so:

1. In DDMS, choose the emulator or device you want to analyze.

2. Switch to the System Information pane.

3. Select from the drop-down the type of System Information you are interested in analyzing.

4. If the screen is blank, you may need to press the Update from Device button.

5. You should now see a chart displaying the System Information, as shown in Figure C.9.

Image

Figure C.9 Using the DDMS System Information pane.

Taking Screen Captures of the Emulator and Device Screens

You can take screen captures of the emulator and the device from DDMS. The device captures are most useful for debugging, and this makes the DDMS tool appropriate for quality assurance personnel and developers. To capture a screenshot, take the following steps:

1. In DDMS, choose the emulator or device you want to capture in the Devices pane.

2. On the device or emulator, make sure you have the screen you want to capture.

3. Click the multicolored square picture button (Image) to take a screen capture. A capture window launches, as shown in Figure C.10.

Image

Figure C.10 Using DDMS to take a screenshot.

4. Within the capture window, click the Save button to save the screen capture. Similarly, the Copy button stores the screenshot in your clipboard, the Refresh button updates the screenshot if the underlying device or emulator screen has changed since you launched the capture window, and the Rotate button rotates the screenshot 90 degrees.

Working with Application Logging

The LogCat tool is integrated into DDMS. It is provided as a pane along the bottom of the DDMS user interface. You can control how much information displays by choosing an option from the log type filter drop-down. The default option is verbose (show everything). The other options correspond to debug, info, warn, error, and assert. When selected, only log entries for that level of severity and worse will display. You can filter the LogCat results to show just search results by using the search entry field, which fully supports regular expressions. Search terms can be limited in scope with prefixes, such as text:, to limit the following term to just the log message text.

You can also create saved filters to display only the LogCat information associated with particular attributes. You can use the plus (+) button to add a saved filter and show only log entries matching a tag, message, process ID, name, or log level. The strings for each attribute filter can also be Java-style regular expressions.

For example, suppose your application does this:

public static final String DEBUG_TAG = "MyFirstAppLogging";
Log.i(DEBUG_TAG,
"In the onCreate() method of the MyFirstAndroidAppActivity Class.");

You can create a LogCat filter using the plus button (Image). Name the filter and set the log tag to the string matching your debug tag:

MyFirstAppLogging

The LogCat pane with the resulting filter is shown in Figure C.11.

Image

Figure C.11 Using the DDMS LogCat logging pane with a custom filter (top) and a regular expression search (bottom).

To search for the message if you don’t need to create a full tab, you could type in “MyFirst” and get all the results with tags and text fields containing this string.

Summary

In this appendix, you have learned many valuable features that DDMS provides. Many of the DDMS tools are available from within the Android IDE or as standalone applications. You learned that DDMS provides tools for monitoring your application’s performance while running on an emulator or a device. You also learned that DDMS allows you to interact directly with the file system of an emulator or a device. You should also feel comfortable interacting with an emulator or device, performing actions such as phone calls, SMS, taking screenshots, or even logging application data.

Quiz Questions

1. What is the name of the Android SDK directory where the command-line DDMS application resides?

2. True or false: The DDMS tab for sending GPS coordinates to a device or emulator is called the Emulator Control tab.

3. Name some of the tasks that you can perform with the Threads and Heap tabs.

4. What is the name of the class used for adding network statistics analysis code to your application?

5. True or false: The LogCat tool is not part of DDMS.

Exercises

1. Launch a sample application, on either an emulator or a device, using a Debug configuration, and practice analyzing the application using the various DDMS tabs.

2. Practice interacting with an emulator or device by sending calls, SMS messages, and GPS coordinates, and then take screen captures of each interaction using DDMS.

3. Practice adding log statements to a sample application, and then use LogCat to view the logging information.

References and More Information

Android Tools: “Using DDMS”:

http://d.android.com/tools/debugging/ddms.html

Android Reference: “TrafficStats”:

http://d.android.com/reference/android/net/TrafficStats.html

Android Tools: “Reading and Writing Logs”:

http://d.android.com/tools/debugging/debugging-log.html

Android Reference: “Log”:

http://d.android.com/reference/android/util/Log.html