cykl / hprof2flamegraph

Flame Graph visualization for Java (HPROF, Honest-profiler)

Java flame graphs

A few years ago, Brendan Gregg created the flame graph visualization. He describes it as a visualization of profiled software, allowing the most frequent code-paths to be identified quickly and accurately. More pragmatically, it is a great way to identify the hot spots of an application and to understand its runtime behavior.

The FlameGraph project provides a flamegraph.pl script to create SVG files from a pivot format called folded stacks, and several scripts to convert the proprietary output of various profilers (perf, DTrace etc.) into folded stacks.

This project aims to provide conversion scripts for several Java profilers. These scripts are not pushed in the official project mostly because they are written in Python and not in Perl.

Supported profilers are:

• HPROF
• Honest-profiler

Installation

The easiest way to install hprof2flamgegraph is to use the Pypi package:

pip install [--user] hprof2flamegraph

It installs a stackcollapse-hprof and stackcollapse-hpl scripts into the bin directory of your environment. Make sure this directory is in your PATH. The original flamegraph.pl script from Brendan is also installed (CDDL licensed).

You can also download the script from github or clone the repository. The script is standalone with Python >= 2.7 and only requires the argparse module with Python 2.6.

Why should I use flame graphs with a Java profiler ?

The Java ecosystem is full of great performance analysis tools and profilers. They are often full featured (CPU, memory, threads, GC, monitors, etc.) and well suited for complex environments or analyses.

However, quite often we only need to get the big picture of our application. Flame graphs really shine in this area. It is the easiest and fastest way to visualize your application and understand its performance profile. It is a complement to more heavy-weight analysis environments.

The official flame graph visualization page describe it in-depth and examine several use cases.

Usage

HPROF

Run the application with HPROF enabled. It must be configured to do CPU sampling and not CPU tracing. You can configure the sampling interval, the maximum stack depth, and whether if line numbers and thread information are printed.

I recommend to always set these last two to y since they can be discarded at a latter step if needed. You never collect too much information.

java -agentlib:hprof=cpu=samples,depth=100,interval=7,lineno=y,thread=y,file=output.hprof[...]

Convert the output.hprof file into folded stacks using the stackcollapse-hprof script

stackcollapse-hprof output.hprof > output-folded.txt

Create the final SVG graph. You can either use the flamegraph.pl script shipped with this module or the one from the official FlameGraph project. They are the same.

flamegraph.pl output-folded.txt > output.svg

A few tips about HPROF follows:

• HPROF is not hot-pluggable. It means that it must be activated when the JVM starts and that the application will be profiled from the begging to the end. However, playing with SIGQUITs allow to profile a specific time frame. Its lame but it works.
• It is also usually a good practice to avoid round sampling intervals like 10ms to avoid a possible bias due to the synchronization of several periodic processes (like a process scheduler or a timer).
• As shown in Evaluating the Accuracy of Java Profilers HPROF is flawed, like many other Java profiler, and can produce non-actionable profiles. It worth reading the paper to make sure you understand the limitation of the tool. After that, HPROF is usually good enough to identify the hot spots.

Honest-profiler

Run the application with honest-profiler enabled (and remember it is not production ready yet).

java -agentpath:/path/to/location/liblagent.so[...]

It will create a log.hpl. Convert it into folded stacks using the stackcollapse-hpl script

stackcollapse-hpl log.hpl > output-folded.txt

Create the final SVG graph

flamegraph.pl output-folded.txt > output.svg

Specific use cases

Hadoop jobs

Want to profile an Hadoop job?

It is quite easy to do. You only have to set the following Hadoop variables:

• mapred.task.profile
• mapred.task.profile.params
• mapred.task.profile.maps
• mapred.task.profile.reduces.

To enable HPROF programmatically from a Java job:

Configuration conf = getConf();
conf.setBoolean("mapred.task.profile", true);
conf.set("mapred.task.profile.params",
         "-agentlib:hprof=cpu=samples,depth=100,interval=7,lineno=y,thread=y,file=%s");
conf.set("mapred.task.profile.maps", "0");
conf.set("mapred.task.profile.reduces", "0");

To do it from the command line:

hadoop jar my.jar \
  -Dmapred.task.profile=true \
  -Dmapred.task.profile.params="-agentlib:hprof=cpu=samples,depth=100,interval=7,lineno=y,thread=y,file=%s" \
  -Dmapred.task.profile.maps=0 \
  -Dmapred.task.profile.reduces=0

hprof2flamegraph's Issues

UnicodeDecodeError

Hi,
I hava a file that generated on android,I convert it to a standard binary hprof by the tool "hprof-conv".stackcollapse-hprof use "utf-8" to read it,so error is showed:

    File "./stackcollapse_hprof.py", line 207, in <module>
      main()
    File "./stackcollapse_hprof.py", line 184, in main
      content  = get_file_content(filename)
    File "./stackcollapse_hprof.py", line 60, in get_file_content
      return f.read()
    File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/codecs.py", line 302, in decode
      (result, consumed) = self._buffer_decode(data, self.errors, final)
      UnicodeDecodeError: 'utf8' codec can't decode byte 0x99 in position 29: invalid start byte

Do you have a solution for android hprof?

does not work with the lastest honest profiler(last commit at 2017-10-06)

honest profiler just introduced a new marker:
const byte NEW_METHOD_SIGNATURE = 31;

this of course breaks the conversion from hpl. Hopefully you can take a look and fix this.

stackcollapse-hpl fails with "Exception: Unexpected marker: 21 at offset 14"

I get the following error when trying to parse a hpl file generated by honest-profiler (version d505d540ad09516ede804e7d1aa34a889f266780):

stackcollapse-hpl slow2 > output-folded.txt
Traceback (most recent call last):
  File "/usr/local/bin/stackcollapse-hpl", line 9, in <module>
    load_entry_point('hprof2flamegraph==0.0.2', 'console_scripts', 'stackcollapse-hpl')()
  File "/usr/local/lib/python3.4/dist-packages/stackcollapse_hpl.py", line 110, in main
    (traces, methods) = parse_hpl(filename)
  File "/usr/local/lib/python3.4/dist-packages/stackcollapse_hpl.py", line 72, in parse_hpl
    raise Exception("Unexpected marker: %s at offset %s" % (marker, fh.tell()))
Exception: Unexpected marker: 21 at offset 14

Support for Py3.x

Does supporting Python >= 2.7 mean that I can run this tool for Py3.6?
This is purely py2 --> py3 encoding problem.

$ stackcollapse-hprof mymem.hprof > output-folded.txt

Traceback (most recent call last):
  File "/Library/Frameworks/Python.framework/Versions/3.6/bin/stackcollapse-hprof", line 11, in <module>
    sys.exit(main())
  File "/Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/stackcollapse_hprof.py", line 183, in main
    content  = get_file_content(filename)
  File "/Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/stackcollapse_hprof.py", line 58, in get_file_content
    lines = f.readlines()
  File "/Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/encodings/ascii.py", line 26, in decode
    return codecs.ascii_decode(input, self.errors)[0]
UnicodeDecodeError: 'ascii' codec can't decode byte 0xd6 in position 87: ordinal not in range(128)