docs/html/tools/debugging/debugging-memory.jd

page.title=Investigating Your RAM Usage
page.tags=memory,OutOfMemoryError
@jd:body

 <div id="qv-wrapper">
    <div id="qv">
      <h2>In this document</h2>
<ol>
  <li><a href="#LogMessages">Interpreting Log Messages</a></li>
  <li><a href="#ViewHeap">Viewing Heap Updates</a></li>
  <li><a href="#TrackAllocations">Tracking Allocations</a></li>
  <li><a href="#ViewingAllocations">Viewing Overall Memory Allocations</a></li>
  <li><a href="#HeapDump">Capturing a Heap Dump</a></li>
  <li><a href="#TriggerLeaks">Triggering Memory Leaks</a></li>
</ol>
      <h2>See Also</h2>
      <ul>
        <li><a href="{@docRoot}training/articles/memory.html">Managing Your App's Memory</a></li>
      </ul>
    </div>
  </div>




<p>Because Android is designed for mobile devices, you should always be careful about how much
random-access memory (RAM) your application uses. Although Dalvik and ART perform
routine garbage collection (GC), this doesn’t mean you can ignore when and where your application allocates and
releases memory. In order to provide a stable user experience that allows the system to quickly
switch between apps, it is important that your application does not needlessly consume memory when the user
is not interacting with it.</p>

<p>Even if you follow all the best practices for <a href="{@docRoot}training/articles/memory.html"
>Managing Your App Memory</a> during
development (which you should), you still might leak objects or introduce other memory bugs. The
only way to be certain your application is using as little memory as possible is to analyze your app’s
memory usage with tools. This guide shows you how to do that.</p>


<h2 id="LogMessages">Interpreting Log Messages</h2>

<p>The simplest place to begin investigating your application’s memory usage is the runtime log messages.
Sometimes when a GC occurs, a message is printed to
<a href="{@docRoot}tools/help/logcat.html">logcat</a>. The logcat output is also available in the
Device Monitor or directly in IDEs such as Eclipse and Android Studio.</p>

<h3 id="DalvikLogMessages">Dalvik Log Messages</h3>

<p>In Dalvik (but not ART), every GC prints the following information to logcat:</p>

<pre class="no-pretty-print">
D/dalvikvm: &lt;GC_Reason> &lt;Amount_freed>, &lt;Heap_stats>, &lt;External_memory_stats>, &lt;Pause_time>
</pre>

<p>Example:</p>

<pre class="no-pretty-print">
D/dalvikvm( 9050): GC_CONCURRENT freed 2049K, 65% free 3571K/9991K, external 4703K/5261K, paused 2ms+2ms
</pre>

<dl>
<dt>GC Reason</dt>
<dd>
What triggered the GC and what kind of collection it is. Reasons that may appear
include:
<dl>
<dt><code>GC_CONCURRENT</code></dt>
<dd>A concurrent GC that frees up memory as your heap begins to fill up.</dd>

<dt><code>GC_FOR_MALLOC</code></dt>
<dd>A GC caused because your application attempted to allocate memory when your heap was
already full, so the system had to stop your application and reclaim memory.</dd>

<dt><code>GC_HPROF_DUMP_HEAP</code></dt>
<dd>A GC that occurs when you request to create an HPROF file to analyze your heap.</dd>

<dt><code>GC_EXPLICIT</code>
<dd>An explicit GC, such as when you call {@link java.lang.System#gc()} (which you
should avoid calling and instead trust the GC to run when needed).</dd>

<dt><code>GC_EXTERNAL_ALLOC</code></dt>
<dd>This happens only on API level 10 and lower (newer versions allocate everything in the Dalvik
heap). A GC for externally allocated memory (such as the pixel data stored in
native memory or NIO byte buffers).</dd>
</dl>
</dd>

<dt>Amount freed</dt>
<dd>The amount of memory reclaimed from this GC.</dd>

<dt>Heap stats</dt>
<dd>Percentage free of the heap and (number of live objects)/(total heap size).</dd>

<dt>External memory stats</dt>
<dd>Externally allocated memory on API level 10 and lower (amount of allocated memory) / (limit at
which collection will occur).</dd>

