diff options
Diffstat (limited to 'docs/html/tools/debugging')
| -rw-r--r-- | docs/html/tools/debugging/ddms.jd | 357 | ||||
| -rw-r--r-- | docs/html/tools/debugging/debugging-devtools.jd | 77 | ||||
| -rw-r--r-- | docs/html/tools/debugging/debugging-log.jd | 308 | ||||
| -rw-r--r-- | docs/html/tools/debugging/debugging-projects-cmdline.jd | 78 | ||||
| -rw-r--r-- | docs/html/tools/debugging/debugging-projects.jd | 67 | ||||
| -rw-r--r-- | docs/html/tools/debugging/debugging-tracing.jd | 402 | ||||
| -rw-r--r-- | docs/html/tools/debugging/debugging-ui.jd | 547 | ||||
| -rw-r--r-- | docs/html/tools/debugging/index.jd | 186 |
8 files changed, 2022 insertions, 0 deletions
diff --git a/docs/html/tools/debugging/ddms.jd b/docs/html/tools/debugging/ddms.jd new file mode 100644 index 0000000..3d6324b --- /dev/null +++ b/docs/html/tools/debugging/ddms.jd @@ -0,0 +1,357 @@ +page.title=Using DDMS +parent.title=Debugging +parent.link=index.html +@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> + <ol> + <li><a href="#heap">Viewing heap usage for a process</a></li> + <li><a href="#alloc">Tracking memory allocation of objects</a></li> + <li><a href="#emulator">Working with an emulator or device's file system</a></li> + <li><a href="#thread">Examining thread information</a></li> + <li><a href="#profiling">Starting method profiling</a></li> + <li><a href="#network">Using the Network Traffic tool</a></li> + <li><a href="#logcat">Using LogCat</a></li> + <li><a href="#ops-location">Emulating phone operations and location</a></li> + </ol> + + </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}tools/help/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.android.email</code>, that is running in the emulator + has the debugging port 8700 assigned to it as well as 8606. This signifies that DDMS is currently + forwarding port 8606 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}tools/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/.android/ddms.cfg</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 id="heap">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 id="alloc">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. + </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 id="emulator">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 id="thread">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}tools/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="network">Using the Network Traffic tool</h3> + + <p>In Android 4.0, the DDMS (Dalvik Debug Monitor Server) includes a Detailed +Network Usage tab that makes it possible to track when your application is +making network requests. Using this tool, you can monitor how and when your app +transfers data and optimize the underlying code appropriately. You can also +distinguish between different traffic types by applying a “tag” to network +sockets before use.</p> + +<p>These tags are shown in a stack area chart in DDMS, as shown in figure 2:</p> + +<img src="{@docRoot}images/developing/ddms-network.png" /> +<p class="img-caption"><strong>Figure 2.</strong> Network Usage tab.</p> + +<p>By monitoring the frequency of your data transfers, and the amount of data +transferred during each connection, you can identify areas of your application +that can be made more battery-efficient. Generally, you should look for +short spikes that can be delayed, or that should cause a later transfer to be +pre-empted. </p> + +<p>To better identify the cause of transfer spikes, the +{@link android.net.TrafficStats} API allows you +to tag the data transfers occurring within a thread using {@link +android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}, followed +by manually tagging (and untagging) individual sockets using {@link +android.net.TrafficStats#tagSocket tagSocket()} and {@link +android.net.TrafficStats#untagSocket untagSocket()}. For example:</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); +TrafficStats.tagSocket(outputSocket); +// Transfer data using socket +TrafficStats.untagSocket(outputSocket);</pre> + +<p>Alternatively, the Apache {@link org.apache.http.client.HttpClient} and +{@link java.net.URLConnection} APIs included in the platform +automatically tag sockets internally based on the active tag (as +identified by +{@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}). +These APIs correctly tag/untag sockets when recycled through +keep-alive pools. In the following example, +{@link android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()} +sets the active tag to be {@code 0xF00D}. +There can only be one active tag per thread. +That is the value that will +be returned by {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()} +and thus used by {@link org.apache.http.client.HttpClient} + to tag sockets. The {@code finally} statement +invokes +{@link android.net.TrafficStats#clearThreadStatsTag clearThreadStatsTag()} +to clear the tag.</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); + try { + // Make network request using HttpClient.execute() + } finally { + TrafficStats.clearThreadStatsTag(); +}</pre> + +<p>Socket tagging is supported in Android 4.0, but real-time stats will only be +displayed on devices running Android 4.0.3 or higher.</p> + + <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}tools/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 id="ops-location">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="{@docRoot}guide/topics/location/strategies.html#MockData">Location Strategies</a>. + diff --git a/docs/html/tools/debugging/debugging-devtools.jd b/docs/html/tools/debugging/debugging-devtools.jd new file mode 100644 index 0000000..3a05120 --- /dev/null +++ b/docs/html/tools/debugging/debugging-devtools.jd @@ -0,0 +1,77 @@ +page.title=Using the Dev Tools App +parent.title=Debugging +parent.link=index.html +@jd:body + +<p>The Dev Tools application is installed by default on all system images included with the SDK, + so you can use it with the Android Emulator. With the Dev Tools application, you can enable a + number of settings on your device that will make it easier to test and debug your applications.</p> + + <p> The Dev Tools application relies on a number of permissions that are not available for + third party applications. If you'd like to install the Dev Tools application + on a real development device, you'd have to build a system image for that device and sign + the Dev Tools application with the same key as used for the system image.</p> + + <p>To get started, launch the Dev Tools application and select <strong>Development Settings</strong>. This will + open the Development Settings page with the following options (among others):</p> + + <dl> + <dt><strong>Debug app</strong></dt> + + <dd> + Lets you select the application to debug. You do not need to set this to attach a debugger, + but setting this value has two effects: + + <ul> + <li>It will prevent Android from throwing an error if you pause on a breakpoint for a long + time while debugging.</li> + + <li>It will enable you to select the <em>Wait for Debugger</em> option to pause application + startup until your debugger attaches (described next).</li> + </ul> + </dd> + + <dt><strong>Wait for debugger</strong></dt> + + <dd>Blocks the selected application from loading until a debugger attaches. This way you can + set a breakpoint in {@link android.app.Activity#onCreate onCreate()}, + which is important to debug the startup process of an Activity. + When you change this option, any currently running instances of the selected application will + be killed. In order to check this box, you must have selected a debug application as described + in the previous option. You can do the same thing by adding {@link + android.os.Debug#waitForDebugger()} to your code.</dd> + + <dt><strong>Show screen updates</strong></dt> + + <dd>Flashes a momentary pink rectangle on any screen sections that are being redrawn. This is + very useful for discovering unnecessary screen drawing.</dd> + + <dt><strong>Immediately destroy activities</strong></dt> + + <dd>Tells the system to destroy an activity as soon as it is stopped (as if Android had to + reclaim memory). This is very useful for testing the {@link + android.app.Activity#onSaveInstanceState} / {@link + android.app.Activity#onCreate(android.os.Bundle)} code path, which would otherwise be difficult + to force. Choosing this option will probably reveal a number of problems in your application + due to not saving state. For more information about saving an activity's state, see the + <a href="{@docRoot}guide/components/activities.html#SavingActivityState">Activities</a> +document.</dd> + + <dt><strong>Show CPU usage</strong></dt> + + <dd>Displays CPU meters at the top of the screen, showing how much the CPU is being used. The + top red bar shows overall CPU usage, and the green bar underneath it shows the CPU time spent + in compositing the screen. + <p class="note">Note: You cannot turn this feature off once it is on, without + restarting the emulator.</p></dd> + + <dt><strong>Show background</strong></dt> + + <dd>Displays a background pattern when no activity screens are visible. This typically does not + happen, but can happen during debugging.</dd> + </dl> + + <p>These settings will be remembered across emulator restarts.</p> + + + diff --git a/docs/html/tools/debugging/debugging-log.jd b/docs/html/tools/debugging/debugging-log.jd new file mode 100644 index 0000000..d2baaf2 --- /dev/null +++ b/docs/html/tools/debugging/debugging-log.jd @@ -0,0 +1,308 @@ +page.title=Reading and Writing Logs +parent.title=Debugging +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li><a href="#logClass">The Log class</a></li> + + <li><a href="#startingLogcat">Starting LogCat</a></li> + + <li><a href="#filteringOutput">Filtering Log Output</a></li> + + <li><a href="#outputFormat">Controlling Log Output Format</a></li> + + <li><a href="#alternativeBuffers">Viewing Alternative Log Output Buffers</a></li> + + <li><a href="#viewingStd">Viewing stdout and stderr</a></li> + + <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li> + </ol> + </div> + </div> + + <p>The Android logging system provides a mechanism for collecting and viewing system debug + output. Logcat dumps a log of system messages, which include things such as stack traces when the + emulator throws an error and messages that you have written from your application by using the + {@link android.util.Log} class. You can run LogCat through ADB or from DDMS, which allows you to + read the messages in real time.</p> + + <h2 id="logClass">The <code>Log</code> class</h2> + + <p>{@link android.util.Log} is a logging class that you can utilize in your code to print out + messages to the LogCat. Common logging methods include:</p> + + <ul> + <li>{@link android.util.Log#v(String,String)} (verbose)</li> + + <li>{@link android.util.Log#d(String,String)} (debug)</li> + + <li>{@link android.util.Log#i(String,String)} (information)</li> + + <li>{@link android.util.Log#w(String,String)} (warning)</li> + + <li>{@link android.util.Log#e(String,String)} (error)</li> + </ul>For example: + <pre class="no-pretty-print"> +Log.i("MyActivity", "MyClass.getView() — get item number " + position); +</pre> + + <p>The LogCat will then output something like:</p> + <pre class="no-pretty-print"> +I/MyActivity( 1557): MyClass.getView() — get item number 1 +</pre> + + <h2 id="startingLogcat">Using LogCat</h2> + + <p>You can use LogCat from within DDMS or call it on an ADB shell. For more information on how to + use LogCat within DDMS, see <a href="{@docRoot}tools/debugging/ddms.html#logcat">Using + DDMS</a>. To run LogCat, through the ADB shell, the general usage is:</p> + <pre> +[adb] logcat [<option>] ... [<filter-spec>] ... +</pre> + + <p>You can use the <code>logcat</code> command from your development computer or from a remote + adb shell in an emulator/device instance. To view log output in your development computer, you + use</p> + <pre> +$ adb logcat +</pre> + + <p>and from a remote adb shell you use</p> + <pre> +# logcat +</pre> + + <p>The following table describes the <code>logcat</code> command line options:</p> + + <table> + <tr> + <td><code>-c</code></td> + + <td>Clears (flushes) the entire log and exits.</td> + </tr> + + <tr> + <td><code>-d</code></td> + + <td>Dumps the log to the screen and exits.</td> + </tr> + + <tr> + <td><code>-f <filename></code></td> + + <td>Writes log message output to <code><filename></code>. The default is + <code>stdout</code>.</td> + </tr> + + <tr> + <td><code>-g</code></td> + <td>Prints the size of the specified log buffer and exits.</td> + </tr> + + <tr> + <td><code>-n <count></code></td> + + <td>Sets the maximum number of rotated logs to <code><count></code>. The default value + is 4. Requires the <code>-r</code> option.</td> + </tr> + + <tr> + <td><code>-r <kbytes></code></td> + + <td>Rotates the log file every <code><kbytes></code> of output. The default value is + 16. Requires the <code>-f</code> option.</td> + </tr> + + <tr> + <td><code>-s</code></td> + + <td>Sets the default filter spec to silent.</td> + </tr> + + <tr> + <td><code>-v <format></code></td> + + <td>Sets the output format for log messages. The default is <code>brief</code> format. For a + list of supported formats, see <a href="#outputFormat">Controlling Log Output + Format</a>.</td> + </tr> + </table> + + <h3 id="filteringOutput">Filtering Log Output</h3> + + <p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it.</p> + + <ul> + <li>The tag of a log message is a short string indicating the system component from which the + message originates (for example, "View" for the view system).</li> + + <li>The priority is one of the following character values, ordered from lowest to highest + priority:</li> + + <li style="list-style: none; display: inline"> + <ul> + <li><code>V</code> — Verbose (lowest priority)</li> + + <li><code>D</code> — Debug</li> + + <li><code>I</code> — Info</li> + + <li><code>W</code> — Warning</li> + + <li><code>E</code> — Error</li> + + <li><code>F</code> — Fatal</li> + + <li><code>S</code> — Silent (highest priority, on which nothing is ever printed)</li> + </ul> + </li> + </ul> + + <p>You can obtain a list of tags used in the system, together with priorities, by running + LogCat and observing the first two columns of each message, given as + <code><priority>/<tag></code>.</p> + + <p>Here's an example of logcat output that shows that the message relates to priority level "I" + and tag "ActivityManager":</p> + <pre> +I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...} +</pre> + + <p>To reduce the log output to a manageable level, you can restrict log output using <em>filter + expressions</em>. Filter expressions let you indicate to the system the tags-priority + combinations that you are interested in — the system suppresses other messages for the + specified tags.</p> + + <p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code> + indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of + priority to report for that tag. Messages for that tag at or above the specified priority are + written to the log. You can supply any number of <code>tag:priority</code> specifications in a + single filter expression. The series of specifications is whitespace-delimited.</p> + + <p>Here's an example of a filter expression that suppresses all log messages except those with + the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", + with priority "Debug" or above:</p> + <pre> +adb logcat ActivityManager:I MyApp:D *:S +</pre> + + <p>The final element in the above expression, <code>*:S</code>, sets the priority level for all + tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using + <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that + you have explicitly specified — it lets your filters serve as a "whitelist" for log + output.</p> + + <p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p> + <pre> +adb logcat *:W +</pre> + + <p>If you're running LogCat from your development computer (versus running it on a + remote adb shell), you can also set a default filter expression by exporting a value for the + environment variable <code>ANDROID_LOG_TAGS</code>:</p> + <pre> +export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S" +</pre> + + <p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device + instance, if you are running LogCat from a remote shell or using <code>adb shell + logcat</code>.</p> + + <h3 id="outputFormat">Controlling Log Output Format</h3> + + <p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can + modify the output format for messages so that they display a specific metadata field. To do so, + you use the <code>-v</code> option and specify one of the supported output formats listed + below.</p> + + <ul> + <li><code>brief</code> — Display priority/tag and PID of the process issuing the + message (the default format).</li> + + <li><code>process</code> — Display PID only.</li> + + <li><code>tag</code> — Display the priority/tag only.</li> + + <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> + + <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the + process issuing the message.</li> + + <li><code>threadtime</code> — Display the date, invocation time, priority, tag, and + the PID and TID of the thread issuing the message.</li> + + <li><code>long</code> — Display all metadata fields and separate messages with blank + lines.</li> + </ul> + + <p>When starting LogCat, you can specify the output format you want by using the + <code>-v</code> option:</p> + <pre> +[adb] logcat [-v <format>] +</pre> + + <p>Here's an example that shows how to generate messages in <code>thread</code> output + format:</p> + <pre> +adb logcat -v thread +</pre> + + <p>Note that you can only specify one output format with the <code>-v</code> option.</p> + + <h3 id="alternativeBuffers">Viewing Alternative Log Buffers</h3> + + <p>The Android logging system keeps multiple circular buffers for log messages, and not all of + the log messages are sent to the default circular buffer. To see additional log messages, you can + run the <code>logcat</code> command with the <code>-b</code> option, to request viewing of an alternate + circular buffer. You can view any of these alternate buffers:</p> + + <ul> + <li><code>radio</code> — View the buffer that contains radio/telephony related + messages.</li> + + <li><code>events</code> — View the buffer containing events-related messages.</li> + + <li><code>main</code> — View the main log buffer (default)</li> + </ul> + + <p>The usage of the <code>-b</code> option is:</p> + <pre> +[adb] logcat [-b <buffer>] +</pre> + + <p>Here's an example of how to view a log buffer containing radio and telephony messages:</p> + <pre> +adb logcat -b radio +</pre><a name="stdout" + id="stdout"></a> + + <h2 id="viewingStd">Viewing stdout and stderr</h2> + + <p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> + (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In + processes that run the Dalvik VM, you can have the system write a copy of the output to the log + file. In this case, the system writes the messages to the log using the log tags + <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>.</p> + + <p>To route the output in this way, you stop a running emulator/device instance and then use the + shell command <code>setprop</code> to enable the redirection of output. Here's how you do it:</p> + <pre> +$ adb shell stop +$ adb shell setprop log.redirect-stdio true +$ adb shell start +</pre> + + <p>The system retains this setting until you terminate the emulator/device instance. To use the + setting as a default on the emulator/device instance, you can add an entry to + <code>/data/local.prop</code> on the device.</p> + + <h2 id="DebuggingWebPages">Debugging Web Apps</h2> + <p> + If you're developing a web application for Android, you can debug your JavaScript using the console JavaScript APIs, + which output messages to LogCat. For more information, see + <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p> diff --git a/docs/html/tools/debugging/debugging-projects-cmdline.jd b/docs/html/tools/debugging/debugging-projects-cmdline.jd new file mode 100644 index 0000000..0b79575 --- /dev/null +++ b/docs/html/tools/debugging/debugging-projects-cmdline.jd @@ -0,0 +1,78 @@ +page.title=Debugging from Other IDEs +parent.title=Debugging +parent.link=index.html +@jd:body + + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li><a href="#start-debugging">Starting a Debugging Environment</a> + <ul> + <li><a href="#debuggingPort">Configuring Your IDE to Attach to the Debugging Port</a></li> + </ul> + </li> + </ol> + </div> + </div> + + <p>If you are not using Eclipse to develop, you can still take advantage of all the tools that + the Android SDK provides for debugging. A basic debugging environment consists of:</p> + + <ul> + <li><a href="{@docRoot}tools/help/adb.html">ADB</a></li> + + <li><a href="{@docRoot}tools/debugging/ddms.html">DDMS</a></li> + + <li>Java Debugger</li> + </ul> + + <p>You need to obtain a JDWP-compliant Java debugger to properly debug your application. + Most Java IDEs will already have one included, or you can use a command line debugger, + such as JDB, if you are using a simple text editor to develop applications.</p> + + <h2 id="start-debugging">Starting a debugging environment</h2> + <p>A Java Debugger assists you in finding problems with + your code by letting you set breakpoints, step through execution of your application, and examine + variable values. Since you are not using Eclipse, you have to manually start up the debugging + environment yourself by running a few tools that are provided in the Android SDK. To begin + debugging your application, follow these general steps:</p> + + <ol> + <li>Load an AVD with the Android emulator or connect a device to your computer.</li> + + <li>Start DDMS from the sdk <code>/tools</code> directory. This also starts ADB if it is + not already started. You should see your device appear in DDMS.</li> + + <li>Install and run your <code>.apk</code> file on the device or emulator. In DDMS, you should see your + application running under the device that you installed it to.</li> + + <li>Attach your debugger to the debugging port 8700, or to the specific port shown for the + application in DDMS.</li> + </ol> + + <h3 id="debuggingPort">Configuring Your IDE to Attach to the Debugging Port</h3> + + <p>DDMS assigns a specific debugging port to every virtual machine that it finds on the + emulator. You must either attach your IDE to that port (listed on the Info tab for that VM), or + you can use a default port 8700 to connect to whatever application is currently selected on the + list of discovered virtual machines.</p> + + <p>Your IDE should attach to your application running on the emulator, showing you its threads + and allowing you to suspend them, inspect their state, and set breakpoints. If you selected "Wait + for debugger" in the Development settings panel the application will run when Eclipse connects, + so you will need to set any breakpoints you want before connecting.</p> + + <p>Changing either the application being debugged or the "Wait for debugger" option causes the + system to kill the selected application if it is currently running. You can use this to kill your + application if it is in a bad state by simply going to the settings and toggling the + checkbox.</p> + + + + + + + diff --git a/docs/html/tools/debugging/debugging-projects.jd b/docs/html/tools/debugging/debugging-projects.jd new file mode 100644 index 0000000..2283f8b --- /dev/null +++ b/docs/html/tools/debugging/debugging-projects.jd @@ -0,0 +1,67 @@ +page.title=Debugging from Eclipse with ADT +parent.title=Debugging +parent.link=index.html +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li><a href="#tools">The Debug Perspective</a></li> + + <li><a href="#toptips">The DDMS Perspective</a></li> + </ol> + </div> + </div> + + <p>If you are developing in Eclipse with the ADT plugin, you can use the built-in Java Debugger, + along with DDMS, to debug your applications. To access the debugger and + DDMS, Eclipse displays the debugger and DDMS features as perspectives, which are customized + Eclipse views that display certain tabs and windows depending on the perspective that you are in. + Eclipse also takes care of starting the ADB host daemon for you, so you do not have to run this + manually.</p> + + <h2>The Debug Perspective in Eclipse</h2> + + <p>The Debug Perspective in Eclipse gives you access to the following tabs:</p> + + <ul> + <li>Debug - Displays previously and currently debugged Android applications and its currently + running threads</li> + + <li>Variables - When breakpoints are set, displays variable values during code execution</li> + + <li>Breakpoints - Displays a list of the set breakpoints in your application code</li> + + <li>LogCat - Allows you to view system log messages in real time. The LogCat tab is also + available in the DDMS perspective.</li> + </ul> + <p>You can access the Debug Perspective by clicking <strong>Window > Open Perspective > + Debug</strong>. Refer to the appropriate documentation for the Eclipse debugger for more + information.</p> + + <h2>The DDMS Perspective</h2> + <p>The DDMS Perspective in Eclipse lets you access all of the features + of DDMS from within the Eclipse IDE. The following sections of DDMS are available to you:</p> + + <ul> + <li>Devices - Shows the list of devices and AVDs that are connected to ADB.</li> + + <li>Emulator Control - Lets you carry out device functions.</li> + + <li>LogCat - Lets you view system log messages in real time.</li> + + <li>Threads - Shows currently running threads within a VM.</li> + + <li>Heap - Shows heap usage for a VM.</li> + + <li>Allocation Tracker - Shows the memory allocation of objects.</li> + + <li>File Explorer - Lets you explore the device's file system.</li> + </ul> + <p>To access the DDMS perspective, go to <strong>Window > Open Perspective > + DDMS</strong>. If DDMS does not appear, go to <strong>Window > Open Perspective > Other + ...</strong> and select <strong>DDMS</strong> from the Open Perspective window that appears. For + more information on using DDMS, see <a href="ddms.html">Using the Dalvik Debug Monitor Server</a>. + </p>
\ No newline at end of file diff --git a/docs/html/tools/debugging/debugging-tracing.jd b/docs/html/tools/debugging/debugging-tracing.jd new file mode 100644 index 0000000..f0d0c0b --- /dev/null +++ b/docs/html/tools/debugging/debugging-tracing.jd @@ -0,0 +1,402 @@ +page.title=Profiling with Traceview and dmtracedump +parent.title=Debugging +parent.link=index.html +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li> + <a href="#traceviewLayout">Traceview Layout</a> + + <ol> + <li><a href="#timelinepanel">Timeline Panel</a></li> + + <li><a href="#profilepanel">Profile Panel</a></li> + </ol> + </li> + + <li> + <a href="#format">Traceview File Format</a> + <ol> + <li><a href="#datafileformat">Data File Format</a></li> + + <li><a href="#keyfileformat">Key File Format</a></li> + </ol> + </li> + + <li><a href="#creatingtracefiles">Creating Trace Files</a></li> + + <li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li> + + <li><a href="#runningtraceview">Viewing Trace Files in Traceview</a></li> + + <li><a href="#dmtracedump">Using dmtracedump</a></li> + + <li><a href="#knownissues">Traceview Known Issues</a></li> + </ol> + </div> + </div> + + <p>Traceview is a graphical viewer for execution logs that you create by using the {@link + android.os.Debug} class to log tracing information in your code. Traceview can help you debug + your application and profile its performance.</p> + + <h2 id="traceviewLayout">Traceview Layout</h2> + + <p>When you have a trace log file (generated by adding tracing code to your application or by DDMS), + you can have Traceview load the log files and display their data in a window visualizes your application + in two panels:</p> + + <ul> + <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread and method + started and stopped</li> + + <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside + a method</li> + </ul> + + <p>The sections below provide addition information about the traceview output panes.</p> + + <h3 id="timelinepanel">Timeline Panel</h3> + + <p>The image below shows a close up of the timeline panel. Each thread’s execution is shown + in its own row, with time increasing to the right. Each method is shown in another color (colors + are reused in a round-robin fashion starting with the methods that have the most inclusive time). + The thin lines underneath the first row show the extent (entry to exit) of all the calls to the + selected method. The method in this case is <code>LoadListener.nativeFinished()</code> and it was selected in + the profile view.</p> + + <img src="{@docRoot}images/traceview_timeline.png" + alt="Traceview timeline panel" + width="893" + height="284" /> + <p class="img-caption"><strong>Figure 1.</strong> The Traceview Timeline Panel</p> + + <h3 id="profilepanel">Profile Panel</h3> + + <p>Figure 2 shows the profile pane, a summary of all the time spent + in a method. The table shows both the inclusive and exclusive times (as well as the percentage of + the total time). Exclusive time is the time spent in the method. Inclusive time is the time spent + in the method plus the time spent in any called functions. We refer to calling methods as + "parents" and called methods as "children." When a method is selected (by clicking on it), it + expands to show the parents and children. Parents are shown with a purple background and children + with a yellow background. The last column in the table shows the number of calls to this method + plus the number of recursive calls. The last column shows the number of calls out of the total + number of calls made to that method. In this view, we can see that there were 14 calls to + <code>LoadListener.nativeFinished();</code> looking at the timeline panel shows that one of those calls took + an unusually long time.</p> + + <img src="{@docRoot}images/traceview_profile.png" + alt="Traceview profile panel." + width="892" + height="630" /> + <p class="img-caption"><strong>Figure 2.</strong> The Traceview Profile Panel</p> + + <h2 id="format">Traceview File Format</h2> + + <p>Tracing creates two distinct pieces of output: a <em>data</em> file, which holds the trace + data, and a <em>key</em> file, which provides a mapping from binary identifiers to thread and + method names. The files are concatenated when tracing completes, into a single <em>.trace</em> + file.</p> + + <p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate + these files for you. If you have old key and data files that you'd still like to trace, you can + concatenate them yourself with <code>cat mytrace.key mytrace.data > + mytrace.trace</code>.</p> + + <h3 id="datafileformat">Data File Format</h3> + + <p>The data file is binary, structured as follows (all values are stored in little-endian + order):</p> + <pre> +* File format: +* header +* record 0 +* record 1 +* ... +* +* Header format: +* u4 magic 0x574f4c53 ('SLOW') +* u2 version +* u2 offset to data +* u8 start date/time in usec +* +* Record format: +* u1 thread ID +* u4 method ID | method action +* u4 time delta since start, in usec +</pre> + + <p>The application is expected to parse all of the header fields, then seek to "offset to data" + from the start of the file. From there it just reads 9-byte records until EOF is reached.</p> + + <p><em>u8 start date/time in usec</em> is the output from <code>gettimeofday()</code>. It's mainly there so + that you can tell if the output was generated yesterday or three months ago.</p> + + <p><em>method action</em> sits in the two least-significant bits of the <em>method</em> word. The + currently defined meanings are:</p> + + <ul> + <li>0 - method entry</li> + + <li>1 - method exit</li> + + <li>2 - method "exited" when unrolled by exception handling</li> + + <li>3 - (reserved)</li> + </ul> + + <p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds.</p> + + <h3 id="keyfileformat">Key File Format</h3> + + <p>The key file is a plain text file divided into three sections. Each section starts with a + keyword that begins with '*'. If you see a '*' at the start of a line, you have found the start + of a new section.</p> + + <p>An example file might look like this:</p> + <pre> +*version +1 +clock=global +*threads +1 main +6 JDWP Handler +5 Async GC +4 Reference Handler +3 Finalizer +2 Signal Handler +*methods +0x080f23f8 java/io/PrintStream write ([BII)V +0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V +0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V +0x080da620 java/lang/RuntimeException <init> ()V +[...] +0x080f630c android/os/Debug startMethodTracing ()V +0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V +*end +</pre> +<p>The following list describes the major sections of a key file:</p> + <dl> + <dt><em>version section</em></dt> + + <dd>The first line is the file version number, currently 1. The second line, + <code>clock=global</code>, indicates that we use a common clock across all threads. A future + version may use per-thread CPU time counters that are independent for every thread.</dd> + + <dt><em>threads section</em></dt> + + <dd>One line per thread. Each line consists of two parts: the thread ID, followed by a tab, + followed by the thread name. There are few restrictions on what a valid thread name is, so + include everything to the end of the line.</dd> + + <dt><em>methods section</em></dt> + + <dd>One line per method entry or exit. A line consists of four pieces, separated by tab marks: + <em>method-ID</em> [TAB] <em>class-name</em> [TAB] <em>method-name</em> [TAB] + <em>signature</em> . Only the methods that were actually entered or exited are included in the + list. Note that all three identifiers are required to uniquely identify a method.</dd> + </dl> + + <p>Neither the threads nor methods sections are sorted.</p> + + <h2 id="creatingtracefiles">Creating Trace Files</h2> + + <p>To use Traceview, you need to generate log files containing the trace information you want to + analyze.</p> + + <p>There are two ways to generate trace logs:</p> + <ul> + <li>Include the {@link android.os.Debug} class in your code and call its + methods to start and stop logging of trace information to disk. This method is very precise because + you can specify in your code exactly where to start and stop logging trace data.</li> + <li>Use the method profiling feature of DDMS to generate trace logs. This method is less + precise since you do not modify code, but rather specify when to start and stop logging with + a DDMS. Although you have less control on exactly where the data is logged, this method is useful + if you don't have access to the application's code, or if you do not need the precision of the first method. + </li> + </ul> + + <p>Before you start generating trace logs, be aware of the following restrictions:</p> + <ul> + <li>If you are using the {@link android.os.Debug} class, your device or emulator must have an SD card + and your application must have permission to write to the SD card. </li> + <li>If you are using DDMS, Android 1.5 devices are not supported.</li> + <li>If you are using DDMS, 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>If you are using DDMS, 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>This document focuses on using the {@link android.os.Debug} class to generate trace data. For more information on using DDMS + to generate trace data, see <a href="ddms.html#profiling">Using the Dalvik Debug Monitor Server.</a> + </p> + + <p>To create the trace files, include the {@link android.os.Debug} class and call one of the + {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. In the call, you + specify a base name for the trace files that the system generates. To stop tracing, call {@link + android.os.Debug#stopMethodTracing() stopMethodTracing()}. These methods start and stop method + tracing across the entire virtual machine. For example, you could call + {@link android.os.Debug#startMethodTracing() startMethodTracing()} in + your activity's {@link android.app.Activity#onCreate onCreate()} method, and call + {@link android.os.Debug#stopMethodTracing() stopMethodTracing()} in that activity's + {@link android.app.Activity#onDestroy()} method.</p> + <pre> + // start tracing to "/sdcard/calc.trace" + Debug.startMethodTracing("calc"); + // ... + // stop tracing + Debug.stopMethodTracing(); +</pre> + + <p>When your application calls startMethodTracing(), the system creates a file called + <code><trace-base-name>.trace</code>. This contains the binary method trace data and a + mapping table with thread and method names.</p> + + <p>The system then begins buffering the generated trace data, until your application calls + stopMethodTracing(), at which time it writes the buffered data to the output file. If the system + reaches the maximum buffer size before stopMethodTracing() is called, the system stops tracing + and sends a notification to the console.</p> + + <p>Interpreted code will run more slowly when profiling is enabled. Don't try to generate + absolute timings from the profiler results (i.e. "function X takes 2.5 seconds to run"). The + times are only useful in relation to other profile output, so you can see if changes have made + the code faster or slower.</p> + + <p>When using the Android emulator, you must specify an SD card when you create your AVD because the trace files + are written to the SD card. Your application must have permission to write to the SD card as well. + + <p>The format of the trace files is previously described <a href="#format">in this + document</a>.</p> + + <h2 id="copyingfiles">Copying Trace Files to a Host Machine</h2> + + <p>After your application has run and the system has created your trace files + <code><trace-base-name>.trace</code> on a device or emulator, you must copy those files to + your development computer. You can use <code>adb pull</code> to copy the files. Here's an example + that shows how to copy an example file, calc.trace, from the default location on the emulator to + the /tmp directory on the emulator host machine:</p> + <pre> +adb pull /sdcard/calc.trace /tmp +</pre> + + <h2 id="runningtraceview">Viewing Trace Files in Traceview</h2> + + <p>To run Traceview and view the trace files, enter <code>traceview + <trace-base-name></code>. For example, to run Traceview on the example files copied in the + previous section, use:</p> + <pre> +traceview /tmp/calc +</pre> + + <p class="note"><strong>Note:</strong> If you are trying to view the trace logs of an application + that is built with ProGuard enabled (release mode build), some method and member names might be obfuscated. + You can use the Proguard <code>mapping.txt</code> file to figure out the original unobfuscated names. For more information + on this file, see the <a href="{@docRoot}tools/help/proguard.html">Proguard</a> documentation.</p> + + <h2 id="dmtracedump">Using dmtracdedump</h2> + + <p><code>dmtracedump</code> is a tool that gives you an alternate way of generating + graphical call-stack diagrams from trace log files. The tool uses the Graphviz Dot utility to + create the graphical output, so you need to install Graphviz before running dmtracedump.</p> + + <p>The dmtracedump tool generates the call stack data as a tree diagram, with each call + represented as a node. It shows call flow (from parent node to child nodes) using arrows. The + diagram below shows an example of dmtracedump output.</p> + <img src= + "{@docRoot}images/tracedump.png" + width="485" + height="401" /> + <p class="image-caption"><strong>Figure 3.</strong> Screenshot of dmtracedump</p> + + <p>For each node, dmtracedump shows <code><ref> + <em>callname</em> (<inc-ms>, <exc-ms>,<numcalls>)</code>, where</p> + + <ul> + <li><code><ref></code> -- Call reference number, as used in trace logs</li> + + <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, + including all child methods)</li> + + <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, + not including any child methods)</li> + + <li><code><numcalls></code> -- Number of calls</li> + </ul> + + <p>The usage for dmtracedump is:</p> + <pre> +dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name> +</pre> + + <p>The tool then loads trace log data from <code><trace-base-name>.data</code> and + <code><trace-base-name>.key</code>. The table below lists the options for dmtracedump.</p> + + <table> + <tr> + <th>Option</th> + + <th>Description</th> + </tr> + + <tr> + <td><code>-d <trace-base-name></code></td> + + <td>Diff with this trace name</td> + </tr> + + <tr> + <td><code>-g <outfile></code></td> + + <td>Generate output to <outfile></td> + </tr> + + <tr> + <td><code>-h</code></td> + + <td>Turn on HTML output</td> + </tr> + + <tr> + <td><code>-o</code></td> + + <td>Dump the trace file instead of profiling</td> + </tr> + + <tr> + <td><code>-d <trace-base-name></code></td> + + <td>URL base to the location of the sortable javascript file</td> + </tr> + + <tr> + <td><code>-t <percent></code></td> + + <td>Minimum threshold for including child nodes in the graph (child's inclusive time as a + percentage of parent inclusive time). If this option is not used, the default threshold + is 20%.</td> + </tr> + </table> + + + + <h2 id="knownissues">Traceview Known Issues</h2> + + <dl> + <dt>Threads</dt> + + <dd> + Traceview logging does not handle threads well, resulting in these two problems: + + <ol> + <li>If a thread exits during profiling, the thread name is not emitted;</li> + + <li>The VM reuses thread IDs. If a thread stops and another starts, they may get the same + ID.</li> + </ol> + </dd> + + </dl>
\ No newline at end of file diff --git a/docs/html/tools/debugging/debugging-ui.jd b/docs/html/tools/debugging/debugging-ui.jd new file mode 100644 index 0000000..c1976b8 --- /dev/null +++ b/docs/html/tools/debugging/debugging-ui.jd @@ -0,0 +1,547 @@ +page.title=Optimizing Your UI +parent.title=Debugging +parent.link=index.html +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li> + <a href="#HierarchyViewer"> + Using Hierarchy Viewer + </a> + <ol> + <li><a href="#runhv">Running Hierarchy Viewer and choosing a window</a></li> + <li><a href="#viewhierarchy">About the View Hierarchy window</a></li> + <li><a href="#indiView">Working with an individual View in Tree View</a></li> + <li><a href="#hvdebugging">Debugging with View Hierarchy</a></li> + <li><a href="#hvoptimize">Optimizing with View Hierarchy</a></li> + </ol> + </li> + <li> + <a href="#pixelperfect"> + Using Pixel Perfect + </a> + <ol> + <li><a href="#aboutpixelperfect">About the Pixel Perfect window</a></li> + <li><a href="#overlays">Working with Pixel Perfect overlays</a></li> + </ol> + </li> + <li><a href="#layoutopt">Using layoutopt</a></li> + </ol> + <h2>Related videos</h2> + <ol> + <li> +<iframe title="Hierarchyviewer" + width="210" height="160" + src="http://www.youtube.com/embed/PAgE7saQUUY?rel=0&hd=1" + frameborder="0" allowfullscreen> +</iframe> + </li> + <li> +<iframe title="Pixel Perfect" + width="210" height="160" + src="http://www.youtube.com/embed/C45bMZGdN7Y?rel=0&hd=1" + frameborder="0" + allowfullscreen> +</iframe> + </li> + </ol> + </div> + </div> + + <p> +Sometimes your application's layout can slow down your application. + To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and + <code>layoutopt</code> tools. + </p> + + <p>The Hierarchy Viewer application allows you to debug and optimize your user interface. It + provides a visual representation of the layout's View hierarchy (the View Hierarchy window) + and a magnified view of the display (the Pixel Perfect window).</p> + + <p><code>layoutopt</code> is a command-line tool that helps you optimize the layouts and layout + hierarchies of your applications. You can run it against your layout files or resource + directories to quickly check for inefficiencies or other types of problems that could be + affecting the performance of your application.</p> + +<h2 id="HierarchyViewer">Using Hierarchy Viewer</h2> + +<h3 id="runhv">Running Hierarchy Viewer and choosing a window</h3> +<p> + To run Hierarchy Viewer, follow these steps:</p> +<ol> + <li> + Connect your device or launch an emulator. + <p> + To preserve security, Hierarchy Viewer can only connect to devices running a + developer version of the Android system. + </p> + </li> + <li> + If you have not done so already, install the application you want to work with. + </li> + <li> + Run the application, and ensure that its UI is visible. + </li> + <li> + From a terminal, launch <code>hierarchyviewer</code> from the + <code><sdk>/tools/</code> + directory. + </li> + <li> + The first window you see displays a list of devices and emulators. To expand the list + of Activity objects for a device or emulator, click the arrow on the left. This displays a + list of the Activity objects whose UI is currently visible on the device or emulator. The + objects are listed by their Android component name. The list includes both your application + Activity and system Activity objects. A screenshot of this window appears in + figure 1. + </li> + <li> + Select the name of your Activity from the list. You can now look at its view + hierarchy using the View Hierarchy window, or look at a magnified image of the UI using + the Pixel Perfect window. + </li> +</ol> +<p> + To learn how to use the View Hierarchy window, go to + <a href="#viewhierarchy">About the View Hierarchy window</a>. To learn how to use the + Pixel Perfect window, go to <a href="#pixelperfect">About the Pixel Perfect window</a>. +</p> +<img id="Fig1" src="{@docRoot}images/developing/hv_device_window.png" alt="" height="600"/> +<p class="img-caption"><strong>Figure 1.</strong> Hierarchy Viewer device window</p> +<h3 id="viewhierarchy">About the View Hierarchy window</h3> +<p> + The View Hierarchy window displays the View objects that form the UI of the + Activity that is running on your device or emulator. You use it to look at individual + View objects within the context of the entire View tree. For each View object, the View + Hierarchy window also displays rendering performance data. +</p> +<p> + To see the View Hierarchy window, run Hierarchy Viewer as described in + the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click + <strong>View Hierarchy</strong> at the top of the device window. +</p> +<p> + You should see four panes: +</p> +<ul> + <li> + <strong>Tree View</strong>: The left-hand pane displays the Tree View, + a diagram of the Activity object's hierarchy of views. Use Tree View to examine individual + View objects and see the relationships between View objects in your UI. + <p> + To zoom in on the pane, use the slider at the bottom of the pane, or use your mouse + scroll wheel. To move around in the pane or reveal View objects that are not currently + visible, click and drag the pane. + </p> + <p> + To highlight the nodes in the tree whose class or ID match a search string, enter the + string in the <strong>Filter by class or id:</strong> edit box at the bottom of the + window. The background of nodes that match the search string will change from gray to + bright blue. + </p> + <p> + To save a screenshot of Tree View to a PNG file, click <strong>Save As PNG</strong> at + the top of the View Hierarchy window. This displays a dialog in which you can choose + a directory and file name. + </p> + <p> + To save a layered screenshot of your device or emulator to an Adobe Photoshop (PSD) + file, click <strong>Capture Layers</strong> at the top of the View Hierarchy window. + This displays a dialog in which you can choose a directory or file name. + Each View in the UI is saved as a separate Photoshop layer. + </p> + <p> + In Photoshop (or similar program that accepts .psd files), you can hide, show or edit a + layer independently of others. When you save a layered screenshot, you can examine and + modify the image of an individual View object. This helps you experiment with design + changes. + </p> + </li> + <li> + The upper right-hand pane displays the <strong>Tree Overview</strong>, a smaller map + representation of the entire Tree View window. Use Tree Overview to identify the part of the + view tree that is being displayed in Tree View. + <p> + You can also use Tree Overview to move around in the Tree View pane. Click and drag + the shaded rectangle over an area to reveal it in Tree View. + </p> + </li> + <li> + The middle right-hand pane displays the <strong>Properties View</strong>, + a list of the properties for a selected View object. With Properties View, you can + examine all the properties without having to look at your application source. + <p> + The properties are organized by category. To find an individual property, expand + a category name by clicking the arrow on its left. This reveals all the properties + in that category. + </p> + </li> + <li> + The lower right-hand pane displays the <strong>Layout View</strong>, + a block representation of the UI. Layout View is another way to navigate through your UI. + When you click on a View object in Tree View, its position in the UI is highlighted. + Conversely, when you click in an area of Layout View, the View object for that area is + highlighted in Tree View. + <p> + The outline colors of blocks in Layout View provide additional information: + </p> + <ul> + <li> + Bold red: The block represents the the View that is currently selected in + Tree View. + </li> + <li> + Light red: The block represents the parent of the block outlined in bold red. + </li> + <li> + White: The block represents a visible View that is not a parent or child of the + View that is currently selected in Tree View. + </li> + </ul> + </li> +</ul> +<p> + When the UI of the current Activity changes, the View Hierarchy window is not automatically + updated. To update it, click <strong>Load View Hierarchy</strong> at the top of the window. +</p> +<p> + Also, the window is not updated if you switch to a new Activity. To update it, start by + clicking the window selection icon in the bottom left-hand corner of the window. This + navigates back to the Window Selection window. From this window, click the Android + component name of the new Activity and then click <strong>Load View Hierarchy</strong> + at the top of the window. +</p> +<p> + A screenshot of the View Hierarchy window appears in figure 2. +</p> +<img id="Fig2" src="{@docRoot}images/developing/hv_view_hierarchy_window.png" alt="" height="600"/> +<p class="img-caption"><strong>Figure 2.</strong> The View Hierarchy window</p> +<h3 id="indiView">Working with an individual View in Tree View</h3> +<p> + Each node in Tree View represents a single View. Some information is always visible. Starting + at the top of the node, you see the following: +</p> +<ol> + <li> + View class: The View object's class. + </li> + <li> + View object address: A pointer to View object. + </li> + <li> + View object ID: The value of the + <code><a href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">android:id</a> + </code> attribute. + </li> + <li> + Performance indicators: A set of three colored dots that indicate the rendering + speed of this View relative to other View objects in the tree. The three dots + represent (from left to right) the measure, layout, and draw times of the rendering. + <p> + The colors indicate the following relative performance: + </p> + <ul> + <li> + Green: For this part of the render time, this View is in the faster 50% of all + the View objects in the tree. For example, a green dot for the measure time means + that this View has a faster measure time than 50% of the View objects in the tree. + </li> + <li> + Yellow: For this part of the render time, this View is in the slower 50% of all + the View objects in the tree. For example, a yellow dot for the layout time means + that this View has a slower layout time than 50% of the View objects in the tree. + </li> + <li> + Red: For this part of the render time, this View is the slowest one in the tree. + For example, a red dot for the draw time means that this View takes the most + time to draw of all the View objects in the tree. + </li> + </ul> + </li> + <li> + View index: The zero-based index of the View in its parent View. If it is the only child, + this is 0. + </li> +</ol> +<p> + When you select a node, additional information for the View appears in a small window above + the node. When you click one of the nodes, you see the following: +</p> +<ul> + <li> + Image: The actual image of the View, as it would appear in the emulator. If the View has + children, these are also displayed. + </li> + <li> + View count: The number of View objects represented by this node. This includes the View + itself and a count of its children. For example, this value is 4 for a View that has 3 + children. + </li> + <li> + Render times: The actual measure, layout, and draw times for the View rendering, in + milliseconds. These represent the same values as the performance indicators mentioned in + the preceding section. + </li> +</ul> +<p> + An annotated screenshot of an individual node in the Tree View window appears in figure 3. +</p> +<img id="Fig3" src="{@docRoot}images/developing/hv_treeview_screenshot.png" alt="" height="600"/> +<p class="img-caption"><strong>Figure 3.</strong> An annotated node in Tree View</p> +<h3 id="hvdebugging">Debugging with View Hierarchy</h3> +<p> + The View Hierarchy window helps you debug an application by providing a static display + of the UI. The display starts with your application's opening screen. As you step through + your application, the display remains unchanged until you redraw it by invalidating and + then requesting layout for a View. +</p> +<p> + To redraw a View in the display: +</p> + <ul> + <li> + Select a View in Tree View. As you move up towards the root of the tree (to the + left in the Tree View), you see the highest-level View objects. Redrawing a high-level + object usually forces the lower-level objects to redraw as well. + </li> + <li> + Click <strong>Invalidate</strong> at the top of the window. This marks the View as + invalid, and schedules it for a redraw at the next point that a layout is requested. + </li> + <li> + Click <strong>Request Layout</strong> to request a layout. The View and its children + are redrawn, as well as any other View objects that need to be redrawn. + </li> + </ul> +<p> + Manually redrawing a View allows you to watch the View object tree and examine the properties of + individual View objects one step at a time as you go through breakpoints in your code. +</p> +<h3 id="hvoptimize">Optimizing with View Hierarchy</h3> +<p> + View Hierarchy also helps you identify slow render performance. You start by looking at the + View nodes with red or yellow performance indicators to identify the slower View objects. As you + step through your application, you can judge if a View is consistently slow or slow only in + certain circumstances. +</p> +<p> + Remember that slow performance is not necessarily evidence of a problem, especially for + ViewGroup objects. View objects that have more children and more complex View objects render + more slowly. +</p> +<p> + The View Hierarchy window also helps you find performance issues. Just by looking at the + performance indicators (the dots) for each View node, you can see which View objects are the + slowest to measure, layout, and draw. From that, you can quickly identify the problems you + should look at first. +</p> +<h2 id="pixelperfect">Using Pixel Perfect</h2> +<p> + Pixel Perfect is a tool for examining pixel properties and laying out UIs from a design drawing. +</p> +<h3 id="aboutpixelperfect">About the Pixel Perfect window</h3> +<p> + The Pixel Perfect window displays a magnified image of the screen that is currently + visible on the emulator or device. In it, you can examine the properties + of individual pixels in the screen image. You can also use the Pixel Perfect window + to help you lay out your application UI based on a bitmap design. +</p> +<p> + To see the Pixel Perfect window, run Hierarchy Viewer, as described in + the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click + <strong>Inspect Screenshot</strong> at the top of the device window. The Pixel Perfect window + appears. +</p> +<p> + In it, you see three panes: +</p> +<ul> + <li> + View Object pane: This is a hierarchical list of the View objects that are currently + visible on the device or emulator screen, including both the ones in your application and + the ones generated by the system. The objects are listed by their View class. + To see the class names of a View object's children, expand the View by clicking the + arrow to its left. When you click a View, its position is highlighted in the Pixel Perfect + pane on the right. + </li> + <li> + Pixel Perfect Loupe pane: This is the magnified screen image. It is overlaid by a grid in + which each square represents one pixel. To look at the information for a pixel, click in its + square. Its color and X,Y coordinates appear at the bottom of the pane. + <p> + The magenta crosshair in the pane corresponds to the positioning + crosshair in the next pane. It only moves when you move the crosshair in the next pane. + </p> + <p> + To zoom in or out on the image, use the <strong>Zoom</strong> slider at the bottom of + the pane, or use your mouse's scroll wheel. + </p> + <p> + When you select a pixel in the Loupe pane, you see the following information at the + bottom of the pane: + </p> + <ul> + <li> + Pixel swatch: A rectangle filled with the same color as the pixel. + </li> + <li> + HTML color code: The hexadecimal RGB code corresponding to the pixel color + </li> + <li> + RGB color values: A list of the (R), green (G), and blue (B) color values of the + pixel color. Each value is in the range 0-255. + </li> + <li> + X and Y coordinates: The pixel's coordinates, in device-specific pixel units. + The values are 0-based, with X=0 at the left of the screen and Y=0 at the top. + </li> + </ul> + </li> + <li> + Pixel Perfect pane: This displays the currently visible screen as it would appear in the + emulator. + <p> + You use the cyan crosshair to do coarse positioning. Drag the crosshair in the image, + and the Loupe crosshair will move accordingly. You can also click on a point in the + Pixel Perfect pane, and the crosshair will move to that point. + </p> + <p> + The image corresponding to the View object selected in the View Object pane is + outlined in a box that indicates the View object's position on the screen. For the + selected object, the box is bold red. Sibling and parent View objects have a light + red box. View objects that are neither parents nor siblings are in white. + </p> + <p> + The layout box may have other rectangles either inside or outside it, each of which + indicates part of the View. A purple or green rectangle indicates the View bounding box. + A white or black box inside the layout box represents the <strong>padding</strong>, the + defined distance between the View object's content and its bounding box. An outer white + or black rectangle represents the <strong>margins</strong>, the distance between the + View bounding box and adjacent View objects. The padding and margin boxes are white if + the layout background is black, and vice versa. + </p> + <p> + You can save the screen image being displayed in the Pixel Perfect pane as a PNG file. + This produces a screenshot of the current screen. To do this, click + <strong>Save as PNG</strong> at the top of the window. This displays a dialog, + in which you can choose a directory and filename for the file. + </p> + </li> +</ul> +<p> + The panes are not automatically refreshed when you change one of the View objects or go to + another Activity. To refresh the Pixel Perfect pane and the Loupe pane, click + <strong>Refresh Screenshot</strong> at the top of the window. This will change the panes + to reflect the current screen image. You still may need to refresh the View Object pane; + to do this, click <strong>Refresh Tree</strong> at the top of the window. +</p> +<p> + To automatically refresh the panes while you are debugging, set + <strong>Auto Refresh</strong> at the top of the window, and then set a refresh rate + with the <strong>Refresh Rate</strong> slider at the bottom of the Loupe pane. +</p> +<h3 id="overlays">Working with Pixel Perfect overlays</h3> +<p> + You often construct a UI based on a design done as a bitmap image. The Pixel Perfect window + helps you match up your View layout to a bitmap image by allowing you to load the bitmap as an + <strong>overlay</strong> on the screen image. +</p> +<p> + To use a bitmap image as an overlay: +</p> +<ul> + <li> + Start your application in a device or emulator and navigate to the Activity whose UI you + want to work with. + </li> + <li> + Start Hierarchy Viewer and navigate to the Pixel Perfect window. + </li> + <li> + At the top of the window, click <strong>Load Overlay</strong>. A dialog opens, prompting + for the image file to load. Load the image file. + </li> + <li> + Pixel Perfect displays the overlay over the screen image in the Pixel Perfect pane. The + lower left corner of the bitmap image (X=0, Y=<em>max value</em>) is anchored on the lower + leftmost pixel (X=0, Y=<em>max screen</em>) of the screen. + <p> + By default, the overlay has a 50% transparency, which allows you to see the screen + image underneath. You can adjust this with the <strong>Overlay:</strong> slider at the + bottom of the Loupe pane. + </p> + <p> + Also by default, the overlay is not displayed in the Loupe pane. To display it, + set <strong>Show in Loupe</strong> at the top of the window. + </p> + </li> +</ul> +<p> + The overlay is not saved as part of the screenshot when you save the screen image as a PNG + file. +</p> +<p> + A screenshot of the Pixel Perfect window appears in figure 4. +</p> +<img id="Fig4" src="{@docRoot}images/developing/hv_pixelperfect.png" + alt="" + height="600"/> +<p class="img-caption"><strong>Figure 4.</strong> The Pixel Perfect window</p> +<h2 id="layoutopt">Using layoutopt</h2> +<p> + The <code>layoutopt</code> tool lets you analyze the XML files that define your + application's UI to find inefficiencies in the view hierarchy.</p> + +<p> + To run the tool, open a terminal and launch <code>layoutopt <xmlfiles></code> + from your SDK <code>tools/</code> directory. The <xmlfiles> argument is a space- + delimited list of resources you want to analyze, either uncompiled resource xml files or + directories of such files. +</p> +<p> + The tool loads the specified XML files and analyzes their definitions and + hierarchies according to a set of predefined rules. For every issue it detects, it + displays the following information: +</p> +<ul> + <li> + The filename in which the issue was detected. + </li> + <li> + The line number for the issue. + </li> + <li> + A description of the issue, and for some types of issues it also suggests a resolution. + </li> +</ul> +<p>The following is a sample of the output from the tool:</p> +<pre> +$ layoutopt samples/ +samples/compound.xml + 7:23 The root-level <FrameLayout/> can be replaced with <merge/> + 11:21 This LinearLayout layout or its FrameLayout parent is useless +samples/simple.xml + 7:7 The root-level <FrameLayout/> can be replaced with <merge/> +samples/too_deep.xml + -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 10! + 20:81 This LinearLayout layout or its LinearLayout parent is useless + 24:79 This LinearLayout layout or its LinearLayout parent is useless + 28:77 This LinearLayout layout or its LinearLayout parent is useless + 32:75 This LinearLayout layout or its LinearLayout parent is useless + 36:73 This LinearLayout layout or its LinearLayout parent is useless + 40:71 This LinearLayout layout or its LinearLayout parent is useless + 44:69 This LinearLayout layout or its LinearLayout parent is useless + 48:67 This LinearLayout layout or its LinearLayout parent is useless + 52:65 This LinearLayout layout or its LinearLayout parent is useless + 56:63 This LinearLayout layout or its LinearLayout parent is useless +samples/too_many.xml + 7:413 The root-level <FrameLayout/> can be replaced with <merge/> + -1:-1 This layout has too many views: 81 views, it should have <= 80! +samples/useless.xml + 7:19 The root-level <FrameLayout/> can be replaced with <merge/> + 11:17 This LinearLayout layout or its FrameLayout parent is useless +</pre> diff --git a/docs/html/tools/debugging/index.jd b/docs/html/tools/debugging/index.jd new file mode 100644 index 0000000..45fbc9e --- /dev/null +++ b/docs/html/tools/debugging/index.jd @@ -0,0 +1,186 @@ +page.title=Debugging +@jd:body + + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li><a href="#stack">Debugging Environment</a></li> + + <li><a href="#addltools">Additional Debugging Tools</a></li> + + <li><a href="#tips">Debugging Tips</a></li> + </ol> + </div> + </div> + + <p>The Android SDK provides most of the tools that you need to debug your applications. You need + a JDWP-compliant debugger if you want to be able to do things such as step through code, + view variable values, and pause execution of an application. If you are using Eclipse, a + JDWP-compliant debugger is already included and there is no setup required. If you are using + another IDE, you can use the debugger that comes with it and attach the debugger to a special + port so it can communicate with the application VMs on your devices. The main components that + comprise a typical Android debugging environment are:</p> + + <dl> + <dt><a href="{@docRoot}tools/help/adb.html"><strong>adb</strong></a></dt> + + <dd><code>adb</code> acts as a middleman between a device and your development system. It provides various + device management capabilities, including moving and syncing files to the emulator, running a + UNIX shell on the device or emulator, and providing a general means to communicate with + connected emulators and devices.</dd> + + <dt><a href="{@docRoot}tools/debugging/ddms.html"><strong>Dalvik Debug Monitor + Server</strong></a></dt> + + <dd>DDMS is a graphical program that communicates with your devices through <code>adb</code>. DDMS can + capture screenshots, gather thread and stack information, spoof incoming calls and SMS + messages, and has many other features.</dd> + + <dt><strong><a href="{@docRoot}tools/device.html">Device</a> or + <a href="{@docRoot}tools/devices/index.html">Android Virtual Device</a></strong></dt> + + <dd>Your application must run in a device or in an AVD so that it can be debugged. An <code>adb</code> device + daemon runs on the device or emulator and provides a means for the <code>adb</code> host daemon to + communicate with the device or emulator.</dd> + + <dt><strong>JDWP debugger</strong></dt> + + <dd>The Dalvik VM (Virtual Machine) supports the JDWP protocol to allow debuggers to attach to + a VM. Each application runs in a VM and exposes a unique port that you can attach a debugger to + via DDMS. If you want to debug multiple applications, attaching to each port might become + tedious, so DDMS provides a port forwarding feature that can forward a specific VM's debugging + port to port 8700. You can switch freely from application to application by highlighting it in the + Devices tab of DDMS. DDMS forwards the appropriate port to port 8700. Most modern Java IDEs include a JDWP debugger, + or you can use a command line debugger such as <a href="http://download.oracle.com/javase/6/docs/technotes/tools/"> + <code>jdb</code></a>.</dd> + </dl> + + <h2>Debugging Environment</h2> + + <p>Figure 1 shows how the various debugging tools work together in a typical + debugging environment.</p> + <img src="{@docRoot}images/debugging.png" + alt="Debugging workflow" /> + <p class="img-caption><strong>Figure 1. </strong> Debugging Workflow</p> + + <p>On your emulator or device, each application runs in its own instance of a Dalvik VM. The <code>adb</code> + device daemon allows communication with the VMs from an outside party.</p> + + <p>On your development machine, the <code>adb</code> host daemon communicates with the <code>adb</code> device daemon and + allows tools such as DDMS to communicate with the device or emulator. The <code>adb</code> host daemon also + allows you to access shell commands on the device as well as providing capabilities such as + application installation and file transferring.</p> + + <p>Each application VM on the device or emulator exposes a debugging port that you can attach to + via DDMS. DDMS can forward any of these ports to a static debugging port (typically port 8700) by + selecting the application that you want to debug in the DDMS user interface. A JDWP debugger can + attach to this static debugging port and debug all the applications that are running on the + device or emulator without having to attach to multiple ports.</p> + + <p>If you are using Eclipse, much of these interconnections are hidden from you. DDMS, <code>adb</code>, and a + JDWP debugger are all setup for you and you can access them through the Debug and DDMS + perspectives in Eclipse. If you are developing in a non-Eclipse environment, you have to invoke + these tools manually.</p> + + <h2 id="addltools">Additional Debugging Tools</h2> + + <p>In addition to the main debugging tools, the Android SDK provides additional tools to help you + debug and profile your applications:</p> + + <dl> + <dt><strong><a href="{@docRoot}tools/debugging/debugging-ui.html">Heirarchy Viewer + and layoutopt</a></strong></dt> + + <dd>Graphical programs that let you debug and profile user interfaces.</dd> + + <dt><strong><a href= + "{@docRoot}tools/debugging/debugging-tracing.html">Traceview</a></strong></dt> + + <dd>A graphical viewer that displays trace file data for method calls and times saved by your + application, which can help you profile the performance of your application.</dd> + + <dt><strong><a href="{@docRoot}tools/debugging/debugging-devtools.html">Dev Tools + Android application</a></strong></dt> + + <dd>The Dev Tools application included in the emulator system image exposes several settings + that provide useful information such as CPU usage and frame rate. You can also transfer the + application to a hardware device.</dd> + </dl> + + + <h2 id="tips">Debugging Tips</h2> + +<p>While debugging, keep these helpful tips in mind to help you figure out common problems with your +applications:</p> + +<dl> +<dt><strong>Dump the stack trace</strong></dt> +<dd>To obtain a stack dump from emulator, you can log +in with <code>adb shell</code>, use <code>ps</code> to find the process you +want, and then <code>kill -3</code>. The stack trace appears in the log file. +</dd> + +<dt><strong>Display useful info on the emulator screen</strong></dt> +<dd>The device can display useful information such as CPU usage or highlights +around redrawn areas. Turn these features on and off in the developer settings +window as described in <a href="{@docRoot}tools/debugging/debugging-devtools.html"> +Debugging with the Dev Tools App</a>. +</dd> + +<dt><strong>Get application and system state information from the emulator</strong></dt> +<dd>You can access dumpstate information from the <code>adb shell</code> commands. See +<a href="{@docRoot}tools/help/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + + + +<dt><strong>Get wireless connectivity information</strong></dt> +<dd>You can get information about wireless connectivity using DDMS. +From the <strong>Device</strong> menu, select <strong>Dump +radio state</strong>.</dd> + +<dt><strong>Log trace data</strong></dt> +<dd>You can log method calls and other tracing data in an activity by calling +{@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a +href="{@docRoot}tools/debugging/debugging-tracing.html">Profiling with Traceview and +dmtracedump</a> for details. </dd> + +<dt><strong>Log radio data</strong></dt> +<dd>By default, radio information is not logged to the system (it is a lot of +data). However, you can enable radio logging using the following commands: + +<pre class="no-pretty-print"> +adb shell +logcat -b radio +</pre> +</dd> + +<dt><strong>Capture screenshots</strong></dt> +<dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select +<strong>Device > Screen capture</strong>.</dd> + +<dt><strong>Use debugging helper classes</strong></dt> +<dd>Android provides debug helper classes such as {@link android.util.Log + util.Log} and {@link android.os.Debug} for your convenience. </dd> + +<dt><strong>Garbage collection</strong></dt> +<dd> +The debugger and garbage collector are currently loosely integrated. The VM guarantees that any +object the debugger is aware of is not garbage collected until after the debugger disconnects. +This can result in a buildup of objects over time while the debugger is connected. For example, +if the debugger sees a running thread, the associated {@link java.lang.Thread} object is not +garbage collected even after the thread terminates. +</dd> + +</dl> + + + + + + + + |