[mat-dev] my own HOWTO / tutorial

[Victor <dreamland_skib2@xxxxxxxxxxx>]

Hello, MAT developers!

I am using MAT during some time, maybe several months - our system is 
now on that (un)happy stage which requires constant memory & performance 
 analysis, so I tried many tools, especially YourKit, JProfiler, 
OptimizeIt and of course MAT ;)

At the first look, when I started MAT I did not understand at all what 
to do and how to use it :) I spent several days to find out how to do 
something real with MAT. After that I understood that the tool was 
really great. But every time after non-using of MAT for some time, I 
forgot (again and again) those steps I did to find memory leaks or just 
understand memory usage, so I decided to write a small HOWTO for myself :)

It would be great if we include some kind of tutorial based on it, with 
examples and screen-shots to MAT help system.

Also, to make MAT more "easy-to-use" I would propose to change the 
behavior of "Dominator Tree" link, shown at the "Overview" page by 
default ("List the biggest objects and what they keep alive") - if you 
click it on the large dump, you will see some strange dominator tree 
which shows ~10% of objects, and I had never seen that those objects had 
something to do with real memory problems. And where are other 90% of 
objects? :)
I would propose to open (by default) a dominator tree as shown in my 
HOWTO, see below - grouped by packets, include all classes excepting 
standard java.*.

OK, sorry for the long introduction, here is the HOWTO itself, I have 
already posted it to Markus Kohler's blog:
http://kohlerm.blogspot.com/2009/07/eclipse-memory-analyzer-10-useful.html


===============================================
How to use Eclipse MAT to analyze memory dumps.
===============================================

Initial steps:
- if working with large heap dumps (> 1 Gb), it is recommended to 
increase Xmx value in eclipse.ini (ex. -Xmx2400m)
- open your dump (File -> Open heap dump), wait until parsing is finished
- for a fast preview, make a summary histogram (button "Create a 
histogram from an arbitrary set of object" on the toolbar),
	sort by retaind heap, look at object types which retain most of memory 
(usually, String/char[] and byte[])


1. The first way - using dominator tree grouped by packets/classes

1.1 Press button "Open query browser", in the drop-down menu select 
"Java Basics -> Open in dominator tree",
	type a filter for your classes in "objects" field, ex. 
"com.yourcompany.yourproject.*",
	in the "groupby" field, select "by package", look at the results 
(retained heap), expand your packets and subpackets,
	see how much memory is retained by each packet/subpacket.
	This way you may understand which module(s) of your system consume most 
of memory.

1.2 Select a packet (or a class) you want to investigate (which retains 
much memory),
	in the drop-down menu select "Show retained set",
	look at object types which consume most of memory (in the context of 
the selected package),
	you should sort the results by retained heap.
	So, you see which types of objects are consumed by some of your 
modules/subsystems.

1.3 Click on some object type (usually, you look at char[] and byte[]),
	in the context menu select "List objects -> with incoming references", 
sort the results by retained heap.
	This way, you will see largest objects of the selected type. You may 
see their contents, copy them into clipboard
	or a file ("Copy" in the context menu)
	To see more objects, click on the "Total" line (in the bottom) and 
select "Next" in the context menu.

1.4 Select an object instance from the result, look at its contents, and 
also expand incoming references,
	analyze why this object is referenced and why this value is here (this 
depends on your business logic).
	It makes sense to look at more objects from the result and analyze them.

1.5 Repeat steps for different object types and also different packets 
and/or classes
	(you are interested in objects which retain most of heap).



2. Another way

2.1 On the summary histogram (see Initial Steps above) select a type 
(class) which retains much memory (ususally char[]/String, byte[])

2.2 In the context menu select "Show object by class -> by incoming 
references"

2.3 Expand the resulting tree, look - which class references to it, then 
look which class references to that class, etc.

2.4 At each step you may look at the retained set of any class ("Show 
retained set" in the context menu)
	or at the concrete object instances ("List objects -> with incoming 
references" in the context menu).
===============================================

--
 Vatel (Victor)