<dt>Pause time</dt>
<dd>Larger heaps will have larger pause times. Concurrent pause times show two pauses: one at the
beginning of the collection and another near the end.</dd>
</dl>

<p>As these log messages accumulate, look out for increases in the heap stats (the
{@code 3571K/9991K} value in the above example). If this value continues to increase, you may have
a memory leak.</p>


<h3 id="ARTLogMessages">ART Log Messages</h3>

<p>Unlike Dalvik, ART doesn't log messqages for GCs that were not explicity requested. GCs are only
printed when they are they are deemed slow. More precisely, if the GC pause exceeds than 5ms or
the GC duration exceeds 100ms. If the application is not in a pause perceptible process state,
then none of its GCs are deemed slow. Explicit GCs are always logged.</p>

<p>ART includes the following information in its garbage collection log messages:</p>

<pre class="no-pretty-print">
I/art: &lt;GC_Reason> &lt;GC_Name> &lt;Objects_freed>(&lt;Size_freed>) AllocSpace Objects, &lt;Large_objects_freed>(&lt;Large_object_size_freed>) &lt;Heap_stats> LOS objects, &lt;Pause_time(s)>
</pre>

<p>Example:</p>

<pre class="no-pretty-print">
I/art : Explicit concurrent mark sweep GC freed 104710(7MB) AllocSpace objects, 21(416KB) LOS objects, 33% free, 25MB/38MB, paused 1.230ms total 67.216ms
</pre>

<dl>
<dt>GC Reason</dt>
<dd>
What triggered the GC and what kind of collection it is. Reasons that may appear
include:
<dl>
<dt><code>Concurrent</code></dt>
<dd>A concurrent GC which does not suspend application threads. This GC runs in a background thread
and does not prevent allocations.</dd>

<dt><code>Alloc</code></dt>
<dd>The GC was initiated because your application attempted to allocate memory when your heap
was already full. In this case, the garbage collection occurred in the allocating thread.</dd>

