Understanding Flame Graphs for Performance Analysis in Java Applications

Introduction

The evolution of tools drives productivity; using the right tool can dramatically improve efficiency. While shell commands excel at aggregating simple numeric data, they struggle with multi‑dimensional analysis such as correlation between two values, prompting the need for visual tools like flame graphs.

Overview

Background

When diagnosing performance issues, we often dump thread stacks and filter them with commands such as:

grep --no-group-separator -A 1 java.lang.Thread.State jstack.log | awk 'NR%2==0' | sort | uniq -c | sort -nr

This approach treats the frequency of a stack trace as a proxy for the time spent in that call, similar to counting how often an advertisement appears on a screen to estimate its airtime.

However, pure text output cannot easily convey both the call chain and its frequency, which is why Brendan Gregg introduced flame graphs.

Flame Graph

A flame graph is an interactive SVG where each rectangle represents a function call; its width reflects the cumulative time (or frequency) of that call across all samples. Clicking a rectangle expands its children, and hovering shows detailed information.

When you click a block, the view expands upward from that block; hovering reveals the call name, sample count, and its percentage of the total width.

Features

From bottom to top you can trace a unique call chain; each block’s parent is directly below it.

Blocks with the same parent are ordered alphabetically from left to right.

The text on a block shows the function name, the number of samples, and the block’s width as a percentage of the total.

Colors have no semantic meaning; they are only for visual distinction.

Analysis

When interpreting a flame graph, the primary focus is the width of the blocks because width indicates how often a call appears, which correlates with time consumption. However, wide blocks in the middle of the graph may not be problematic if their children are evenly distributed. The most critical areas are the flat “plateaus” at the top—blocks with no children that occupy a large width, indicating a function that either hangs or is called extremely frequently.

Implementation

Generation Tool

Brendan Gregg provides a Perl script flamegraph.pl that converts collapsed stack data into an interactive SVG. The script accepts various parameters to customize colors, dimensions, and other visual aspects.

Data Preparation

Flamegraph.pl expects input in a collapsed stack format where each line contains a semicolon‑separated call chain followed by a sample count, e.g.:

a;b;c 12
a;d 3
b;c 3
z;d 5
a;c;e 3

Tools such as stackcollapse-perf.pl , stackcollapse-jstack.pl , and stackcollapse-gdb.pl can transform raw perf, jstack, or gdb output into this format. A simple shell pipeline to process a jstack dump might look like:

grep -v -P '.+prio=\d+ os_prio=\d+' | grep -v -E 'locked <' | awk '{if ($0=="") {print $0} else {printf "%s;",$0}}' | sort | uniq -c | awk '{a=$1;$1="";print $0,a}'

Conclusion

Flame graphs provide a powerful visual method for pinpointing performance hotspots in Java applications, complementing traditional text‑based profiling techniques and enabling faster, more intuitive troubleshooting.