plugins/org.eclipse.mat.ui.help/gettingstarted/basictutorial.dita - mat/org.eclipse.mat - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd" >
 <!--
     Copyright (c) 2008, 2017 SAP AG and others.
     All rights reserved. This program and the accompanying materials
     are made available under the terms of the Eclipse Public License v1.0
     which accompanies this distribution, and is available at
     http://www.eclipse.org/legal/epl-v10.html

     Contributors:
         SAP AG - initial API and implementation
         IBM Corporation - minor updates
  -->
 <task id="task_basictutorial" xml:lang="en-us">
 	<title>Basic Tutorial</title>
 	<prolog>
 		<copyright>
 			<copyryear year=""></copyryear>
 			<copyrholder>
 				Copyright (c) 2008, 2017 SAP AG and others.
 			    All rights reserved. This program and the accompanying materials
 			    are made available under the terms of the Eclipse Public License v1.0
 			    which accompanies this distribution, and is available at
 			    http://www.eclipse.org/legal/epl-v10.html
 			</copyrholder>
 		</copyright>
 	</prolog>

 	<taskbody>
 		<context>
 			<p>
 				This tutorial provides a "jumping-off place" to get familiar with
 				Memory Analyzer.
 			</p>

 			<p>
 				If you are using Memory Analyzer installed into Eclipse rather than a stand-alone Memory Analyzer,
 				first open the 'Memory Analysis' perspective using:
 				<menucascade>
  					<uicontrol>Window</uicontrol>
  					<uicontrol>Perspective</uicontrol>
  					<uicontrol>Open Perspective</uicontrol>
  					<uicontrol>Other ...</uicontrol>
  					<uicontrol>Memory Analysis</uicontrol>
 				</menucascade>
 			</p>

 			<p>
 				<b>Step 1 - Getting a Heap Dump</b>
 			</p>

 			<p>
 				The Memory Analyzer works with
 				<xref href="../concepts/heapdump.dita">heap dumps</xref>
 				. Such a heap dump contains information about all Java objects alive
 				at a given point in time. All current Java Virtual Machines can
 				write heap dumps, but the exact steps depend on vendor, version and
 				operation system. Find out more in the section
 				<xref href="../tasks/acquiringheapdump.dita" />
 				.
 			</p>

 			<p>
 				Open
 				<image href="../mimes/me76fc4.png">
 					<alt></alt>
 				</image>
 				<xref format="html"
 					href='javascript:liveAction(%22org.eclipse.mat.ui%22,%22org.eclipse.mat.ui.snapshot.actions.OpenSampleHeapDumpAction%22,%22org.eclipse.mat.ui.help/heapdump/HeapDumpSample.hprof%22)'>
 					a sample heap dump</xref>
 				if you view this page inside the Eclipse help center.
 			</p>

 			<p>
 				For the purpose of this tutorial, we use Java 6 and JConsole on
 				Windows. Start your application with Java 6, then start
 				<codeph>&lt;jre6&gt;/bin/jconsole.exe</codeph>
 				and select the running application (in this case Eclipse):
 			</p>

 			<image href="basictutorial_jconsole_open.png">
 				<alt>JConsole dialog to open a connection to a Virtual Machine.</alt>
 			</image>

 			<p>
 				Then, select the operation
 				<i>dumpHeap</i>
 				from the
 				<i>com.sun.management.HotSpotDiagnostic</i>
 				MBean. The first parameter
 				<i>p0</i>
 				is the full path to the heap dump file. Make sure you give it the
 				file extension .hprof. The second parameter
 				<i>p1</i>
 				should be left at true as we are only interested in live objects.
 			</p>

 			<image href="basictutorial_jconsole_mbean.png">
 				<alt>Select the dumpHeap method of the HotspotDiagnostics mbean.</alt>
 			</image>

 			<p>
 				<b>Step 2 - The Overview</b>
 			</p>

 			<p>
 				Open the heap dump via
 				<menucascade>
 					<uicontrol>File</uicontrol>
 					<uicontrol>
 						<image href="../mimes/i-openhd.png">
 							<alt></alt>
 						</image>
 						Open Heap Dump...
 					</uicontrol>
 				</menucascade>
 				to see the overview page.
 			</p>

 			<image href="basictutorial_overview.png">
 				<alt>Memory Analyzer's overview page for a heap dump</alt>
 			</image>

 			<p>
 				On the right, you'll find the size of the dump and the number of
 				classes, objects and class loaders.
 			</p>
 			<p>
 				If the total size of the dump is much smaller than the size of the file it is possible
 				that the heap dump contained many 'garbage' objects which would be discarded at the next garbage
 				collection. See the <xref href="../reference/inspections/unreachable_objects.dita">unreachable objects</xref>
 				query to examine these 'garbage' objects.
 			</p>
 			<p>
 				Right below, the pie chart gives an impression on the biggest
 				objects in the dump. Move your mouse over a slice to see the details
 				of the objects in the object inspector on the left. Click on any
 				slice to drill down and follow for example the outgoing references.
 			</p>

 			<p>
 				<b>Step 3 - The Histogram</b>
 			</p>

 			<p>
 				Select the
 				<i>histogram</i>
 				from the tool bar to list the number of instances per class, the
 				<xref href="../concepts/shallowretainedheap.dita">shallow size</xref>
 				and the
 				<xref href="../concepts/shallowretainedheap.dita">retained size</xref>
 				.
 			</p>

 			<image href="basictutorial_histogram.png">
 				<alt>Histogram</alt>
 			</image>

 			<p>
 				The Memory Analyzer displays by default the retained size of
 				individual objects. However, the retained size of a set of objects -
 				in this case all instances of a particular class - needs to be
 				calculated.
 			</p>

 			<p>
 				To approximate the retained sizes for all rows, pick
 				<image href="../mimes/i-calcrs.png">
 					<alt>Calculate retained size</alt>
 				</image> icon
 				from the tool bar. Alternatively, select a couple rows and use the
 				context menu.
 			</p>

 			<image href="basictutorial_calc_retained.png">
 				<alt>Select calculate retained sizes from the tool bar</alt>
 			</image>

 			<p>
 				Using the
 				<b>context menu</b>
 				, you can drill-down into the set of objects
 				which the selected row
 				represents. For example, you can list the
 				objects with outgoing or
 				incoming references. Or group the objects
 				by the value of an
 				attribute. Or group the collections by their
 				size. Or or or...
 			</p>

 			<p>
 				One thing that makes the Memory Analyzer so powerful is the fact
 				that one can run any action on any set of objects. Just drill down
 				and slice your objects the way you need them.
 			</p>

 			<image href="basictutorial_context_menu.png">
 				<alt>Drill down via the context menu</alt>
 			</image>

 			<p>
 				Another important feature is the facility to
 				<b>group any histogram by class loader, packages or superclass</b>
 				.
 			</p>

 			<image href="basictutorial_group_by.png">
 				<alt>Group the histogram by class loader or package via the tool bar</alt>
 			</image>

 			<p>
 				Any decent application loads different components by different
 				class loaders. The Memory Analyzer attaches a meaningful label to
 				the class loader - in the case of OSGi bundles it is the bundle id.
 				Therefore it becomes a lot easier to divide the heap dump into
 				smaller parts.
 			</p>

 			<p>
 				More: <xref href="../tasks/analyzingclassloader.dita"/>
 			</p>

 			<image href="basictutorail_by_classloader.png">
 				<alt>Histogram grouped by class loader</alt>
 			</image>

 			<p>
 				Grouping the histogram by packages allows to drill-down along the
 				Java package hierarchy.
 			</p>

 			<image href="basictutorail_by_package.png">
 				<alt>Histogram grouped by packages</alt>
 			</image>

 			<p>
 				Grouping the histogram by superclass provides an easy way to find for example all the subclasses of java.util.AbstractMap, etc...
 			</p>

 			<image href="basictutorial_by_superclass.png">
 				<alt>Histogram grouped by superclass</alt>
 			</image>

 			<p>
 				<b>Step 4 - The Dominator Tree</b>
 			</p>

 			<p>
 				The
 				<xref href="../concepts/dominatortree.dita">dominator tree</xref>
 				displays the biggest objects in the heap dump. The next level of the
 				tree lists those objects that would be garbage collected if all
 				incoming references to the parent node were removed.
 			</p>

 			<p>
 				The dominator tree is a powerful tool to investigate which objects
 				keep which other objects alive. Again, the tree can be grouped by
 				class loader (e.g. components) and packages to ease the analysis.
 			</p>

 			<image href="basictutorial_dominator_tree.png">
 				<alt>Dominator Tree</alt>
 			</image>

 			<p>
 				<b>Step 5 - Path to GC Roots</b>
 			</p>

 			<p>
 				<xref href="../concepts/gcroots.dita">Garbage Collections Roots (GC roots)</xref>
 				are objects that are kept alive by the Virtual Machines itself.
 				These include for example the thread objects of the threads
 				currently running, objects currently on the call stack and classes
 				loaded by the system class loader.
 			</p>

 			<p>
 				The (reverse) reference chain from an object to a GC root - the so
 				called path to GC roots - explains why the object cannot be garbage
 				collected. The path helps solving the classical memory leak in Java:
 				those leaks exist because an object is still referenced even though
 				the program logic will not access the object anymore.
 			</p>

 			<image href="basictutorial_path_menu.png">
 				<alt>Select path to GC roots from the context menu</alt>
 			</image>

 			<p>
 				Initially, the GC root reached by the shortest path is selected.
 			</p>

 			<image href="basictutorial_path.png">
 				<alt>Path to GC roots</alt>
 			</image>

 			<p>
 				<b>Step 6 - The Leak Report</b>
 			</p>

 			<p>
 				The Memory Analyzer can inspect the heap dump for leak suspects,
 				e.g. objects or set of objects which are suspiciously big.
 			</p>

 			<image href="basictutorial_run_leak_suspects.png">
 				<alt>Run the leak report</alt>
 			</image>

 			<p>
 				Learn more in this blog posting:
 				<xref format="html"
 					href="http://memoryanalyzer.blogspot.com/2008/05/automated-heap-dump-analysis-finding.html">Automated Heap Dump Analysis: Finding Memory Leaks with One
 					Click</xref>
 				.
 			</p>
 		</context>
 	</taskbody>
 	<related-links>
 		<link href="../concepts/dominatortree.dita" />
 		<link href="../concepts/gcroots.dita" />
 	</related-links>
 </task>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd" >
	<!--
	Copyright (c) 2008, 2017 SAP AG and others.
	All rights reserved. This program and the accompanying materials
	are made available under the terms of the Eclipse Public License v1.0
	which accompanies this distribution, and is available at
	http://www.eclipse.org/legal/epl-v10.html

	Contributors:
	SAP AG - initial API and implementation
	IBM Corporation - minor updates
	-->
	<task id="task_basictutorial" xml:lang="en-us">
	<title>Basic Tutorial</title>
	<prolog>
	<copyright>
	<copyryear year=""></copyryear>
	<copyrholder>
	Copyright (c) 2008, 2017 SAP AG and others.
	All rights reserved. This program and the accompanying materials
	are made available under the terms of the Eclipse Public License v1.0
	which accompanies this distribution, and is available at
	http://www.eclipse.org/legal/epl-v10.html
	</copyrholder>
	</copyright>
	</prolog>

	<taskbody>
	<context>
	<p>
	This tutorial provides a "jumping-off place" to get familiar with
	Memory Analyzer.
	</p>

	<p>
	If you are using Memory Analyzer installed into Eclipse rather than a stand-alone Memory Analyzer,
	first open the 'Memory Analysis' perspective using:
	<menucascade>
	<uicontrol>Window</uicontrol>
	<uicontrol>Perspective</uicontrol>
	<uicontrol>Open Perspective</uicontrol>
	<uicontrol>Other ...</uicontrol>
	<uicontrol>Memory Analysis</uicontrol>
	</menucascade>
	</p>

	<p>
	<b>Step 1 - Getting a Heap Dump</b>
	</p>

	<p>
	The Memory Analyzer works with
	<xref href="../concepts/heapdump.dita">heap dumps</xref>
	. Such a heap dump contains information about all Java objects alive
	at a given point in time. All current Java Virtual Machines can
	write heap dumps, but the exact steps depend on vendor, version and
	operation system. Find out more in the section
	<xref href="../tasks/acquiringheapdump.dita" />
	.
	</p>

	<p>
	Open
	<image href="../mimes/me76fc4.png">
	<alt></alt>
	</image>
	<xref format="html"
	href='javascript:liveAction(%22org.eclipse.mat.ui%22,%22org.eclipse.mat.ui.snapshot.actions.OpenSampleHeapDumpAction%22,%22org.eclipse.mat.ui.help/heapdump/HeapDumpSample.hprof%22)'>
	a sample heap dump</xref>
	if you view this page inside the Eclipse help center.
	</p>

	<p>
	For the purpose of this tutorial, we use Java 6 and JConsole on
	Windows. Start your application with Java 6, then start
	<codeph><jre6>/bin/jconsole.exe</codeph>
	and select the running application (in this case Eclipse):
	</p>

	<image href="basictutorial_jconsole_open.png">
	<alt>JConsole dialog to open a connection to a Virtual Machine.</alt>
	</image>

	<p>
	Then, select the operation
	<i>dumpHeap</i>
	from the
	<i>com.sun.management.HotSpotDiagnostic</i>
	MBean. The first parameter
	<i>p0</i>
	is the full path to the heap dump file. Make sure you give it the
	file extension .hprof. The second parameter
	<i>p1</i>
	should be left at true as we are only interested in live objects.
	</p>

	<image href="basictutorial_jconsole_mbean.png">
	<alt>Select the dumpHeap method of the HotspotDiagnostics mbean.</alt>
	</image>

	<p>
	<b>Step 2 - The Overview</b>
	</p>

	<p>
	Open the heap dump via
	<menucascade>
	<uicontrol>File</uicontrol>
	<uicontrol>
	<image href="../mimes/i-openhd.png">
	<alt></alt>
	</image>
	Open Heap Dump...
	</uicontrol>
	</menucascade>
	to see the overview page.
	</p>

	<image href="basictutorial_overview.png">
	<alt>Memory Analyzer's overview page for a heap dump</alt>
	</image>

	<p>
	On the right, you'll find the size of the dump and the number of
	classes, objects and class loaders.
	</p>
	<p>
	If the total size of the dump is much smaller than the size of the file it is possible
	that the heap dump contained many 'garbage' objects which would be discarded at the next garbage
	collection. See the <xref href="../reference/inspections/unreachable_objects.dita">unreachable objects</xref>
	query to examine these 'garbage' objects.
	</p>
	<p>
	Right below, the pie chart gives an impression on the biggest
	objects in the dump. Move your mouse over a slice to see the details
	of the objects in the object inspector on the left. Click on any
	slice to drill down and follow for example the outgoing references.
	</p>

	<p>
	<b>Step 3 - The Histogram</b>
	</p>

	<p>
	Select the
	<i>histogram</i>
	from the tool bar to list the number of instances per class, the
	<xref href="../concepts/shallowretainedheap.dita">shallow size</xref>
	and the
	<xref href="../concepts/shallowretainedheap.dita">retained size</xref>
	.
	</p>

	<image href="basictutorial_histogram.png">
	<alt>Histogram</alt>
	</image>

	<p>
	The Memory Analyzer displays by default the retained size of
	individual objects. However, the retained size of a set of objects -
	in this case all instances of a particular class - needs to be
	calculated.
	</p>

	<p>
	To approximate the retained sizes for all rows, pick
	<image href="../mimes/i-calcrs.png">
	<alt>Calculate retained size</alt>
	</image> icon
	from the tool bar. Alternatively, select a couple rows and use the
	context menu.
	</p>

	<image href="basictutorial_calc_retained.png">
	<alt>Select calculate retained sizes from the tool bar</alt>
	</image>

	<p>
	Using the
	<b>context menu</b>
	, you can drill-down into the set of objects
	which the selected row
	represents. For example, you can list the
	objects with outgoing or
	incoming references. Or group the objects
	by the value of an
	attribute. Or group the collections by their
	size. Or or or...
	</p>

	<p>
	One thing that makes the Memory Analyzer so powerful is the fact
	that one can run any action on any set of objects. Just drill down
	and slice your objects the way you need them.
	</p>

	<image href="basictutorial_context_menu.png">
	<alt>Drill down via the context menu</alt>
	</image>

	<p>
	Another important feature is the facility to
	<b>group any histogram by class loader, packages or superclass</b>
	.
	</p>

	<image href="basictutorial_group_by.png">
	<alt>Group the histogram by class loader or package via the tool bar</alt>
	</image>

	<p>
	Any decent application loads different components by different
	class loaders. The Memory Analyzer attaches a meaningful label to
	the class loader - in the case of OSGi bundles it is the bundle id.
	Therefore it becomes a lot easier to divide the heap dump into
	smaller parts.
	</p>

	<p>
	More: <xref href="../tasks/analyzingclassloader.dita"/>
	</p>

	<image href="basictutorail_by_classloader.png">
	<alt>Histogram grouped by class loader</alt>
	</image>

	<p>
	Grouping the histogram by packages allows to drill-down along the
	Java package hierarchy.
	</p>

	<image href="basictutorail_by_package.png">
	<alt>Histogram grouped by packages</alt>
	</image>

	<p>
	Grouping the histogram by superclass provides an easy way to find for example all the subclasses of java.util.AbstractMap, etc...
	</p>

	<image href="basictutorial_by_superclass.png">
	<alt>Histogram grouped by superclass</alt>
	</image>

	<p>
	<b>Step 4 - The Dominator Tree</b>
	</p>

	<p>
	The
	<xref href="../concepts/dominatortree.dita">dominator tree</xref>
	displays the biggest objects in the heap dump. The next level of the
	tree lists those objects that would be garbage collected if all
	incoming references to the parent node were removed.
	</p>

	<p>
	The dominator tree is a powerful tool to investigate which objects
	keep which other objects alive. Again, the tree can be grouped by
	class loader (e.g. components) and packages to ease the analysis.
	</p>

	<image href="basictutorial_dominator_tree.png">
	<alt>Dominator Tree</alt>
	</image>

	<p>
	<b>Step 5 - Path to GC Roots</b>
	</p>

	<p>
	<xref href="../concepts/gcroots.dita">Garbage Collections Roots (GC roots)</xref>
	are objects that are kept alive by the Virtual Machines itself.
	These include for example the thread objects of the threads
	currently running, objects currently on the call stack and classes
	loaded by the system class loader.
	</p>

	<p>
	The (reverse) reference chain from an object to a GC root - the so
	called path to GC roots - explains why the object cannot be garbage
	collected. The path helps solving the classical memory leak in Java:
	those leaks exist because an object is still referenced even though
	the program logic will not access the object anymore.
	</p>

	<image href="basictutorial_path_menu.png">
	<alt>Select path to GC roots from the context menu</alt>
	</image>

	<p>
	Initially, the GC root reached by the shortest path is selected.
	</p>

	<image href="basictutorial_path.png">
	<alt>Path to GC roots</alt>
	</image>

	<p>
	<b>Step 6 - The Leak Report</b>
	</p>

	<p>
	The Memory Analyzer can inspect the heap dump for leak suspects,
	e.g. objects or set of objects which are suspiciously big.
	</p>

	<image href="basictutorial_run_leak_suspects.png">
	<alt>Run the leak report</alt>
	</image>

	<p>
	Learn more in this blog posting:
	<xref format="html"
	href="http://memoryanalyzer.blogspot.com/2008/05/automated-heap-dump-analysis-finding.html">Automated Heap Dump Analysis: Finding Memory Leaks with One
	Click</xref>
	.
	</p>
	</context>
	</taskbody>
	<related-links>
	<link href="../concepts/dominatortree.dita" />
	<link href="../concepts/gcroots.dita" />
	</related-links>
	</task>