1 page.title=Using DDMS 2 parent.title=Debugging 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 10 <ol> 11 <li><a href="#running">Running DDMS</a></li> 12 <li><a href="#how-ddms-works">How DDMS Interacts with a Debugger</a></li> 13 14 <li><a href="#using-ddms">Using DDMS</a></li> 15 </ol> 16 </div> 17 </div> 18 19 <p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), which 20 provides port-forwarding services, screen capture on the device, thread and heap information on 21 the device, logcat, process, and radio state information, incoming call and SMS spoofing, 22 location data spoofing, and more. This page provides a modest discussion of DDMS features; it is 23 not an exhaustive exploration of all the features and capabilities.</p> 24 25 <h2 id="running">Running DDMS</h2> 26 <p>DDMS is integrated into Eclipse and is also shipped in the <code>tools/</code> directory of the 27 SDK. DDMS works with both the emulator and a connected device. If both are connected and running simultaneously, 28 DDMS defaults to the emulator.</p> 29 30 <ul> 31 <li>From Eclipse: Click <strong>Window > Open Perspective > Other... > DDMS</strong>.</li> 32 <li>From the command line: Type <code>ddms</code> (or <code>./ddms</code> on Mac/Linux) from the <code>tools/</code> 33 directory. </li> 34 </ul> 35 36 37 <h2 id="how-ddms-works">How DDMS Interacts with a Debugger</h2> 38 39 <p>On Android, every application runs in its own process, each of which runs in its own virtual machine 40 (VM). Each VM exposes a unique port that a debugger can attach to.</p> 41 42 <p>When DDMS starts, it connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a>. 43 When a device is connected, a VM monitoring service is created between 44 <code>adb</code> and DDMS, which notifies DDMS when a VM on the device is started or terminated. Once a VM 45 is running, DDMS retrieves the the VM's process ID (pid), via <code>adb</code>, and opens a connection to the 46 VM's debugger, through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a 47 custom wire protocol.</p> 48 49 <p>DDMS assigns a debugging port to each VM on the device. Typically, 50 DDMS assigns port 8600 for the first debuggable VM, the next on 8601, and so on. When a debugger 51 connects to one of these ports, all traffic is forwarded to the debugger from the associated 52 VM. You can only attach a single debugger to a single port, but DDMS can handle multiple, attached 53 debuggers.</p> 54 55 <p>By default, DDMS also listens on another debugging port, the DDMS "base port" (8700, by default). 56 The base port is a port forwarder, which can accept VM traffic from any debugging port and forward 57 it to the debugger on port 8700. This allows you to attach one debugger to port 8700, and debug 58 all the VMs on a device. The traffic that is forwarded is determined by the currently selected process 59 in the DDMS Devices view.</p> 60 61 <p>The following screenshot shows a typical DDMS screen in Eclipse. If you are starting DDMS from 62 the command line, the screen is slightly different, but much of the functionality is identical. 63 Notice that the highlighted process, <code>com.android.email</code>, that is running in the emulator 64 has the debugging port 8700 assigned to it as well as 8606. This signifies that DDMS is currently 65 forwarding port 8606 to the static debugging port of 8700.</p> 66 67 <img src="{@docRoot}images/debug-ddms.png" 68 width="1024" /> 69 <p class="img-caption"><strong>Figure 1.</strong> 70 Screenshot of DDMS</p> 71 72 <p>If you are not using Eclipse and ADT, read <a href= 73 "{@docRoot}guide/developing/debugging/debugging-projects-cmdline.html#debuggingPort">Configuring 74 your IDE to attach to the debugging port</a>, for more information on attaching your 75 debugger.</p> 76 77 <p class="note"><strong>Tip:</strong> You can set a number of DDMS preferences in 78 <strong>File</strong> > <strong>Preferences</strong>. Preferences are saved to 79 <code>$HOME/.android/ddms.cfg</code>.</p> 80 81 <p class="warning"><strong>Known debugging issues with Dalvik</strong><br /> 82 Debugging an application in the Dalvik VM should work the same as it does in other VMs. However, 83 when single-stepping out of synchronized code, the "current line" cursor may jump to the last 84 line in the method for one step.</p> 85 86 <h2 id="using-ddms">Using DDMS</h2> 87 The following sections describe how to use DDMS and the various tabs and panes that are part of the 88 DDMS GUI. The Eclipse version and the command line version have minor UI differences, but the 89 same functionality. For information on running DDMS, see the previous section in this document, 90 <a href="#running">Running DDMS</a>. 91 92 93 <h3>Viewing heap usage for a process</h3> 94 95 <p>DDMS allows you to view how much heap memory a process is using. This information is useful in 96 tracking heap usage at a certain point of time during the execution of your application.</p> 97 <p>To view heap usage for a process:</p> 98 <ol> 99 <li>In the Devices tab, select the process that you want to see the heap information for.</li> 100 101 <li>Click the <strong>Update Heap</strong> button to enable heap information for the 102 process.</li> 103 104 <li>In the Heap tab, click <strong>Cause GC</strong> to invoke garbage collection, which 105 enables the collection of heap data. When the operation completes, you will see a group of 106 object types and the memory that has been allocated for each type. You can click <strong>Cause 107 GC</strong> again to refresh the data.</li> 108 109 <li>Click on an object type in the list to see a bar graph that shows the number of objects 110 allocated for a particular memory size in bytes.</li> 111 </ol> 112 113 <h3>Tracking memory allocation of objects</h3> 114 115 <p>DDMS provides a feature to track objects that are being allocated to memory and to see which 116 classes and threads are allocating the objects. This allows you to track, in real time, where 117 objects are being allocated when you perform certain actions in your application. This 118 information is valuable for assessing memory usage that can affect application performance. 119 If you want more granular control over where allocation data is collected, use the 120 {@link android.os.Debug#startAllocCounting()} and {@link android.os.Debug#stopAllocCounting()} 121 methods.</p> 122 123 <p>To track memory allocation of objects:</p> 124 <ol> 125 <li>In the Devices tab, select the process that you want to enable allocation tracking 126 for.</li> 127 128 <li>In the Allocation Tracker tab, click the <strong>Start Tracking</strong> button to begin 129 allocation tracking. At this point, anything you do in your application will be tracked.</li> 130 131 <li>Click <strong>Get Allocations</strong> to see a list of objects that have been allocated 132 since you clicked on the <strong>Start Tracking</strong> button. You can click on <strong>Get 133 Allocations</strong> again to append to the list new objects that that have been 134 allocated.</li> 135 136 <li>To stop tracking or to clear the data and start over, click the <strong>Stop Tracking 137 button</strong>.</li> 138 139 <li>Click on a specific row in the list to see more detailed information such as the method and 140 line number of the code that allocated the object.</li> 141 </ol> 142 143 <h3>Working with an emulator or device's file system</h3> 144 145 <p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the 146 device. This feature is useful in examining files that are created by your application or if you 147 want to transfer files to and from the device.</p> 148 149 <p>To work with an emulator or device's file system:</p> 150 <ol> 151 <li>In the Devices tab, select the emulator that you want to view the file system for.</li> 152 153 <li>To copy a file from the device, locate the file in the File Explorer and click the 154 <strong>Pull file</strong> button.</li> 155 156 <li>To copy a file to the device, click the <strong>Push file</strong> button on the File 157 Explorer tab.</li> 158 </ol> 159 160 <!-- Need to elaborate more on where things are stored in the file system, 161 databases, apks, user info, files that are important to look at --> 162 163 <h3>Examining thread information</h3> 164 165 <p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p> 166 167 <ol> 168 <li>In the Devices tab, select the process that you want to examine the threads for.</li> 169 170 <li>Click the <strong>Update Threads</strong> button.</li> 171 172 <li>In the Threads tab, you can view the thread information for the selected process.</li> 173 </ol> 174 175 <h3 id="profiling">Starting method profiling</h3> 176 177 <p>Method profiling is a means to track certain metrics about a method, such as number of calls, 178 execution time, and time spent executing the method. If you want more granular control over 179 where profiling data is collected, use the {@link android.os.Debug#startMethodTracing()} and 180 {@link android.os.Debug#stopMethodTracing()} methods. For more information about generating trace logs, see 181 <a href="debugging-tracing.html">Profiling and Debugging UIs</a>.</p> 182 183 <p>Before you start method profiling in DDMS, be aware of the following restrictions:</p> 184 <ul> 185 <li>Android 1.5 devices are not supported.</li> 186 <li>Android 2.1 and earlier devices must 187 have an SD card present and your application must have permission to write to the SD card. 188 <li>Android 2.2 and later devices do not need an SD card. The trace log files are 189 streamed directly to your development machine.</li> 190 </ul> 191 192 <p>To start method profiling:</p> 193 <ol> 194 <li>On the Devices tab, select the process that you want to enable method profiling for.</li> 195 196 <li>Click the <strong>Start Method Profiling</strong> button.</li> 197 198 <li>Interact with your application to start the methods that you want to profile.</li> 199 200 <li>Click the <strong>Stop Method Profiling</strong> button. DDMS stops profiling your 201 application and opens <a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Traceview</a> 202 with the method profiling information that was collected 203 between the time you clicked on <strong>Start Method Profiling</strong> and <strong>Stop Method 204 Profiling</strong>.</li> 205 </ol> 206 207 <h3 id="logcat">Using LogCat</h3> 208 209 <p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log} 210 class along with other system messages such as stack traces when exceptions are thrown. View the 211 <a href="{@docRoot}guide/developing/debugging/debugging-log.html">Reading and 212 Writing Log Messages.</a> topic for more information on how to log messages to the LogCat.</p> 213 214 <p>When you have set up your logging, you can use the LogCat feature of DDMS to filter certain 215 messages with the following buttons:</p> 216 217 <ul> 218 <li>Verbose</li> 219 220 <li>Debug</li> 221 222 <li>Info</li> 223 224 <li>Warn</li> 225 226 <li>Error</li> 227 </ul> 228 229 <p>You can also setup your own custom filter to specify more details such as filtering messages 230 with the log tags or with the process id that generated the log message. The add filter, 231 edit filter, and delete filter buttons let you manage your custom filters.</p> 232 233 <h3>Emulating phone operations and location</h3> 234 <p>The Emulator control tab lets you simulate a 235 phone's voice and data network status. This is useful when you want to test your application's 236 robustness in differing network environments.</p> 237 238 <h4>Changing network state, speed, and latency</h4> 239 <p>The Telephony Status section of the Emulator 240 controls tab lets you change different aspects of the phone's networks status, speed and latency. 241 The following options are available to you and are effective immediately after you set them:</p> 242 243 <ul> 244 <li>Voice - unregistered, home, roaming, searching, denied</li> 245 246 <li>Data - unregistered, home, roaming, searching, denied</li> 247 248 <li>Speed - Full, GSM, HSCSD, GPRS, EDGE, UMTS, HSDPA</li> 249 250 <li>Latency - GPRS, EDGE, UMTS</li> 251 </ul> 252 253 <h4>Spoofing calls or SMS text messages</h4> 254 <p>The Telephony Actions section of the Emulator 255 controls tab lets you spoof calls and messages. This is useful when you want to to test your 256 application's robustness in responding to incoming calls and messages that are sent to the phone. 257 The following actions are available to you:</p> 258 259 <ul> 260 <li>Voice - Enter a number in the <strong>Incoming number</strong> field and click 261 <strong>Call</strong> to send a simulated call to the emulator or phone. Click the 262 <strong>Hang up</strong> button to terminate the call.</li> 263 264 <li>SMS - Enter a number in the <strong>Incoming number</strong> field and a message in the 265 <strong>Message:</strong> field and click the <strong>Send</strong> button to send the 266 message.</li> 267 </ul> 268 269 <h4>Setting the location of the phone</h4> 270 <p>If your application depends on the location of the phone, you can have DDMS send your 271 device or AVD a mock location. This is useful if you 272 want to test different aspects of your application's location specific features without 273 physically moving. The following geolocation data types are available to you:</p> 274 275 <ul> 276 <li>Manual - set the location by manually specifying decimal or sexagesimal longitude and 277 latitude values.</li> 278 279 <li>GPX - GPS eXchange file</li> 280 281 <li>KML - Keyhole Markup Language file</li> 282 </ul> 283 284 For more information about providing mock location data, see 285 <a href="{@docRoot}guide/topics/location/obtaining-user-location.html#MockData">Obtaining User Location</a>. 286 287