<dt><code>Explicit</code>
<dd>The garbage collection was explicitly requested by an application, for instance, by
calling {@link java.lang.System#gc()} or {@link java.lang.Runtime#gc()}. As with Dalvik, in ART it is
recommended that you trust the GC and avoid requesting explicit GCs if possible. Explicit GCs are
discouraged since they block the allocating thread and unnecessarily was CPU cycles. Explicit GCs
could also cause jank if they cause other threads to get preempted.</dd>

<dt><code>NativeAlloc</code></dt>
<dd>The collection was caused by native memory pressure from native allocations such as Bitmaps or
RenderScript allocation objects.</dd>

<dt><code>CollectorTransition</code></dt>
<dd>The collection was caused by a heap transition; this is caused by switching the GC at run time.
Collector transitions consist of copying all the objects from a free-list backed
space to a bump pointer space (or visa versa). Currently collector transitions only occur when an
application changes process states from a pause perceptible state to a non pause perceptible state
(or visa versa) on low RAM devices.
</dd>

<dt><code>HomogeneousSpaceCompact</code></dt>
<dd>Homogeneous space compaction is free-list space to free-list space compaction which usually
occurs when an application is moved to a pause imperceptible process state. The main reasons for doing
this are reducing RAM usage and defragmenting the heap.
</dd>

<dt><code>DisableMovingGc</code></dt>
<dd>This is not a real GC reason, but a note that collection was blocked due to use of
GetPrimitiveArrayCritical. while concurrent heap compaction is occuring. In general, the use of
GetPrimitiveArrayCritical is strongly discouraged due to its restrictions on moving collectors.
</dd>

<dt><code>HeapTrim</code></dt>
<dd>This is not a GC reason, but a note that collection was blocked until a heap trim finished.
</dd>

</dl>
</dd>


<dl>
<dt>GC Name</dt>
<dd>
ART has various different GCs which can get run.
<dl>
<dt><code>Concurrent mark sweep (CMS)</code></dt>
<dd>A whole heap collector which frees collects all spaces other than the image space.</dd>

<dt><code>Concurrent partial mark sweep</code></dt>
<dd>A mostly whole heap collector which collects all spaces other than the image and zygote spaces.
</dd>

<dt><code>Concurrent sticky mark sweep</code></dt>
<dd>A generational collector which can only free objects allocated since the last GC. This garbage
collection is run more often than a full or partial mark sweep since it is faster and has lower pauses.
</dd>

<dt><code>Marksweep + semispace</code></dt>
<dd>A non concurrent, copying GC used for heap transitions as well as homogeneous space
compaction (to defragement the heap).</dd>

</dl>
</dd>

<dt>Objects freed</dt>
<dd>The number of objects which were reclaimed from this GC from the non large
object space.</dd>

<dt>Size freed</dt>
<dd>The number of bytes which were reclaimed from this GC from the non large object
space.</dd>

<dt>Large objects freed</dt>
<dd>The number of object in the large object space which were reclaimed from this garbage
collection.</dd>

<dt>Large object size freed</dt>
<dd>The number of bytes in the large object space which were reclaimed from this garbage
collection.</dd>

<dt>Heap stats</dt>
<dd>Percentage free and (number of live objects)/(total heap size).</dd>

<dt>Pause times</dt>
<dd>In general pause times are proportional to the number of object references which were modified
while the GC was running. Currently, the ART CMS GCs only has one pause, near the end of the GC.
The moving GCs have a long pause which lasts for the majority of the GC duration.</dd>
</dl>

<p>If you are seeing a large amount of GCs in logcat, look for increases in the heap stats (the
{@code 25MB/38MB} value in the above example). If this value continues to increase and doesn't
ever seem to get smaller, you could have a memory leak. Alternatively, if you are seeing GC which
are for the reason "Alloc", then you are already operating near your heap capacity and can expect
OOM exceptios in the near future. </p>

<h2 id="ViewHeap">Viewing Heap Updates</h2>

<p>To get a little information about what kind of memory your application is using and when, you can view
real-time updates to your app's heap in the Device Monitor:</p>

<ol>
<li>Open the Device Monitor.
<p>From your <code>&lt;sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p>
</li>
<li>In the Debug Monitor window, select your app's process from the list on the left.</li>
<li>Click <strong>Update Heap</strong> above the process list.</li>
<li>In the right-side panel, select the <strong>Heap</strong> tab.</li>
</ol>

<p>The Heap view shows some basic stats about your heap memory usage, updated after every
GC. To see the first update, click the <strong>Cause GC</strong> button.</p>

<img src="{@docRoot}images/tools/monitor-vmheap@2x.png" width="760" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> The Device Monitor tool,
showing the <strong>[1] Update Heap</strong> and <strong>[2] Cause GC</strong> buttons.
The Heap tab on the right shows the heap results.</p>

<p>Continue interacting with your application to watch your heap allocation update with each garbage
collection. This can help you identify which actions in your application are likely causing too much
allocation and where you should try to reduce allocations and release
resources.</p>



<h2 id="TrackAllocations">Tracking Allocations</h2>

<p>As you start narrowing down memory issues, you should also use the Allocation Tracker to
get a better understanding of where your memory-hogging objects are allocated. The Allocation
Tracker can be useful not only for looking at specific uses of memory, but also to analyze critical
code paths in an application such as scrolling.</p>

<p>For example, tracking allocations when flinging a list in your application allows you to see all the
allocations that need to be done for that behavior, what thread they are on, and where they came
from. This is extremely valuable for tightening up these paths to reduce the work they need and
improve the overall smoothness of the UI.</p>

<p>To use Allocation Tracker:</p>
<ol>
<li>Open the Device Monitor.
<p>From your <code>&lt;sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p>
</li>
<li>In the DDMS window, select your app's process in the left-side panel.</li>
<li>In the right-side panel, select the <strong>Allocation Tracker</strong> tab.</li>
<li>Click <strong>Start Tracking</strong>.</li>
<li>Interact with your application to execute the code paths you want to analyze.</li>
<li>Click <strong>Get Allocations</strong> every time you want to update the
list of allocations.</li>
 </ol>

<p>The list shows all recent allocations,
currently limited by a 512-entry ring buffer. Click on a line to see the stack trace that led to
the allocation. The trace shows you not only what type of object was allocated, but also in which
thread, in which class, in which file and at which line.</p>

<img src="{@docRoot}images/tools/monitor-tracker@2x.png" width="760" alt="" />
<p class="img-caption"><strong>Figure 2.</strong> The Device Monitor tool,
showing recent application allocations and stack traces in the Allocation Tracker.</p>


<p class="note"><strong>Note:</strong> You will always see some allocations from {@code
DdmVmInternal} and else where that come from the allocation tracker itself.</p>

<p>Although it's not necessary (nor possible) to remove all allocations for your performance
critical code paths, the allocation tracker can help you identify important issues in your code.
For instance, some apps might create a new {@link android.graphics.Paint} object on every draw.
Moving that object into a global member is a simple fix that helps improve performance.</p>






<h2 id="ViewingAllocations">Viewing Overall Memory Allocations</h2>

<p>For further analysis, you may want to observe how your app's memory is
divided between different types of RAM allocation with the
following <a href="{@docRoot}tools/help/adb.html">adb</a> command:</p>

<pre class="no-pretty-print">
adb shell dumpsys meminfo &lt;package_name|pid> [-d]
</pre>

<p>The -d flag prints more info related to Dalvik and ART memory usage.</p>

<p>The output lists all of your app's current allocations, measured in kilobytes.</p>

<p>When inspecting this information, you should be familiar with the
following types of allocation:</p>

<dl>
<dt>Private (Clean and Dirty) RAM</dt>
<dd>This is memory that is being used by only your process. This is the bulk of the RAM that the system
can reclaim when your app’s process is destroyed. Generally, the most important portion of this is
“private dirty” RAM, which is the most expensive because it is used by only your process and its
contents exist only in RAM so can’t be paged to storage (because Android does not use swap). All
Dalvik and native heap allocations you make will be private dirty RAM; Dalvik and native
allocations you share with the Zygote process are shared dirty RAM.</dd>

<dt>Proportional Set Size (PSS)</dt>
<dd>This is a measurement of your app’s RAM use that takes into account sharing pages across processes.
Any RAM pages that are unique to your process directly contribute to its PSS value, while pages
that are shared with other processes contribute to the PSS value only in proportion to the amount
of sharing. For example, a page that is shared between two processes will contribute half of its
size to the PSS of each process.</dd>
</dl>


<p>A nice characteristic of the PSS measurement is that you can add up the PSS across all processes to
determine the actual memory being used by all processes. This means PSS is a good measure for the
actual RAM weight of a process and for comparison against the RAM use of other processes and the
total available RAM.</p>


<p>For example, below is the the output for Map’s process on a Nexus 5 device. There is a lot of
information here, but key points for discussion are listed below.</p>
<code>adb shell dumpsys meminfo com.google.android.apps.maps -d</code>

<p class="note"><strong>Note:</strong> The information you see may vary slightly from what is shown
here, as some details of the output differ across platform versions.</p>

<pre class="no-pretty-print">
** MEMINFO in pid 18227 [com.google.android.apps.maps] **
                   Pss  Private  Private  Swapped     Heap     Heap     Heap
                 Total    Dirty    Clean    Dirty     Size    Alloc     Free
                ------   ------   ------   ------   ------   ------   ------
  Native Heap    10468    10408        0        0    20480    14462     6017
  Dalvik Heap    34340    33816        0        0    62436    53883     8553
 Dalvik Other      972      972        0        0
        Stack     1144     1144        0        0
      Gfx dev    35300    35300        0        0
    Other dev        5        0        4        0
     .so mmap     1943      504      188        0
    .apk mmap      598        0      136        0
    .ttf mmap      134        0       68        0
    .dex mmap     3908        0     3904        0
    .oat mmap     1344        0       56        0
    .art mmap     2037     1784       28        0
   Other mmap       30        4        0        0
   EGL mtrack    73072    73072        0        0
    GL mtrack    51044    51044        0        0
      Unknown      185      184        0        0
        TOTAL   216524   208232     4384        0    82916    68345    14570

 Dalvik Details
        .Heap     6568     6568        0        0
         .LOS    24771    24404        0        0
          .GC      500      500        0        0
    .JITCache      428      428        0        0
      .Zygote     1093      936        0        0
   .NonMoving     1908     1908        0        0
 .IndirectRef       44       44        0        0

 Objects
               Views:       90         ViewRootImpl:        1
         AppContexts:        4           Activities:        1
              Assets:        2        AssetManagers:        2
       Local Binders:       21        Proxy Binders:       28
       Parcel memory:       18         Parcel count:       74
    Death Recipients:        2      OpenSSL Sockets:        2
</pre>

<p>Here is an older dumpsys on Dalvik of the gmail app:</p>

<pre class="no-pretty-print">
** MEMINFO in pid 9953 [com.google.android.gm] **
                 Pss     Pss  Shared Private  Shared Private    Heap    Heap    Heap
               Total   Clean   Dirty   Dirty   Clean   Clean    Size   Alloc    Free
              ------  ------  ------  ------  ------  ------  ------  ------  ------
  Native Heap      0       0       0       0       0       0    7800    7637(6)  126
  Dalvik Heap   5110(3)    0    4136    4988(3)    0       0    9168    8958(6)  210
 Dalvik Other   2850       0    2684    2772       0       0
        Stack     36       0       8      36       0       0
       Cursor    136       0       0     136       0       0
       Ashmem     12       0      28       0       0       0
    Other dev    380       0      24     376       0       4
     .so mmap   5443(5) 1996    2584    2664(5) 5788    1996(5)
    .apk mmap    235      32       0       0    1252      32
    .ttf mmap     36      12       0       0      88      12
    .dex mmap   3019(5) 2148       0       0    8936    2148(5)
   Other mmap    107       0       8       8     324      68
      Unknown   6994(4)    0     252    6992(4)    0       0
        TOTAL  24358(1) 4188    9724   17972(2)16388    4260(2)16968   16595     336

 Objects
               Views:    426         ViewRootImpl:        3(8)
         AppContexts:      6(7)        Activities:        2(7)
              Assets:      2        AssetManagers:        2
       Local Binders:     64        Proxy Binders:       34
    Death Recipients:      0
     OpenSSL Sockets:      1

 SQL
         MEMORY_USED:   1739
  PAGECACHE_OVERFLOW:   1164          MALLOC_SIZE:       62
</pre>

<p>Generally, you should be concerned with only the <code>Pss Total</code> and <code>Private Dirty</code>
columns. In some cases, the <code>Private Clean</code> and <code>Heap Alloc</code> columns also offer
interesting data. Here is some more information about the different memory allocations (the rows)
you should observe:

<dl>
<dt><code>Dalvik Heap</code></dt>
<dd>The RAM used by Dalvik allocations in your app. The <code>Pss Total</code> includes all Zygote
allocations (weighted by their sharing across processes, as described in the PSS definition above).
The <code>Private Dirty</code> number is the actual RAM committed to only your app’s heap, composed of
your own allocations and any Zygote allocation pages that have been modified since forking your
app’s process from Zygote.

<p class="note"><strong>Note:</strong> On newer platform versions that have the <code>Dalvik
Other</code> section, the <code>Pss Total</code> and <code>Private Dirty</code> numbers for Dalvik Heap do
not include Dalvik overhead such as the just-in-time compilation (JIT) and GC
bookkeeping, whereas older versions list it all combined under <code>Dalvik</code>.</p>

<p>The <code>Heap Alloc</code> is the amount of memory that the Dalvik and native heap allocators keep
track of for your app. This value is larger than <code>Pss Total</code> and <code>Private Dirty</code>
because your process was forked from Zygote and it includes allocations that your process shares
with all the others.</p>
</dd>

<dt><code>.so mmap</code> and <code>.dex mmap</code></dt>
<dd>The RAM being used for mmapped <code>.so</code> (native) and <code>.dex</code> (Dalvik or ART)
code. The <code>Pss Total</code> number includes platform code shared across apps; the
<code>Private Clean</code> is your app’s own code. Generally, the actual mapped size will be much
larger—the RAM here is only what currently needs to be in RAM for code that has been executed by
the app. However, the .so mmap has a large private dirty, which is due to fix-ups to the native
code when it was loaded into its final address.
</dd>

<dt><code>.oat mmap</code></dt>
<dd>This is the amount of RAM used by the code image which is based off of the preloaded classes
which are commonly used by multiple apps. This image is shared across all apps and is unaffected
by particular apps.
</dd>

<dt><code>.art mmap</code></dt>
<dd>This is the amount of RAM used by the heap image which is based off of the preloaded classes
which are commonly used by multiple apps. This image is shared across all apps and is unaffected
by particular apps. Even though the ART image contains {@link java.lang.Object} instances, it does not
count towards your heap size.
</dd>

<dt><code>.Heap</code> (only with -d flag)</dt>
<dd>This is the amount of heap memory for your app. This excludes objects in the image and large
object spaces, but includes the zygote space and non-moving space.
</dd>

<dt><code>.LOS</code> (only with -d flag)</dt>
<dd>This is the amount of RAM used by the ART large object space. This includes zygote large
objects. Large objects are all primitive array allocations larger than 12KB.
</dd>

<dt><code>.GC</code> (only with -d flag)</dt>
<dd>This is the amount of internal GC accounting overhead for your app. There is not really any way
to reduce this overhead.
</dd>

<dt><code>.JITCache</code> (only with -d flag)</dt>
<dd>This is the amount of memory used by the JIT data and code caches. Typically, this is zero
since all of the apps will be compiled at installed time.
</dd>

<dt><code>.Zygote</code> (only with -d flag)</dt>
<dd>This is the amount of memory used by the zygote space. The zygote space is created during
device startup and is never allocated into.
</dd>

<dt><code>.NonMoving</code> (only with -d flag)</dt>
<dd>This is the amount of RAM used by the ART non-moving space. The non-moving space contains
special non-movable objects such as fields and methods. You can reduce this section by using fewer
fields and methods in your app.
</dd>

<dt><code>.IndirectRef</code> (only with -d flag)</dt>
<dd>This is the amount of RAM used by the ART indirect reference tables. Usually this amount is
small, but if it is too high, it may be possible to reduce it by reducing the number of local and
global JNI references used.
</dd>

<dt><code>Unknown</code></dt>
<dd>Any RAM pages that the system could not classify into one of the other more specific items.
Currently, this contains mostly native allocations, which cannot be identified by the tool when
collecting this data due to Address Space Layout Randomization (ASLR). As with the Dalvik heap, the
<code>Pss Total</code> for Unknown takes into account sharing with Zygote, and <code>Private Dirty</code>
is unknown RAM dedicated to only your app.
</dd>

<dt><code>TOTAL</code></dt>
<dd>The total Proportional Set Size (PSS) RAM used by your process. This is the sum of all PSS fields
above it. It indicates the overall memory weight of your process, which can be directly compared
with other processes and the total available RAM.

<p>The <code>Private Dirty</code> and <code>Private Clean</code> are the total allocations within your
process, which are not shared with other processes. Together (especially <code>Private Dirty</code>),
this is the amount of RAM that will be released back to the system when your process is destroyed.
Dirty RAM is pages that have been modified and so must stay committed to RAM (because there is no
swap); clean RAM is pages that have been mapped from a persistent file (such as code being
executed) and so can be paged out if not used for a while.</p>

</dd>

<dt><code>ViewRootImpl</code></dt>
<dd>The number of root views that are active in your process. Each root view is associated with a
window, so this can help you identify memory leaks involving dialogs or other windows.
</dd>

<dt><code>AppContexts</code> and <code>Activities</code></dt>
<dd>The number of application {@link android.content.Context} and {@link android.app.Activity} objects that
currently live in your process. This can be useful to quickly identify leaked {@link
android.app.Activity} objects that can’t be garbage collected due to static references on them,
which is common. These objects often have a lot of other allocations associated with them and so
are a good way to track large memory leaks.</dd>

<p class="note"><strong>Note:</strong> A {@link android.view.View} or {@link
android.graphics.drawable.Drawable} object also holds a reference to the {@link
android.app.Activity} that it's from, so holding a {@link android.view.View} or {@link
android.graphics.drawable.Drawable} object can also lead to your application leaking an {@link
android.app.Activity}.</p>

