# FlameGraph — Stack Trace Visualization for Performance Analysis

> Generate interactive SVG flame graphs from profiling data to pinpoint CPU, memory, and off-CPU bottlenecks across any language or OS.

## Install

Save as a script file and run:

# FlameGraph — Stack Trace Visualization for Performance Analysis

## Quick Use
```bash
git clone https://github.com/brendangregg/FlameGraph.git
cd FlameGraph
# Capture a 30-second CPU profile on Linux using perf
perf record -F 99 -ag -- sleep 30
perf script | ./stackcollapse-perf.pl | ./flamegraph.pl > cpu.svg
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-343f06dc
Author: Script Depot