FlameGraph — Stack Trace Visualization for Performance Analysis

Introduction

FlameGraph is a collection of scripts created by Brendan Gregg that turn stack-trace samples into interactive SVG visualizations. It helps developers and SREs quickly identify hot code paths without wading through walls of text profiler output.

What FlameGraph Does

• Converts folded stack traces into color-coded SVG flame charts
• Supports input from perf, DTrace, SystemTap, bpftrace, and dozens of other profilers
• Generates differential flame graphs to compare two profiles side by side
• Handles CPU, off-CPU, memory, and I/O stack traces
• Produces self-contained SVGs with built-in search and zoom via JavaScript

Architecture Overview

FlameGraph is a set of Perl scripts that operate in a two-stage pipeline. First, a language-specific 'stackcollapse' script normalizes raw profiler output into a semicolon-delimited folded format with sample counts. Then flamegraph.pl reads that folded data, calculates frame widths proportional to sample counts, and emits an SVG with embedded JavaScript for interactive exploration.

Self-Hosting & Configuration

• Clone the repository; no build step or dependencies beyond Perl 5
• Feed any profiler output through the matching stackcollapse-*.pl script
• Adjust colors with --color (hot, mem, io, green, blue, aqua, orange)
• Set --title and --subtitle to label the output SVG
• Use --minwidth to hide frames below a pixel threshold for cleaner visuals

Key Features

• Language-agnostic: works with C, C++, Java, Go, Python, Node.js, Ruby, .NET, and more
• Differential flame graphs highlight regressions between two runs
• Icicle graphs (inverted) available via --inverted flag
• No runtime overhead: operates on already-captured trace data
• Widely adopted as the de facto flame graph standard across the industry

Comparison with Similar Tools

• Speedscope — browser-based viewer with timeline support; FlameGraph produces standalone SVGs without a server
• pprof (Go) — built-in Go profiler with its own flame view; FlameGraph supports any language
• Grafana Pyroscope — continuous profiling platform; FlameGraph is a lightweight offline tool
• async-profiler — Java-specific sampler that can emit FlameGraph-compatible folded stacks
• Firefox Profiler — browser-oriented; FlameGraph targets system and backend workloads

FAQ

Q: Do I need root access to generate flame graphs? A: Root is typically needed to capture kernel stacks with perf, but user-space profilers like py-spy or async-profiler can run without root.

Q: Can I use FlameGraph on macOS? A: Yes. Use DTrace or Instruments to capture stacks, then pipe through the appropriate stackcollapse script.

Q: How do I read a flame graph? A: The x-axis is sorted alphabetically (not by time). Width represents the proportion of samples. Look for wide frames — those are the hot spots.

Q: What are differential flame graphs? A: They compare two profiles and color frames red (regression) or blue (improvement), making it easy to spot performance changes between releases.

Sources

• https://github.com/brendangregg/FlameGraph
• https://www.brendangregg.com/flamegraphs.html