</dd>
</dl>









<h2 id="HeapDump">Capturing a Heap Dump</h2>

<p>A heap dump is a snapshot of all the objects in your app's heap, stored in a binary format called
HPROF. Your app's heap dump provides information about the overall state of your app's heap so you
can track down problems you might have identified while viewing heap updates.</p>

<p>To retrieve your heap dump:</p>
<ol>
<li>Open the Device Monitor.
<p>From your <code>&lt;sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p>
</li>
<li>In the DDMS window, select your app's process in the left-side panel.</li>
<li>Click <strong>Dump HPROF file</strong>, shown in figure 3.</li>
<li>In the window that appears, name your HPROF file, select the save location,
then click <strong>Save</strong>.</li>
</ol>

<img src="{@docRoot}images/tools/monitor-hprof@2x.png" width="760" alt="" />
<p class="img-caption"><strong>Figure 3.</strong> The Device Monitor tool,
showing the <strong>[1] Dump HPROF file</strong> button.</p>

<p>If you need to be more precise about when the dump is created, you can also create a heap dump
at the critical point in your application code by calling {@link android.os.Debug#dumpHprofData
dumpHprofData()}.</p>

<p>The heap dump is provided in a format that's similar to, but not identical to one from the Java
HPROF tool. The major difference in an Android heap dump is due to the fact that there are a large
number of allocations in the Zygote process. But because the Zygote allocations are shared across
all application processes, they don’t matter very much to your own heap analysis.</p>

