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> 15 <ol> 16 <li><a href="#heap">Viewing heap usage for a process</a></li> 17 <li><a href="#alloc">Tracking memory allocation of objects</a></li> 18 <li><a href="#emulator">Working with an emulator or device's file system</a></li> 19 <li><a href="#thread">Examining thread information</a></li> 20 <li><a href="#profiling">Starting method profiling</a></li> 21 <li><a href="#network">Using the Network Traffic tool</a></li> 22 <li><a href="#logcat">Using LogCat</a></li> 23 <li><a href="#ops-location">Emulating phone operations and location</a></li> 24 </ol> 25 26 </li> 27 </ol> 28 </div> 29 </div> 30 31 <p>Android Studio includes a debugging tool called the Dalvik Debug Monitor Server (DDMS), which 32 provides port-forwarding services, screen capture on the device, thread and heap information on 33 the device, logcat, process, and radio state information, incoming call and SMS spoofing, 34 location data spoofing, and more. This page provides a modest discussion of DDMS features; it is 35 not an exhaustive exploration of all the features and capabilities.</p> 36 37 <h2 id="running">Running DDMS</h2> 38 <p>DDMS is integrated into Android Studio. To use it, launch the 39 <a href="{@docRoot}tools/help/monitor.html">Android Device Monitor</a>, and click the 40 <strong>DDMS</strong> menu button. DDMS works with both the emulator and a 41 connected device. If both are connected and running simultaneously, DDMS defaults to the emulator.</p> 42 43 44 <h2 id="how-ddms-works">How DDMS Interacts with a Debugger</h2> 45 46 <p>On Android, every application runs in its own process, each of which runs in its own virtual machine 47 (VM). Each VM exposes a unique port that a debugger can attach to.</p> 48 49 <p>When DDMS starts, it connects to <a href="{@docRoot}tools/help/adb.html">adb</a>. 50 When a device is connected, a VM monitoring service is created between 51 <code>adb</code> and DDMS, which notifies DDMS when a VM on the device is started or terminated. Once a VM 52 is running, DDMS retrieves the VM's process ID (pid), via <code>adb</code>, and opens a connection to the 53 VM's debugger, through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a 54 custom wire protocol.</p> 55 56 <p>DDMS assigns a debugging port to each VM on the device. Typically, 57 DDMS assigns port 8600 for the first debuggable VM, the next on 8601, and so on. When a debugger 58 connects to one of these ports, all traffic is forwarded to the debugger from the associated 59 VM. You can only attach a single debugger to a single port, but DDMS can handle multiple, attached 60 debuggers.</p> 61 62 <p>By default, DDMS also listens on another debugging port, the DDMS "base port" (8700, by default). 63 The base port is a port forwarder, which can accept VM traffic from any debugging port and forward 64 it to the debugger on port 8700. This allows you to attach one debugger to port 8700, and debug 65 all the VMs on a device. The traffic that is forwarded is determined by the currently selected process 66 in the DDMS Devices view.</p> 67 68 <p>The following screenshot shows a typical DDMS screen. If you are starting DDMS from 69 the command line, the screen is slightly different, but much of the functionality is identical. 70 Notice that the highlighted process, <code>com.android.email</code>, that is running in the emulator 71 has the debugging port 8700 assigned to it as well as 8606. This signifies that DDMS is currently 72 forwarding port 8606 to the static debugging port of 8700.</p> 73 74 <img src="{@docRoot}images/debug-ddms.png" 75 width="1024" /> 76 <p class="img-caption"><strong>Figure 1.</strong> 77 Screenshot of DDMS</p> 78 79 <p>If you are using the command line, read <a href= 80 "{@docRoot}tools/debugging/debugging-projects-cmdline.html#debuggingPort">Configuring 81 your IDE to attach to the debugging port</a>, for more information on attaching your 82 debugger.</p> 83 84 <p class="note"><strong>Tip:</strong> You can set a number of DDMS preferences in 85 <strong>File</strong> > <strong>Preferences</strong>. Preferences are saved to 86 <code>$HOME/.android/ddms.cfg</code>.</p> 87 88 <p class="warning"><strong>Known debugging issues with Dalvik</strong><br /> 89 Debugging an application in the Dalvik VM should work the same as it does in other VMs. However, 90 when single-stepping out of synchronized code, the "current line" cursor may jump to the last 91 line in the method for one step.</p> 92 93 <h2 id="using-ddms">Using DDMS</h2> 94 The following sections describe how to use DDMS and the various tabs and panes that are part of the 95 DDMS GUI. The Android Studio version and the command line version have minor UI differences, but 96 the same functionality. For information on running DDMS, see the previous section in this document, 97 <a href="#running">Running DDMS</a>. 98 99 100 <h3 id="heap">Viewing heap usage for a process</h3> 101 102 <p>DDMS allows you to view how much heap memory a process is using. This information is useful in 103 tracking heap usage at a certain point of time during the execution of your application.</p> 104 <p>To view heap usage for a process:</p> 105 <ol> 106 <li>In the Devices tab, select the process that you want to see the heap information for.</li> 107 108 <li>Click the <strong>Update Heap</strong> button to enable heap information for the 109 process.</li> 110 111 <li>In the Heap tab, click <strong>Cause GC</strong> to invoke garbage collection, which 112 enables the collection of heap data. When the operation completes, you will see a group of 113 object types and the memory that has been allocated for each type. You can click <strong>Cause 114 GC</strong> again to refresh the data.</li> 115 116 <li>Click on an object type in the list to see a bar graph that shows the number of objects 117 allocated for a particular memory size in bytes.</li> 118 </ol> 119 120 <h3 id="alloc">Tracking memory allocation of objects</h3> 121 122 <p>DDMS provides a feature to track objects that are being allocated to memory and to see which 123 classes and threads are allocating the objects. This allows you to track, in real time, where 124 objects are being allocated when you perform certain actions in your application. This 125 information is valuable for assessing memory usage that can affect application performance. 126 </p> 127 128 <p>To track memory allocation of objects:</p> 129 <ol> 130 <li>In the Devices tab, select the process that you want to enable allocation tracking 131 for.</li> 132 133 <li>In the Allocation Tracker tab, click the <strong>Start Tracking</strong> button to begin 134 allocation tracking. At this point, anything you do in your application will be tracked.</li> 135 136 <li>Click <strong>Get Allocations</strong> to see a list of objects that have been allocated 137 since you clicked on the <strong>Start Tracking</strong> button. You can click on <strong>Get 138 Allocations</strong> again to append to the list new objects that have been 139 allocated.</li> 140 141 <li>To stop tracking or to clear the data and start over, click the <strong>Stop Tracking 142 button</strong>.</li> 143 144 <li>Click on a specific row in the list to see more detailed information such as the method and 145 line number of the code that allocated the object.</li> 146 </ol> 147 148 <h3 id="emulator">Working with an emulator or device's file system</h3> 149 150 <p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the 151 device. This feature is useful in examining files that are created by your application or if you 152 want to transfer files to and from the device.</p> 153 154 <p>To work with an emulator or device's file system:</p> 155 <ol> 156 <li>In the Devices tab, select the emulator that you want to view the file system for.</li> 157 158 <li>To copy a file from the device, locate the file in the File Explorer and click the 159 <strong>Pull file</strong> button.</li> 160 161 <li>To copy a file to the device, click the <strong>Push file</strong> button on the File 162 Explorer tab.</li> 163 </ol> 164 165 <!-- Need to elaborate more on where things are stored in the file system, 166 databases, apks, user info, files that are important to look at --> 167 168 <h3 id="thread">Examining thread information</h3> 169 170 <p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p> 171 172 <ol> 173 <li>In the Devices tab, select the process that you want to examine the threads for.</li> 174 175 <li>Click the <strong>Update Threads</strong> button.</li> 176 177 <li>In the Threads tab, you can view the thread information for the selected process.</li> 178 </ol> 179 180 <h3 id="profiling">Starting method profiling</h3> 181 182 <p>Method profiling is a means to track certain metrics about a method, such as number of calls, 183 execution time, and time spent executing the method. If you want more granular control over 184 where profiling data is collected, use the {@link android.os.Debug#startMethodTracing()} and 185 {@link android.os.Debug#stopMethodTracing()} methods. For more information about generating trace logs, see 186 <a href="debugging-tracing.html">Profiling and Debugging UIs</a>.</p> 187 188 <p>Before you start method profiling in DDMS, be aware of the following restrictions:</p> 189 <ul> 190 <li>Android 2.1 and earlier devices must 191 have an SD card present and your application must have permission to write to the SD card. 192 <li>Android 2.2 and later devices do not need an SD card. The trace log files are 193 streamed directly to your development machine.</li> 194 </ul> 195 196 <p>To start method profiling:</p> 197 <ol> 198 <li>On the Devices tab, select the process that you want to enable method profiling for.</li> 199 200 <li>Click the <strong>Start Method Profiling</strong> button.</li> 201 202 <li>In Android 4.4 and later, choose either trace-based profiling or sample-based profiling 203 with a specified sampling interval. For earlier versions of Android, only trace-based profiling 204 is available.</li> 205 206 <li>Interact with your application to start the methods that you want to profile.</li> 207 208 <li>Click the <strong>Stop Method Profiling</strong> button. DDMS stops profiling your 209 application and opens <a href="{@docRoot}tools/debugging/debugging-ui.html">Traceview</a> 210 with the method profiling information that was collected 211 between the time you clicked on <strong>Start Method Profiling</strong> and <strong>Stop Method 212 Profiling</strong>.</li> 213 </ol> 214 215 <h3 id="network">Using the Network Traffic tool</h3> 216 217 <p>In Android 4.0, the DDMS (Dalvik Debug Monitor Server) includes a Detailed 218 Network Usage tab that makes it possible to track when your application is 219 making network requests. Using this tool, you can monitor how and when your app 220 transfers data and optimize the underlying code appropriately. You can also 221 distinguish between different traffic types by applying a tag to network 222 sockets before use.</p> 223 224 <p>These tags are shown in a stack area chart in DDMS, as shown in figure 2:</p> 225 226 <img src="{@docRoot}images/developing/ddms-network.png" /> 227 <p class="img-caption"><strong>Figure 2.</strong> Network Usage tab.</p> 228 229 <p>By monitoring the frequency of your data transfers, and the amount of data 230 transferred during each connection, you can identify areas of your application 231 that can be made more battery-efficient. Generally, you should look for 232 short spikes that can be delayed, or that should cause a later transfer to be 233 pre-empted. </p> 234 235 <p>To better identify the cause of transfer spikes, the 236 {@link android.net.TrafficStats} API allows you 237 to tag the data transfers occurring within a thread using {@link 238 android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}, followed 239 by manually tagging (and untagging) individual sockets using {@link 240 android.net.TrafficStats#tagSocket tagSocket()} and {@link 241 android.net.TrafficStats#untagSocket untagSocket()}. For example:</p> 242 243 <pre>TrafficStats.setThreadStatsTag(0xF00D); 244 TrafficStats.tagSocket(outputSocket); 245 // Transfer data using socket 246 TrafficStats.untagSocket(outputSocket);</pre> 247 248 <p>Alternatively, the {@link java.net.URLConnection} APIs included in the platform 249 automatically tag sockets internally based on the active tag (as identified by 250 {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}). 251 These APIs correctly tag/untag sockets when recycled through 252 keep-alive pools. In the following example, 253 {@link android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()} 254 sets the active tag to be {@code 0xF00D}. 255 There can only be one active tag per thread. 256 That is the value that will 257 be returned by {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()} 258 and thus used by the HTTP client to tag sockets. The {@code finally} statement 259 invokes 260 {@link android.net.TrafficStats#clearThreadStatsTag clearThreadStatsTag()} 261 to clear the tag.</p> 262 263 <pre>TrafficStats.setThreadStatsTag(0xF00D); 264 try { 265 // Make network request using your http client. 266 } finally { 267 TrafficStats.clearThreadStatsTag(); 268 }</pre> 269 270 <p>Socket tagging is supported in Android 4.0, but real-time stats will only be 271 displayed on devices running Android 4.0.3 or higher.</p> 272 273 <h3 id="logcat">Using LogCat</h3> 274 275 <p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log} 276 class along with other system messages such as stack traces when exceptions are thrown. View the 277 <a href="{@docRoot}tools/debugging/debugging-log.html">Reading and 278 Writing Log Messages.</a> topic for more information on how to log messages to the LogCat.</p> 279 280 <p>When you have set up your logging, you can use the LogCat feature of DDMS to filter certain 281 messages with the following buttons:</p> 282 283 <ul> 284 <li>Verbose</li> 285 286 <li>Debug</li> 287 288 <li>Info</li> 289 290 <li>Warn</li> 291 292 <li>Error</li> 293 </ul> 294 295 <p>You can also setup your own custom filter to specify more details such as filtering messages 296 with the log tags or with the process id that generated the log message. The add filter, 297 edit filter, and delete filter buttons let you manage your custom filters.</p> 298 299 <h3 id="ops-location">Emulating phone operations and location</h3> 300 <p>The Emulator control tab lets you simulate a 301 phone's voice and data network status. This is useful when you want to test your application's 302 robustness in differing network environments.</p> 303 304 <h4>Changing network state, speed, and latency</h4> 305 <p>The Telephony Status section of the Emulator 306 controls tab lets you change different aspects of the phone's networks status, speed and latency. 307 The following options are available to you and are effective immediately after you set them:</p> 308 309 <ul> 310 <li>Voice - unregistered, home, roaming, searching, denied</li> 311 312 <li>Data - unregistered, home, roaming, searching, denied</li> 313 314 <li>Speed - Full, GSM, HSCSD, GPRS, EDGE, UMTS, HSDPA</li> 315 316 <li>Latency - GPRS, EDGE, UMTS</li> 317 </ul> 318 319 <h4>Spoofing calls or SMS text messages</h4> 320 <p>The Telephony Actions section of the Emulator 321 controls tab lets you spoof calls and messages. This is useful when you want to to test your 322 application's robustness in responding to incoming calls and messages that are sent to the phone. 323 The following actions are available to you:</p> 324 325 <ul> 326 <li>Voice - Enter a number in the <strong>Incoming number</strong> field and click 327 <strong>Call</strong> to send a simulated call to the emulator or phone. Click the 328 <strong>Hang up</strong> button to terminate the call.</li> 329 330 <li>SMS - Enter a number in the <strong>Incoming number</strong> field and a message in the 331 <strong>Message:</strong> field and click the <strong>Send</strong> button to send the 332 message.</li> 333 </ul> 334 335 <h4>Setting the location of the phone</h4> 336 <p>If your application depends on the location of the phone, you can have DDMS send your 337 device or AVD a mock location. This is useful if you 338 want to test different aspects of your application's location specific features without 339 physically moving. The following geolocation data types are available to you:</p> 340 341 <ul> 342 <li>Manual - set the location by manually specifying decimal or sexagesimal longitude and 343 latitude values.</li> 344 345 <li>GPX - GPS eXchange file</li> 346 347 <li>KML - Keyhole Markup Language file</li> 348 </ul> 349 350 For more information about providing mock location data, see 351 <a href="{@docRoot}guide/topics/location/strategies.html#MockData">Location Strategies</a>. 352 353
