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