<p>To analyze your heap dump, you can use a standard tool like jhat or the <a href=
"http://www.eclipse.org/mat/downloads.php">Eclipse Memory Analyzer Tool</a> (MAT). However, first
you'll need to convert the HPROF file from Android's format to the J2SE HPROF format. You can do
this using the <code>hprof-conv</code> tool provided in the <code>&lt;sdk&gt;/platform-tools/</code>
directory. Simply run the <code>hprof-conv</code> command with two arguments: the original HPROF
file and the location to write the converted HPROF file. For example:</p>

<pre class="no-pretty-print">
hprof-conv heap-original.hprof heap-converted.hprof
</pre>

<p class="note"><strong>Note:</strong> If you're using the version of DDMS that's integrated into
Eclipse, you do not need to perform the HPROF converstion—it performs the conversion by
default.</p>

<p>You can now load the converted file in MAT or another heap analysis tool that understands
the J2SE HPROF format.</p>

<p>When analyzing your heap, you should look for memory leaks caused by:</p>
<ul>
<li>Long-lived references to an Activity, Context, View, Drawable, and other objects that may hold a
reference to the container Activity or Context.</li>
<li>Non-static inner classes (such as a Runnable, which can hold the Activity instance).</li>
<li>Caches that hold objects longer than necessary.</li>
</ul>


