Auto-MAT - Analyse Java Heap Dumps From Commandline
Tags: java, commandline, docker
Published: 2019-09-28 19:03:34

A while ago, I had to analyse a large java heap dump, generated by one of our servers after a memory leak. This was hard. 
I usually use [Eclipse MAT](https://www.eclipse.org/mat/) for the job, but this time, it was so large the tool could not parse the heap dump in an acceptable time, and required more and more memory.

I eventually took a strong machine with GUI in the cloud and got it to work, but the experience was bad. I had to use GUI for that, because all the tools I knew back then required GUI to operate.

Running a server with GUI in the cloud is not something I do every day, and it took some time to configure the server, start it, connect with remote desktop etc'.

I figured there must be a better option. So I looked around, and discovered that you can let Eclipse MAT parse the heap dump from commandline!

You can use a script that comes with the Linux installation of Eclipse MAT. The script will calculate indexes for later use in eclipse MAT and can also generate some nice HTML reports that are usually good enough to understand the problem.
The index files will help Eclipse MAT open in seconds, instead of long hours.

This is much better than the experience I had, I could run the script on a remote server from terminal, which is easy to set up, and I usually have a couple of servers ready to do some work for me.

I've tried the script and it worked great. But, it comes only with the linux installation. What if I wanted to run it on Mac or Windows? Also, Eclipse MAT requires Java to be installed.

So, I decided to wrap it in a docker container, and that is how [Auto-MAT](https://github.com/jfrog/auto-mat) got created.
Now every time I need to analyse a heap dump I could just run something like:

```docker run -it --mount src=$(pwd),target=/data,type=bind docker.bintray.io/jfrog/auto-mat heap1.hprof 11g suspects,overview```

This will parse the heap dump, create indexes and will generate nice 2 HTML reports. Suspects and Overview.

After running this, it will usually be enough to open the HTML reports to understand the problem. But if you need a deeper drill down into the memory, you could open the heap dump with MAT and, since the indexes are already there, Eclipse MAT will open in a snap. 

![Sample Report](https://thepracticaldev.s3.amazonaws.com/i/str2vc20iklwyht48vsr.png)
![Sample Repoet](https://thepracticaldev.s3.amazonaws.com/i/8dl0c47hg2ag7fvis69m.png)

Well, that was great, but if I needed a strong machine to run [Auto-MAT](https://github.com/jfrog/auto-mat), I would still have to find a machine, upload the heap dump, install docker if it is not installed, and then download everything back or store it somewhere.

So, I decided to build an automation around it. First, I've asked my colleague to build a Jenkins job that will take a heap dump from a production server, and will upload it to Artifactory.

Later I built a second Jenkins job that will download the heap dump from Artifactory and run Auto-MAT on it. The artifacts of Auto-MAT run will be uploaded back to artifactory.

The second Jenkins job can be triggered by the first, or manually after someone has uploaded the heap dump to Artifactory.

In this way, anyone in the organisation can analyse heap dumps with a click of a button. 

If you are planning to work with heap dumps in automation, I recommend to compress them, I use pigz which is a faster version of gzip. I used Artifactory to store the files for my automation, you can use anything else, but if you are using Artifactory check out [jfrog-cli](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory), and especially the parallel download and upload features.
 
[Auto-MAT](https://github.com/jfrog/auto-mat) is open source and you can visit the github page for more: https://github.com/jfrog/auto-mat