285 lines
13 KiB
Plaintext
285 lines
13 KiB
Plaintext
page.title=Using DDMS
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
<h2>In this document</h2>
|
|
|
|
<ol>
|
|
<li><a href="#running">Running DDMS</a></li>
|
|
<li><a href="#how-ddms-works">How DDMS Interacts with a Debugger</a></li>
|
|
|
|
<li><a href="#using-ddms">Using DDMS</a></li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
|
|
<p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), which
|
|
provides port-forwarding services, screen capture on the device, thread and heap information on
|
|
the device, logcat, process, and radio state information, incoming call and SMS spoofing,
|
|
location data spoofing, and more. This page provides a modest discussion of DDMS features; it is
|
|
not an exhaustive exploration of all the features and capabilities.</p>
|
|
|
|
<h2 id="running">Running DDMS</h2>
|
|
<p>DDMS is integrated into Eclipse and is also shipped in the <code>tools/</code> directory of the
|
|
SDK. DDMS works with both the emulator and a connected device. If both are connected and running simultaneously,
|
|
DDMS defaults to the emulator.</p>
|
|
|
|
<ul>
|
|
<li>From Eclipse: Click <strong>Window > Open Perspective > Other... > DDMS</strong>.</li>
|
|
<li>From the command line: Type <code>ddms</code> (or <code>./ddms</code> on Mac/Linux) from the <code>tools/</code>
|
|
directory. </li>
|
|
</ul>
|
|
|
|
|
|
<h2 id="how-ddms-works">How DDMS Interacts with a Debugger</h2>
|
|
|
|
<p>On Android, every application runs in its own process, each of which runs in its own virtual machine
|
|
(VM). Each VM exposes a unique port that a debugger can attach to.</p>
|
|
|
|
<p>When DDMS starts, it connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a>.
|
|
When a device is connected, a VM monitoring service is created between
|
|
<code>adb</code> and DDMS, which notifies DDMS when a VM on the device is started or terminated. Once a VM
|
|
is running, DDMS retrieves the the VM's process ID (pid), via <code>adb</code>, and opens a connection to the
|
|
VM's debugger, through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a
|
|
custom wire protocol.</p>
|
|
|
|
<p>DDMS assigns a debugging port to each VM on the device. Typically,
|
|
DDMS assigns port 8600 for the first debuggable VM, the next on 8601, and so on. When a debugger
|
|
connects to one of these ports, all traffic is forwarded to the debugger from the associated
|
|
VM. You can only attach a single debugger to a single port, but DDMS can handle multiple, attached
|
|
debuggers.</p>
|
|
|
|
<p>By default, DDMS also listens on another debugging port, the DDMS "base port" (8700, by default).
|
|
The base port is a port forwarder, which can accept VM traffic from any debugging port and forward
|
|
it to the debugger on port 8700. This allows you to attach one debugger to port 8700, and debug
|
|
all the VMs on a device. The traffic that is forwarded is determined by the currently selected process
|
|
in the DDMS Devices view.</p>
|
|
|
|
<p>The following screenshot shows a typical DDMS screen in Eclipse. If you are starting DDMS from
|
|
the command line, the screen is slightly different, but much of the functionality is identical.
|
|
Notice that the highlighted process, <code>com.example.android.notepad</code>, that is running in the emulator
|
|
has the debugging port 8700 assigned to it as well as 8609. This signifies that DDMS is currently
|
|
forwarding port 8609 to the static debugging port of 8700.</p>
|
|
|
|
<img src="{@docRoot}images/debug-ddms.png"
|
|
width="1024" />
|
|
<p class="img-caption"><strong>Figure 1.</strong>
|
|
Screenshot of DDMS</p>
|
|
|
|
<p>If you are not using Eclipse and ADT, read <a href=
|
|
"{@docRoot}guide/developing/debugging/debugging-projects-cmdline.html#debuggingPort">Configuring
|
|
your IDE to attach to the debugging port</a>, for more information on attaching your
|
|
debugger.</p>
|
|
|
|
<p class="note"><strong>Tip:</strong> You can set a number of DDMS preferences in
|
|
<strong>File</strong> > <strong>Preferences</strong>. Preferences are saved to
|
|
<code>$HOME/.ddmsrc</code>.</p>
|
|
|
|
<p class="warning"><strong>Known debugging issues with Dalvik</strong><br />
|
|
Debugging an application in the Dalvik VM should work the same as it does in other VMs. However,
|
|
when single-stepping out of synchronized code, the "current line" cursor may jump to the last
|
|
line in the method for one step.</p>
|
|
|
|
<h2 id="using-ddms">Using DDMS</h2>
|
|
The following sections describe how to use DDMS and the various tabs and panes that are part of the
|
|
DDMS GUI. The Eclipse version and the command line version have minor UI differences, but the
|
|
same functionality. For information on running DDMS, see the previous section in this document,
|
|
<a href="#running">Running DDMS</a>.
|
|
|
|
|
|
<h3>Viewing heap usage for a process</h3>
|
|
|
|
<p>DDMS allows you to view how much heap memory a process is using. This information is useful in
|
|
tracking heap usage at a certain point of time during the execution of your application.</p>
|
|
<p>To view heap usage for a process:</p>
|
|
<ol>
|
|
<li>In the Devices tab, select the process that you want to see the heap information for.</li>
|
|
|
|
<li>Click the <strong>Update Heap</strong> button to enable heap information for the
|
|
process.</li>
|
|
|
|
<li>In the Heap tab, click <strong>Cause GC</strong> to invoke garbage collection, which
|
|
enables the collection of heap data. When the operation completes, you will see a group of
|
|
object types and the memory that has been allocated for each type. You can click <strong>Cause
|
|
GC</strong> again to refresh the data.</li>
|
|
|
|
<li>Click on an object type in the list to see a bar graph that shows the number of objects
|
|
allocated for a particular memory size in bytes.</li>
|
|
</ol>
|
|
|
|
<h3>Tracking memory allocation of objects</h3>
|
|
|
|
<p>DDMS provides a feature to track objects that are being allocated to memory and to see which
|
|
classes and threads are allocating the objects. This allows you to track, in real time, where
|
|
objects are being allocated when you perform certain actions in your application. This
|
|
information is valuable for assessing memory usage that can affect application performance.
|
|
If you want more granular control over where allocation data is collected, use the
|
|
{@link android.os.Debug#startAllocCounting()} and {@link android.os.Debug#stopAllocCounting()}
|
|
methods.</p>
|
|
|
|
<p>To track memory allocation of objects:</p>
|
|
<ol>
|
|
<li>In the Devices tab, select the process that you want to enable allocation tracking
|
|
for.</li>
|
|
|
|
<li>In the Allocation Tracker tab, click the <strong>Start Tracking</strong> button to begin
|
|
allocation tracking. At this point, anything you do in your application will be tracked.</li>
|
|
|
|
<li>Click <strong>Get Allocations</strong> to see a list of objects that have been allocated
|
|
since you clicked on the <strong>Start Tracking</strong> button. You can click on <strong>Get
|
|
Allocations</strong> again to append to the list new objects that that have been
|
|
allocated.</li>
|
|
|
|
<li>To stop tracking or to clear the data and start over, click the <strong>Stop Tracking
|
|
button</strong>.</li>
|
|
|
|
<li>Click on a specific row in the list to see more detailed information such as the method and
|
|
line number of the code that allocated the object.</li>
|
|
</ol>
|
|
|
|
<h3>Working with an emulator or device's file system</h3>
|
|
|
|
<p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the
|
|
device. This feature is useful in examining files that are created by your application or if you
|
|
want to transfer files to and from the device.</p>
|
|
|
|
<p>To work with an emulator or device's file system:</p>
|
|
<ol>
|
|
<li>In the Devices tab, select the emulator that you want to view the file system for.</li>
|
|
|
|
<li>To copy a file from the device, locate the file in the File Explorer and click the
|
|
<strong>Pull file</strong> button.</li>
|
|
|
|
<li>To copy a file to the device, click the <strong>Push file</strong> button on the File
|
|
Explorer tab.</li>
|
|
</ol>
|
|
|
|
<!-- Need to elaborate more on where things are stored in the file system,
|
|
databases, apks, user info, files that are important to look at -->
|
|
|
|
<h3>Examining thread information</h3>
|
|
|
|
<p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p>
|
|
|
|
<ol>
|
|
<li>In the Devices tab, select the process that you want to examine the threads for.</li>
|
|
|
|
<li>Click the <strong>Update Threads</strong> button.</li>
|
|
|
|
<li>In the Threads tab, you can view the thread information for the selected process.</li>
|
|
</ol>
|
|
|
|
<h3 id="profiling">Starting method profiling</h3>
|
|
|
|
<p>Method profiling is a means to track certain metrics about a method, such as number of calls,
|
|
execution time, and time spent executing the method. If you want more granular control over
|
|
where profiling data is collected, use the {@link android.os.Debug#startMethodTracing()} and
|
|
{@link android.os.Debug#stopMethodTracing()} methods. For more information about generating trace logs, see
|
|
<a href="debugging-tracing.html">Profiling and Debugging UIs</a>.</p>
|
|
|
|
<p>Before you start method profiling in DDMS, be aware of the following restrictions:</p>
|
|
<ul>
|
|
<li>Android 1.5 devices are not supported.</li>
|
|
<li>Android 2.1 and earlier devices must
|
|
have an SD card present and your application must have permission to write to the SD card.
|
|
<li>Android 2.2 and later devices do not need an SD card. The trace log files are
|
|
streamed directly to your development machine.</li>
|
|
</ul>
|
|
|
|
<p>To start method profiling:</p>
|
|
<ol>
|
|
<li>On the Devices tab, select the process that you want to enable method profiling for.</li>
|
|
|
|
<li>Click the <strong>Start Method Profiling</strong> button.</li>
|
|
|
|
<li>Interact with your application to start the methods that you want to profile.</li>
|
|
|
|
<li>Click the <strong>Stop Method Profiling</strong> button. DDMS stops profiling your
|
|
application and opens <a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Traceview</a>
|
|
with the method profiling information that was collected
|
|
between the time you clicked on <strong>Start Method Profiling</strong> and <strong>Stop Method
|
|
Profiling</strong>.</li>
|
|
</ol>
|
|
|
|
<h3 id="logcat">Using LogCat</h3>
|
|
|
|
<p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log}
|
|
class along with other system messages such as stack traces when exceptions are thrown. View the
|
|
<a href="{@docRoot}guide/developing/debugging/debugging-log.html">Reading and
|
|
Writing Log Messages.</a> topic for more information on how to log messages to the LogCat.</p>
|
|
|
|
<p>When you have set up your logging, you can use the LogCat feature of DDMS to filter certain
|
|
messages with the following buttons:</p>
|
|
|
|
<ul>
|
|
<li>Verbose</li>
|
|
|
|
<li>Debug</li>
|
|
|
|
<li>Info</li>
|
|
|
|
<li>Warn</li>
|
|
|
|
<li>Error</li>
|
|
</ul>
|
|
|
|
<p>You can also setup your own custom filter to specify more details such as filtering messages
|
|
with the log tags or with the process id that generated the log message. The add filter,
|
|
edit filter, and delete filter buttons let you manage your custom filters.</p>
|
|
|
|
<h3>Emulating phone operations and location</h3>
|
|
<p>The Emulator control tab lets you simulate a
|
|
phone's voice and data network status. This is useful when you want to test your application's
|
|
robustness in differing network environments.</p>
|
|
|
|
<h4>Changing network state, speed, and latency</h4>
|
|
<p>The Telephony Status section of the Emulator
|
|
controls tab lets you change different aspects of the phone's networks status, speed and latency.
|
|
The following options are available to you and are effective immediately after you set them:</p>
|
|
|
|
<ul>
|
|
<li>Voice - unregistered, home, roaming, searching, denied</li>
|
|
|
|
<li>Data - unregistered, home, roaming, searching, denied</li>
|
|
|
|
<li>Speed - Full, GSM, HSCSD, GPRS, EDGE, UMTS, HSDPA</li>
|
|
|
|
<li>Latency - GPRS, EDGE, UMTS</li>
|
|
</ul>
|
|
|
|
<h4>Spoofing calls or SMS text messages</h4>
|
|
<p>The Telephony Actions section of the Emulator
|
|
controls tab lets you spoof calls and messages. This is useful when you want to to test your
|
|
application's robustness in responding to incoming calls and messages that are sent to the phone.
|
|
The following actions are available to you:</p>
|
|
|
|
<ul>
|
|
<li>Voice - Enter a number in the <strong>Incoming number</strong> field and click
|
|
<strong>Call</strong> to send a simulated call to the emulator or phone. Click the
|
|
<strong>Hang up</strong> button to terminate the call.</li>
|
|
|
|
<li>SMS - Enter a number in the <strong>Incoming number</strong> field and a message in the
|
|
<strong>Message:</strong> field and click the <strong>Send</strong> button to send the
|
|
message.</li>
|
|
</ul>
|
|
|
|
<h4>Setting the location of the phone</h4>
|
|
<p>If your application depends on the location of the phone, you can have DDMS send your
|
|
device or AVD a mock location. This is useful if you
|
|
want to test different aspects of your application's location specific features without
|
|
physically moving. The following geolocation data types are available to you:</p>
|
|
|
|
<ul>
|
|
<li>Manual - set the location by manually specifying decimal or sexagesimal longitude and
|
|
latitude values.</li>
|
|
|
|
<li>GPX - GPS eXchange file</li>
|
|
|
|
<li>KML - Keyhole Markup Language file</li>
|
|
</ul>
|
|
|
|
For more information about providing mock location data, see
|
|
<a href="guide/topics/location/obtaining-user-location.html#MockData">Obtaining User Location</a>.
|
|
|