<h3 id="EclipseMat">Using the Eclipse Memory Analyzer Tool</h3>

<p>The <a href=
"http://www.eclipse.org/mat/downloads.php">Eclipse Memory Analyzer Tool</a> (MAT) is just one
tool that you can use to analyze your heap dump. It's also quite powerful so most of its
capabilities are beyond the scope of this document, but here are a few tips to get you started.

<p>Once you open your converted HPROF file in MAT, you'll see a pie chart in the Overview,
showing what your largest objects are. Below this chart, are links to couple of useful features:</p>

<ul>
  <li>The <strong>Histogram view</strong> shows a list of all classes and how many instances
  there are of each.
  <p>You might want to use this view to find extra instances of classes for which you know there
  should be only a certain number. For example, a common source of leaks is additional instance of
  your {@link android.app.Activity} class, for which you should usually have only one instance
  at a time. To find a specific class instance, type the class name into the <em>&lt;Regex></em>
  field at the top of the list.
  <p>When you find a class with too many instances, right-click it and select
  <strong>List objects</strong> &gt; <strong>with incoming references</strong>. In the list that
  appears, you can determine where an instance is retained by right-clicking it and selecting
  <strong>Path To GC Roots</strong> &gt; <strong>exclude weak references</strong>.</p>
  </li>

  <li>The <strong>Dominator tree</strong> shows a list of objects organized by the amount
  of retained heap.
  <p>What you should look for is anything that's retaining a portion of heap that's roughly
  equivalent to the memory size you observed leaking from the <a href="#LogMessages">GC logs</a>,
  <a href="#ViewHeap">heap updates</a>, or <a href="#TrackAllocations">allocation
  tracker</a>.
  <p>When you see something suspicious, right-click on the item and select
  <strong>Path To GC Roots</strong> &gt; <strong>exclude weak references</strong>. This opens a
  new tab that traces the references to that object which is causing the alleged leak.</p>

  <p class="note"><strong>Note:</strong> Most apps will show an instance of
  {@link android.content.res.Resources} near the top with a good chunk of heap, but this is
  usually expected when your application uses lots of resources from your {@code res/} directory.</p>
  </li>
