blob: 1eef6ab76c91f1e2993df35fb7d74457ceaff07f [file] [log] [blame]
page.title=HPROF Viewer and Analyzer
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the Memory Monitor to dump the Java heap to an HPROF file. The HPROF Viewer displays classes, instances of each class, and a reference tree to help you track memory usage and find memory leaks.
page.image=tools/help/thumbnails/am_hprofviewer.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#why">Why Look at the Java Heap?</a></li>
<li><a href="#display">Understanding the HPROF Viewer Display</a></li>
<li><a href="#hprof-snapshot">Taking a Snapshot of the Java Heap</a></li>
<li><a href="#hprof-viewing">Viewing a Saved HPROF File</a></li>
<li><a href="#hprof-diving">Diving into Heap Dump Data in the HPROF Viewer</a></li>
<li><a href="#hprof-analyzing">Analyzing Heap Dump Data in the HPROF Analyzer</a></li>
<li><a href="#hprof-sorting">Sorting Heap Dump Data</a></li>
<li><a href="#hprof-source">Displaying Java Source</a></li>
<li><a href="#hprof-files">Working with HPROF Files</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}training/articles/memory.html">Managing Your App's Memory</a></li>
<li><a href="{@docRoot}guide/practices/verifying-apps-art.html#GC_Migration">Addressing Garbage Collection Issues</a></li>
<li><a href="{@docRoot}tools/debugging/debugging-memory.html">Investigating Your RAM Usage</a></li>
</ol>
</div>
</div>
<p>
When you're monitoring memory usage in the Memory Monitor you can, at the same time, dump a
snapshot of the Java heap to an Android-specific Heap/CPU Profiling (HPROF) file. The HPROF Viewer
displays classes, instances of each class, and a reference tree to help you track memory usage
and find memory leaks. HPROF is a binary heap dump format originally supported by J2SE.
</p>
<h2 id="why">
Why Look at the Java Heap?
</h2>
<p>The Java heap display does the following:</p>
<ul>
<li>Shows snapshots of a number of objects allocated by type.
</li>
<li>Samples data every time a garbage collection event occurs naturally or is triggered by you.
</li>
<li>Helps identify which object types might be involved in memory leaks.
</li>
</ul>
<p>
However, you have to look for changes over time yourself by tracking what's happening in the
graph.
</p>
<p>
The HPROF Analyzer finds the following potential issues:
</p>
<ul>
<li>All destroyed activity instances that are reachable from garbage collection roots.
</li>
<li>Where the target program has strings that repeat values.
</li>
</ul>
<p>
A dominator is at the top of a tree. If you remove it, you also remove the branches of the tree
it dominates, so it’s a potential way to free memory.
</p>
<h2 id="display">
Understanding the HPROF Viewer Display
</h2>
<p>
The HPROF Viewer looks similar to the following figure:
</p>
<img src="{@docRoot}images/tools/am-hprofviewer.png" />
<p>
The tool displays the following information:
</p>
<table>
<tr>
<th scope="col">Column</th>
<th scope="col">Description</th>
</tr>
<tr>
<td><strong>Class Name</strong></td>
<td>The Java class responsible for the memory.</td>
</tr>
<tr>
<td><strong>Total Count</strong></td>
<td>Total number of instances outstanding.</td>
</tr>
<tr>
<td><strong>Heap Count</strong></td>
<td>Number of instances in the selected heap.</td>
</tr>
<tr>
<td><strong>Sizeof</strong></td>
<td>Size of the instances (currently, 0 if the size is variable).</td>
</tr>
<tr>
<td><strong>Shallow Size</strong></td>
<td>Total size of all instances in this heap.</td>
</tr>
<tr>
<td><strong>Retained Size</strong></td>
<td>Size of memory that all instances of this class is dominating.</td>
</tr>
<tr>
<td><strong>Instance</strong></td>
<td>A specific instance of the class.</td>
</tr>
<tr>
<td><strong>Reference Tree</strong></td>
<td>References that point to the selected instance, as well as references pointing to the
references.</td>
</tr>
<tr>
<td><strong>Depth</strong></td>
<td>The shortest number of hops from any GC root to the selected instance.</td>
</tr>
<tr>
<td><strong>Shallow Size</strong></td>
<td>Size of this instance.</td>
</tr>
<tr>
<td><strong>Dominating Size</strong></td>
<td>Size of memory that this instance is dominating.</td>
</tr>
</table>
<p>If you click <strong>Capture Analysis</strong>, the HPROF Analyzer appears: </p>
<img src="{@docRoot}images/tools/am-hprofanalyzer.png" />
<p>You can detect leaked activities and find duplicate strings with the HPROF Analyzer.</p>
<h2 id="hprof-snapshot">
Taking and Displaying a Snapshot of the Java Heap
</h2>
<p>
To examine a snapshot of the Java heap:
</p>
<ol>
<li><a href="{@docRoot}tools/help/am-memory.html#displaying">Display a running app in the Memory
Monitor</a>.</li>
<li>Click Dump Java Heap
<img src="{@docRoot}images/tools/am-idump.png"
style="vertical-align:sub;margin:0;height:17px" alt="Dump Java Heap icon" />.
</li>
<p>
When the icon on the Memory Monitor display changes from
<img src="{@docRoot}images/tools/am-idumpstart.png"
style="vertical-align:sub;margin:0;height:17px" alt="Dump Java Heap Start icon" /> to
<img src="{@docRoot}images/tools/am-idumpend.png" style="vertical-align:sub;margin:0;height:17px"
alt="Dump Java Heap End icon" />, the file is ready. Android Studio creates the heap snapshot
file with the
filename <code><em>package_yyyy.mm.dd_hh.mm.ss</em>.hprof</code> using
the activity package (or project) name, year, month, day, hour, minute, and second of the
capture, for example,
<code>com.android.calc_2015.11.17_14.58.48.hprof</code>.
</p>
<p>
The HPROF Viewer appears.
</p>
</ol>
<h2 id="hprof-viewing">Viewing a Saved HPROF File</h2>
<p>After you do a heap dump, Android Studio automatically stores it so you can view it again.
</p>
<p>To view an HPROF file in the HPROF Viewer:</p>
<ol>
<li>Click
<img src="{@docRoot}images/tools/am-icaptures.png"
style="vertical-align:sub;margin:0;height:17px"
alt="Captures icon" /> in the main window.</li>
<p>Or select <strong>View</strong> > <strong>Tools Windows</strong> >
<strong>Captures</strong>.</p>
<p>The <em>Captures</em> window appears.</p>
<li>Open the <strong>Heap Snapshot</strong> folder.</li>
<li>Double-click the file to view it in the HPROF Viewer.
</li>
<p>
The HPROF Viewer appears.
</p>
<li>Select the Heap menu option you want to display:
<ul>
<li>
<strong>App heap</strong> - The heap used by the current app.
</li>
<li><strong>Image heap</strong> - The memory mapped copy of the
current app on disk.
</li>
<li>
<strong>Zygote heap</strong> - The common set of libraries and runtime classes and data that
all apps are forked
from. The zygote space is created during device startup and is never allocated into.
</li>
</ul>
<li>Select the View menu option you want to display:
<ul>
<li>
<strong>Class List View</strong>
</li>
<li>
<strong>Package Tree View</strong>
</li>
</ul>
</ol>
<h2 id="hprof-diving">
Diving into Heap Dump Data in the HPROF Viewer
</h2>
<p>The following steps outline the typical workflow:</p>
<ol>
<li>In the HPROF Viewer, select a class name. </li>
<li>Select an instance of that class.</li>
<li>Examine the reference tree.</li>
<li>Right-click an item to <strong>Jump to source</strong> or <strong>Go to instance</strong>,
as needed.</li>
</ol>
<h2 id="hprof-analyzing">Analyzing Heap Dump Data in the HPROF Analyzer</h2>
<p>You can detect leaked activities and find duplicate strings with the HPROF Analyzer.
</p>
<p>To use the HPROF Analyzer:</p>
<ol>
<li>In the <em>Captures</em> window, double-click an <code>.hprof</code> file to display it in the
HPROF Viewer. </li>
<li>Click <strong>Capture Analysis</strong> on the right side of the main Android Studio window.</li>
<p>The HPROF Analyzer appears to the right of the HPROF Analyzer, by default.</p>
<li>In the <strong>Analyzer Tasks</strong> list, select the items you want to find.</li>
<li>Click Perform Analysis <img src="{@docRoot}images/tools/am-iperformanalysis.png"
style="vertical-align:sub;margin:0;height:17px" alt="Perform Analysis icon" />.</li>
<li>Examine the items in <strong>Analysis Results</strong>. Click an item to display it in the
HPROF Viewer.</li>
</ol>
<h2 id="hprof-sorting">Sorting Heap Dump Data</h2>
<p>To sort heap dump data:</p>
<ul>
<li>In the HPROF Viewer, click a column heading to sort the table by ascending or descending
order. </li>
</ul>
<h2 id="hprof-source">Displaying Java Source</h2>
<p>For some items displayed in the HPROF Viewer, you can go straight to its
source code.
</p>
<p>To display Java source:</p>
<ul>
<li>In the HPROF Viewer, right-click a class, instance, or item in the reference tree, and then
select <strong>Jump to Source</strong>. </li>
<p>The source code appears in the Code Editor.</p>
</ul>
<h2 id="hprof-files">Working with HPROF Files</h2>
<p>You can rename, locate, and delete an HPROF file from within Android Studio.
You can also convert it to standard HPROF format to use with other analysis
tools.</p>
<h3 id="hprof-renaming">Renaming an HPROF file</h3>
<p>If you rename a file from within Android Studio, it continues to appear in
the <em>Captures</em> window.</p>
<p>To rename an HPROF file:</p>
<ol>
<li>In the <em>Captures</em> window, right-click the file and select <strong>Rename</strong>. </li>
<li>In the dialog, specify the name of the file and click <strong>OK</strong>.</li>
</ol>
<h3 id="hprof-locating">Locating a heap dump file on disk</h3>
<p>You can quickly discover where Android Studio stored HPROF files on disk.</p>
<p>To locate an HPROF file on disk: </p>
<ul>
<li>In the <em>Captures</em> window, right-click a heap snapshot file and select
<strong>Show</strong> or <strong>Reveal</strong>.</li>
<p>Android Studio opens an operating system file browser displaying the location where the file
resides.</p>
</ul>
<p class="note"><strong>Note:</strong> If you move an HPROF file, Android Studio no longer
displays it in the <em>Captures</em> window. To display it, use
<strong>File</strong> &gt; <strong>Open</strong>. Also, if you want to rename the file, do it
from the <em>Captures</em> window and not in the operating system file browser. </p>
<h3 id="hprof-deleting">Deleting a heap dump file</h3>
<p>To delete a heap dump file: </p>
<ul>
<li>In the <em>Captures</em> window, right-click a heap snapshot file and select
<strong>Delete</strong>.</li>
<p>Android Studio deletes the file from the <em>Captures</em> dialog and from disk. </p>
</ul>
<h3 id="hprof-converting">Converting a heap dump file to standard HPROF format</h3>
<p>You can convert an HPROF file to standard format so you can use it outside of Android Studio with
other analysis tools. </p>
<p>To convert an HPROF file:</p>
<ol>
<li>In the <em>Captures</em> window, right-click a heap snapshot file and select <strong>Export to
standard .hprof</strong>.</li>
<li>In the <em>Convert Android Java Heap Dump</em> dialog, specify a filename and click
<strong>OK</strong>.</li>
<p>Android Studio creates a binary HPROF file in the location you specified.</p>
</ol>