1page.title=Investigating Your RAM Usage 2page.tags="memory","OutOfMemoryError" 3@jd:body 4 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>In this document</h2> 8<ol> 9 <li><a href="#LogMessages">Interpreting Log Messages</a></li> 10 <li><a href="#ViewHeap">Viewing Heap Updates</a></li> 11 <li><a href="#TrackAllocations">Tracking Allocations</a></li> 12 <li><a href="#ViewingAllocations">Viewing Overall Memory Allocations</a></li> 13 <li><a href="#HeapDump">Capturing a Heap Dump</a></li> 14 <li><a href="#TriggerLeaks">Triggering Memory Leaks</a></li> 15</ol> 16 <h2>See Also</h2> 17 <ul> 18 <li><a href="{@docRoot}training/articles/memory.html">Managing Your App's Memory</a></li> 19 </ul> 20 </div> 21 </div> 22 23 24 25 26<p>Because Android is designed for mobile devices, you should always be careful about how much 27random-access memory (RAM) your app uses. Although Android’s Dalvik virtual machine performs 28routine garbage collection, this doesn’t mean you can ignore when and where your app allocates and 29releases memory. In order to provide a stable user experience that allows the system to quickly 30switch between apps, it’s important that your app does not needlessly consume memory when the user 31is not interacting with it.</p> 32 33<p>Even if you follow all the best practices for <a href="{@docRoot}training/articles/memory.html" 34>Managing Your App Memory</a> during 35development (which you should), you still might leak objects or introduce other memory bugs. The 36only way to be certain your app is using as little memory as possible is to analyze your app’s 37memory usage with tools. This guide shows you how to do that.</p> 38 39 40<h2 id="LogMessages">Interpreting Log Messages</h2> 41 42<p>The simplest place to begin investigating your apps memory usage is the Dalvik log messages. You'll 43find these log messages in <a href="{@docRoot}tools/help/logcat.html">logcat</a> (the output is 44available in the Device Monitor or directly in IDEs such as Eclipse and Android Studio).</p> 45 46<p>Every time a garbage collection occurs, logcat prints a message with the following information:</p> 47 48<pre class="no-pretty-print"> 49D/dalvikvm: <GC_Reason> <Amount_freed>, <Heap_stats>, <External_memory_stats>, <Pause_time> 50</pre> 51 52<dl> 53<dt>GC Reason</dt> 54<dd> 55What triggered the garbage collection and what kind of collection it is. Reasons that may appear 56include: 57<dl> 58<dt><code>GC_CONCURRENT</code></dt> 59<dd>A concurrent garbage collection that frees up memory as your heap begins to fill up.</dd> 60 61<dt><code>GC_FOR_MALLOC</code></dt> 62<dd>A garbage collection caused because your app attempted to allocate memory when your heap was 63already full, so the system had to stop your app and reclaim memory.</dd> 64 65<dt><code>GC_HPROF_DUMP_HEAP</code></dt> 66<dd>A garbage collection that occurs when you create an HPROF file to analyze your heap.</dd> 67 68<dt><code>GC_EXPLICIT</code> 69<dd>An explicit garbage collection, such as when you call {@link java.lang.System#gc()} (which you 70should avoid calling and instead trust the garbage collector to run when needed).</dd> 71 72<dt><code>GC_EXTERNAL_ALLOC</code></dt> 73<dd>This happens only on API level 10 and lower (newer versions allocate everything in the Dalvik 74heap). A garbage collection for externally allocated memory (such as the pixel data stored in 75native memory or NIO byte buffers).</dd> 76</dl> 77</dd> 78 79<dt>Amount freed</dt> 80<dd>The amount of memory reclaimed from this garbage collection.</dd> 81 82<dt>Heap stats</dt> 83<dd>Percentage free and (number of live objects)/(total heap size).</dd> 84 85<dt>External memory stats</dt> 86<dd>Externally allocated memory on API level 10 and lower (amount of allocated memory) / (limit at 87which collection will occur).</dd> 88 89<dt>Pause time</dt> 90<dd>Larger heaps will have larger pause times. Concurrent pause times show two pauses: one at the 91beginning of the collection and another near the end.</dd> 92</dl> 93 94<p>For example:</p> 95 96<pre class="no-pretty-print"> 97D/dalvikvm( 9050): GC_CONCURRENT freed 2049K, 65% free 3571K/9991K, external 4703K/5261K, paused 2ms+2ms 98</pre> 99 100<p>As these log messages stack up, look out for increases in the heap stats (the 101{@code 3571K/9991K} value in the above example). If this value 102continues to increase and doesn't ever seem to get smaller, you could have a memory leak.</p> 103 104 105<h2 id="ViewHeap">Viewing Heap Updates</h2> 106 107<p>To get a little information about what kind of memory your app is using and when, you can view 108real-time updates to your app's heap in the Device Monitor:</p> 109 110<ol> 111<li>Open the Device Monitor. 112<p>From your <code><sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p> 113</li> 114<li>In the Debug Monitor window, select your app's process from the list on the left.</li> 115<li>Click <strong>Update Heap</strong> above the process list.</li> 116<li>In the right-side panel, select the <strong>Heap</strong> tab.</li> 117</ol> 118 119<p>The Heap view shows some basic stats about your heap memory usage, updated after every 120garbage collection. To see the first update, click the <strong>Cause GC</strong> button.</p> 121 122<img src="{@docRoot}images/tools/monitor-vmheap@2x.png" width="760" alt="" /> 123<p class="img-caption"><strong>Figure 1.</strong> The Device Monitor tool, 124showing the <strong>[1] Update Heap</strong> and <strong>[2] Cause GC</strong> buttons. 125The Heap tab on the right shows the heap results.</p> 126 127<p>Continue interacting with your app to watch your heap allocation update with each garbage 128collection. This can help you identify which actions in your app are likely causing too much 129allocation and where you should try to reduce allocations and release 130resources.</p> 131 132 133 134<h2 id="TrackAllocations">Tracking Allocations</h2> 135 136<p>As you start narrowing down memory issues, you should also use the Allocation Tracker to 137get a better understanding of where your memory-hogging objects are allocated. The Allocation 138Tracker can be useful not only for looking at specific uses of memory, but also to analyze critical 139code paths in an app such as scrolling.</p> 140 141<p>For example, tracking allocations when flinging a list in your app allows you to see all the 142allocations that need to be done for that behavior, what thread they are on, and where they came 143from. This is extremely valuable for tightening up these paths to reduce the work they need and 144improve the overall smoothness of the UI.</p> 145 146<p>To use Allocation Tracker:</p> 147<ol> 148<li>Open the Device Monitor. 149<p>From your <code><sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p> 150</li> 151<li>In the DDMS window, select your app's process in the left-side panel.</li> 152<li>In the right-side panel, select the <strong>Allocation Tracker</strong> tab.</li> 153<li>Click <strong>Start Tracking</strong>.</li> 154<li>Interact with your app to execute the code paths you want to analyze.</li> 155<li>Click <strong>Get Allocations</strong> every time you want to update the 156list of allocations.</li> 157 </ol> 158 159<p>The list shows all recent allocations, 160currently limited by a 512-entry ring buffer. Click on a line to see the stack trace that led to 161the allocation. The trace shows you not only what type of object was allocated, but also in which 162thread, in which class, in which file and at which line.</p> 163 164<img src="{@docRoot}images/tools/monitor-tracker@2x.png" width="760" alt="" /> 165<p class="img-caption"><strong>Figure 2.</strong> The Device Monitor tool, 166showing recent app allocations and stack traces in the Allocation Tracker.</p> 167 168 169<p class="note"><strong>Note:</strong> You will always see some allocations from {@code 170DdmVmInternal} and else where that come from the allocation tracker itself.</p> 171 172<p>Although it's not necessary (nor possible) to remove all allocations for your performance 173critical code paths, the allocation tracker can help you identify important issues in your code. 174For instance, some apps might create a new {@link android.graphics.Paint} object on every draw. 175Moving that object into a global member is a simple fix that helps improve performance.</p> 176 177 178 179 180 181 182<h2 id="ViewingAllocations">Viewing Overall Memory Allocations</h2> 183 184<p>For further analysis, you may want to observe how that your app's memory is 185divided between different categories, which you can do with the <code>adb meminfo</code> data.</p> 186 187<p>When talking about how much RAM your app is using with this data, the key metrics 188discussed below are:</p> 189 190<dl> 191<dt>Private (Clean and Dirty) RAM</dt> 192<dd>This is memory that is being used by only your process. This is the bulk of the RAM that the system 193can reclaim when your app’s process is destroyed. Generally, the most important portion of this is 194“private dirty” RAM, which is the most expensive because it is used by only your process and its 195contents exist only in RAM so can’t be paged to storage (because Android does not use swap). All 196Dalvik and native heap allocations you make will be private dirty RAM; Dalvik and native 197allocations you share with the Zygote process are shared dirty RAM.</dd> 198 199<dt>Proportional Set Size (PSS)</dt> 200<dd>This is a measurement of your app’s RAM use that takes into account sharing pages across processes. 201Any RAM pages that are unique to your process directly contribute to its PSS value, while pages 202that are shared with other processes contribute to the PSS value only in proportion to the amount 203of sharing. For example, a page that is shared between two processes will contribute half of its 204size to the PSS of each process.</dd> 205</dl> 206 207 208<p>A nice characteristic of the PSS measurement is that you can add up the PSS across all processes to 209determine the actual memory being used by all processes. This means PSS is a good measure for the 210actual RAM weight of a process and for comparison against the RAM use of other processes and the 211total available RAM.</p> 212 213<p>You can look at the memory use of your app (measured in kilobytes) with the 214following adb command:</p> 215 216<pre class="no-pretty-print"> 217adb shell dumpsys meminfo <package_name> 218</pre> 219 220<p>For example, below is the the output for Gmail’s process on a tablet device. There is a lot of 221information here, but key points for discussion are highlighted in different colors.</p> 222 223<p class="note"><strong>Note:</strong> The information you see may vary slightly from what is shown 224here, as some details of the output differ across platform versions.</p> 225 226<pre class="no-pretty-print"> 227** MEMINFO in pid 9953 [com.google.android.gm] ** 228 Pss Pss Shared Private Shared Private Heap Heap Heap 229 Total Clean Dirty Dirty Clean Clean Size Alloc Free 230 ------ ------ ------ ------ ------ ------ ------ ------ ------ 231 Native Heap 0 0 0 0 0 0 7800 7637(6) 126 232 Dalvik Heap 5110(3) 0 4136 4988(3) 0 0 9168 8958(6) 210 233 Dalvik Other 2850 0 2684 2772 0 0 234 Stack 36 0 8 36 0 0 235 Cursor 136 0 0 136 0 0 236 Ashmem 12 0 28 0 0 0 237 Other dev 380 0 24 376 0 4 238 .so mmap 5443(5) 1996 2584 2664(5) 5788 1996(5) 239 .apk mmap 235 32 0 0 1252 32 240 .ttf mmap 36 12 0 0 88 12 241 .dex mmap 3019(5) 2148 0 0 8936 2148(5) 242 Other mmap 107 0 8 8 324 68 243 Unknown 6994(4) 0 252 6992(4) 0 0 244 TOTAL 24358(1) 4188 9724 17972(2)16388 4260(2)16968 16595 336 245 246 Objects 247 Views: 426 ViewRootImpl: 3(8) 248 AppContexts: 6(7) Activities: 2(7) 249 Assets: 2 AssetManagers: 2 250 Local Binders: 64 Proxy Binders: 34 251 Death Recipients: 0 252 OpenSSL Sockets: 1 253 254 SQL 255 MEMORY_USED: 1739 256 PAGECACHE_OVERFLOW: 1164 MALLOC_SIZE: 62 257</pre> 258 259<p>Generally, you should be concerned with only the <code>Pss Total</code> and <code>Private Dirty</code> 260columns. In some cases, the <code>Private Clean</code> and <code>Heap Alloc</code> columns also offer 261interesting data. Here is some more information about the different memory allocations (the rows) 262you should observe: 263 264<dl> 265<dt><code>Dalvik Heap</code></dt> 266<dd>The RAM used by Dalvik allocations in your app. The <code>Pss Total</code> includes all Zygote 267allocations (weighted by their sharing across processes, as described in the PSS definition above). 268The <code>Private Dirty</code> number is the actual RAM committed to only your app’s heap, composed of 269your own allocations and any Zygote allocation pages that have been modified since forking your 270app’s process from Zygote. 271 272<p class="note"><strong>Note:</strong> On newer platform versions that have the <code>Dalvik 273Other</code> section, the <code>Pss Total</code> and <code>Private Dirty</code> numbers for Dalvik Heap do 274not include Dalvik overhead such as the just-in-time compilation (JIT) and garbage collection (GC) 275bookkeeping, whereas older versions list it all combined under <code>Dalvik</code>.</p> 276 277<p>The <code>Heap Alloc</code> is the amount of memory that the Dalvik and native heap allocators keep 278track of for your app. This value is larger than <code>Pss Total</code> and <code>Private Dirty</code> 279because your process was forked from Zygote and it includes allocations that your process shares 280with all the others.</p> 281</dd> 282 283<dt><code>.so mmap</code> and <code>.dex mmap</code></dt> 284<dd>The RAM being used for mmapped <code>.so</code> (native) and <code>.dex</code> (Dalvik) code. The 285<code>Pss Total</code> number includes platform code shared across apps; the <code>Private Clean</code> is 286your app’s own code. Generally, the actual mapped size will be much larger—the RAM here is only 287what currently needs to be in RAM for code that has been executed by the app. However, the .so mmap 288has a large private dirty, which is due to fix-ups to the native code when it was loaded into its 289final address. 290</dd> 291 292<dt><code>Unknown</code></dt> 293<dd>Any RAM pages that the system could not classify into one of the other more specific items. 294Currently, this contains mostly native allocations, which cannot be identified by the tool when 295collecting this data due to Address Space Layout Randomization (ASLR). As with the Dalvik heap, the 296<code>Pss Total</code> for Unknown takes into account sharing with Zygote, and <code>Private Dirty</code> 297is unknown RAM dedicated to only your app. 298</dd> 299 300<dt><code>TOTAL</code></dt> 301<dd>The total Proportional Set Size (PSS) RAM used by your process. This is the sum of all PSS fields 302above it. It indicates the overall memory weight of your process, which can be directly compared 303with other processes and the total available RAM. 304 305<p>The <code>Private Dirty</code> and <code>Private Clean</code> are the total allocations within your 306process, which are not shared with other processes. Together (especially <code>Private Dirty</code>), 307this is the amount of RAM that will be released back to the system when your process is destroyed. 308Dirty RAM is pages that have been modified and so must stay committed to RAM (because there is no 309swap); clean RAM is pages that have been mapped from a persistent file (such as code being 310executed) and so can be paged out if not used for a while.</p> 311 312</dd> 313 314<dt><code>ViewRootImpl</code></dt> 315<dd>The number of root views that are active in your process. Each root view is associated with a 316window, so this can help you identify memory leaks involving dialogs or other windows. 317</dd> 318 319<dt><code>AppContexts</code> and <code>Activities</code></dt> 320<dd>The number of app {@link android.content.Context} and {@link android.app.Activity} objects that 321currently live in your process. This can be useful to quickly identify leaked {@link 322android.app.Activity} objects that can’t be garbage collected due to static references on them, 323which is common. These objects often have a lot of other allocations associated with them and so 324are a good way to track large memory leaks.</dd> 325 326<p class="note"><strong>Note:</strong> A {@link android.view.View} or {@link 327android.graphics.drawable.Drawable} object also holds a reference to the {@link 328android.app.Activity} that it's from, so holding a {@link android.view.View} or {@link 329android.graphics.drawable.Drawable} object can also lead to your app leaking an {@link 330android.app.Activity}.</p> 331 332</dd> 333</dl> 334 335 336 337 338 339 340 341 342 343<h2 id="HeapDump">Capturing a Heap Dump</h2> 344 345<p>A heap dump is a snapshot of all the objects in your app's heap, stored in a binary format called 346HPROF. Your app's heap dump provides information about the overall state of your app's heap so you 347can track down problems you might have identified while viewing heap updates.</p> 348 349<p>To retrieve your heap dump:</p> 350<ol> 351<li>Open the Device Monitor. 352<p>From your <code><sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p> 353</li> 354<li>In the DDMS window, select your app's process in the left-side panel.</li> 355<li>Click <strong>Dump HPROF file</strong>, shown in figure 3.</li> 356<li>In the window that appears, name your HPROF file, select the save location, 357then click <strong>Save</strong>.</li> 358</ol> 359 360<img src="{@docRoot}images/tools/monitor-hprof@2x.png" width="760" alt="" /> 361<p class="img-caption"><strong>Figure 3.</strong> The Device Monitor tool, 362showing the <strong>[1] Dump HPROF file</strong> button.</p> 363 364<p>If you need to be more precise about when the dump is created, you can also create a heap dump 365at the critical point in your app code by calling {@link android.os.Debug#dumpHprofData 366dumpHprofData()}.</p> 367 368<p>The heap dump is provided in a format that's similar to, but not identical to one from the Java 369HPROF tool. The major difference in an Android heap dump is due to the fact that there are a large 370number of allocations in the Zygote process. But because the Zygote allocations are shared across 371all app processes, they don’t matter very much to your own heap analysis.</p> 372 373<p>To analyze your heap dump, you can use a standard tool like jhat or the <a href= 374"http://www.eclipse.org/mat/downloads.php">Eclipse Memory Analyzer Tool</a> (MAT). However, first 375you'll need to convert the HPROF file from Android's format to the J2SE HPROF format. You can do 376this using the <code>hprof-conv</code> tool provided in the <code><sdk>/tools/</code> 377directory. Simply run the <code>hprof-conv</code> command with two arguments: the original HPROF 378file and the location to write the converted HPROF file. For example:</p> 379 380<pre class="no-pretty-print"> 381hprof-conv heap-original.hprof heap-converted.hprof 382</pre> 383 384<p class="note"><strong>Note:</strong> If you're using the version of DDMS that's integrated into 385Eclipse, you do not need to perform the HPROF converstion—it performs the conversion by 386default.</p> 387 388<p>You can now load the converted file in MAT or another heap analysis tool that understands 389the J2SE HPROF format.</p> 390 391<p>When analyzing your heap, you should look for memory leaks caused by:</p> 392<ul> 393<li>Long-lived references to an Activity, Context, View, Drawable, and other objects that may hold a 394reference to the container Activity or Context.</li> 395<li>Non-static inner classes (such as a Runnable, which can hold the Activity instance).</li> 396<li>Caches that hold objects longer than necessary.</li> 397</ul> 398 399 400<h3 id="EclipseMat">Using the Eclipse Memory Analyzer Tool</h3> 401 402<p>The <a href= 403"http://www.eclipse.org/mat/downloads.php">Eclipse Memory Analyzer Tool</a> (MAT) is just one 404tool that you can use to analyze your heap dump. It's also quite powerful so most of its 405capabilities are beyond the scope of this document, but here are a few tips to get you started. 406 407<p>Once you open your converted HPROF file in MAT, you'll see a pie chart in the Overview, 408showing what your largest objects are. Below this chart, are links to couple of useful features:</p> 409 410<ul> 411 <li>The <strong>Histogram view</strong> shows a list of all classes and how many instances 412 there are of each. 413 <p>You might want to use this view to find extra instances of classes for which you know there 414 should be only a certain number. For example, a common source of leaks is additional instance of 415 your {@link android.app.Activity} class, for which you should usually have only one instance 416 at a time. To find a specific class instance, type the class name into the <em><Regex></em> 417 field at the top of the list. 418 <p>When you find a class with too many instances, right-click it and select 419 <strong>List objects</strong> > <strong>with incoming references</strong>. In the list that 420 appears, you can determine where an instance is retained by right-clicking it and selecting 421 <strong>Path To GC Roots</strong> > <strong>exclude weak references</strong>.</p> 422 </li> 423 424 <li>The <strong>Dominator tree</strong> shows a list of objects organized by the amount 425 of retained heap. 426 <p>What you should look for is anything that's retaining a portion of heap that's roughly 427 equivalent to the memory size you observed leaking from the <a href="#LogMessages">GC logs</a>, 428 <a href="#ViewHeap">heap updates</a>, or <a href="#TrackAllocations">allocation 429 tracker</a>. 430 <p>When you see something suspicious, right-click on the item and select 431 <strong>Path To GC Roots</strong> > <strong>exclude weak references</strong>. This opens a 432 new tab that traces the references to that object which is causing the alleged leak.</p> 433 434 <p class="note"><strong>Note:</strong> Most apps will show an instance of 435 {@link android.content.res.Resources} near the top with a good chunk of heap, but this is 436 usually expected when your app uses lots of resources from your {@code res/} directory.</p> 437 </li> 438</ul> 439 440 441<img src="{@docRoot}images/tools/mat-histogram@2x.png" width="760" alt="" /> 442<p class="img-caption"><strong>Figure 4.</strong> The Eclipse Memory Analyzer Tool (MAT), 443showing the Histogram view and a search for "MainActivity".</p> 444 445<p>For more information about MAT, watch the Google I/O 2011 presentation, 446<a href="http://www.youtube.com/watch?v=_CruQY55HOk">Memory management for Android apps</a>, 447which includes a walkthrough using MAT beginning at about <a href= 448"http://www.youtube.com/watch?v=_CruQY55HOk&feature=player_detailpage#t=1270">21:10</a>. 449Also refer to the <a href="http://wiki.eclipse.org/index.php/MemoryAnalyzer">Eclipse Memory 450Analyzer documentation</a>.</p> 451 452<h4 id="MatCompare">Comparing heap dumps</h4> 453 454<p>You may find it useful to compare your app's heap state at two different points in time in order 455to inspect the changes in memory allocation. To compare two heap dumps using MAT:</p> 456 457<ol> 458 <li>Create two HPROF files as described above, in <a href="#HeapDump">Capturing a Heap Dump</a>. 459 <li>Open the first HPROF file in MAT (<strong>File</strong> > <strong>Open Heap Dump</strong>). 460 <li>In the Navigation History view (if not visible, select <strong>Window</strong> > 461 <strong>Navigation History</strong>), right-click on <strong>Histogram</strong> and select 462 <strong>Add to Compare Basket</strong>. 463 <li>Open the second HPROF file and repeat steps 2 and 3. 464 <li>Switch to the <em>Compare Basket</em> view and click <strong>Compare the Results</strong> 465 (the red "!" icon in the top-right corner of the view). 466</ol> 467 468 469 470 471 472 473<h2 id="TriggerLeaks">Triggering Memory Leaks</h2> 474 475<p>While using the tools described above, you should aggressively stress your app code and try 476forcing memory leaks. One way to provoke memory leaks in your app is to let it 477run for a while before inspecting the heap. Leaks will trickle up to the top of the allocations in 478the heap. However, the smaller the leak, the longer you need to run the app in order to see it.</p> 479 480<p>You can also trigger a memory leak in one of the following ways:</p> 481<ol> 482<li>Rotate the device from portrait to landscape and back again multiple times while in different 483activity states. Rotating the device can often cause an app to leak an {@link android.app.Activity}, 484{@link android.content.Context}, or {@link android.view.View} object because the system 485recreates the {@link android.app.Activity} and if your app holds a reference 486to one of those objects somewhere else, the system can't garbage collect it.</li> 487<li>Switch between your app and another app while in different activity states (navigate to 488the Home screen, then return to your app).</li> 489</ol> 490 491<p class="note"><strong>Tip:</strong> You can also perform the above steps by using the "monkey" 492test framework. For more information on running the monkey test framework, read the <a href= 493"{@docRoot}tools/help/monkeyrunner_concepts.html">monkeyrunner</a> 494documentation.</p>