</ul>


<img src="{@docRoot}images/tools/mat-histogram@2x.png" width="760" alt="" />
<p class="img-caption"><strong>Figure 4.</strong> The Eclipse Memory Analyzer Tool (MAT),
showing the Histogram view and a search for "MainActivity".</p>

<p>For more information about MAT, watch the Google I/O 2011 presentation,
<a href="http://www.youtube.com/watch?v=_CruQY55HOk">Memory management for Android apps</a>,
which includes a walkthrough using MAT beginning at about <a href=
"http://www.youtube.com/watch?v=_CruQY55HOk&amp;feature=player_detailpage#t=1270">21:10</a>.
Also refer to the <a href="http://wiki.eclipse.org/index.php/MemoryAnalyzer">Eclipse Memory
Analyzer documentation</a>.</p>

<h4 id="MatCompare">Comparing heap dumps</h4>

<p>You may find it useful to compare your app's heap state at two different points in time in order
to inspect the changes in memory allocation. To compare two heap dumps using MAT:</p>

<ol>
  <li>Create two HPROF files as described above, in <a href="#HeapDump">Capturing a Heap Dump</a>.
  <li>Open the first HPROF file in MAT (<strong>File</strong> > <strong>Open Heap Dump</strong>).
  <li>In the Navigation History view (if not visible, select <strong>Window</strong> >
  <strong>Navigation History</strong>), right-click on <strong>Histogram</strong> and select
  <strong>Add to Compare Basket</strong>.
  <li>Open the second HPROF file and repeat steps 2 and 3.
  <li>Switch to the <em>Compare Basket</em> view and click <strong>Compare the Results</strong>
  (the red "!" icon in the top-right corner of the view).
</ol>






<h2 id="TriggerLeaks">Triggering Memory Leaks</h2>

<p>While using the tools described above, you should aggressively stress your application code and try
forcing memory leaks. One way to provoke memory leaks in your application is to let it
run for a while before inspecting the heap. Leaks will trickle up to the top of the allocations in
the heap. However, the smaller the leak, the longer you need to run the application in order to see it.</p>

<p>You can also trigger a memory leak in one of the following ways:</p>
<ol>
<li>Rotate the device from portrait to landscape and back again multiple times while in different
activity states. Rotating the device can often cause an application to leak an {@link android.app.Activity},
{@link android.content.Context}, or {@link android.view.View} object because the system
recreates the {@link android.app.Activity} and if your application holds a reference
to one of those objects somewhere else, the system can't garbage collect it.</li>
<li>Switch between your application and another application while in different activity states (navigate to
the Home screen, then return to your app).</li>
</ol>

<p class="note"><strong>Tip:</strong> You can also perform the above steps by using the "monkey"
test framework. For more information on running the monkey test framework, read the <a href=
"{@docRoot}tools/help/monkeyrunner_concepts.html">monkeyrunner</a>
documentation.</p>