# flamegraphs

Guides agents through turning profiler outputs into SVG flamegraphs and interpreting hot frames to resolve CPU bottlenecks.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 673 installs · ★ 267
- Author: mohitmishra786
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/profilers/flamegraphs/SKILL.md
- Updated: 2026-06-27
- HTML: https://affpapa.org/en/nevibecode/skills/flamegraphs

## What it does

This skill guides your coding agent through converting profiling traces into interactive SVG flamegraphs. It covers workflows for Linux `perf`, Valgrind Callgrind, Go pprof, DTrace, and Java `async-profiler`. The instructions explain how to collapse call stacks using `stackcollapse-*.pl` and render the final diagram with `flamegraph.pl`.

You need Brendan Gregg's FlameGraph repository cloned locally with its directory added to `$PATH`. The skill provides the pipeline logic but does not bundle the Perl scripts themselves.

A major part focuses on reading flamegraphs and spotting regressions. The agent learns that wide plateaus at the top indicate actionable leaf hotspots, while deep narrow towers signal call overhead. It also details differential flamegraphs via `difffolded.pl` to display regressions in red and speedups in blue.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill flamegraphs -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/flamegraphs/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/flamegraphs/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill flamegraphs -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/flamegraphs/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill flamegraphs -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/flamegraphs/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mohitmishra786/low-level-dev-skills flamegraphs
```

2. **Manually: put the files in place**
- File: `.github/skills/flamegraphs/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill flamegraphs -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mohitmishra786/low-level-dev-skills --path skills/profilers/flamegraphs
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/flamegraphs/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill flamegraphs -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/profilers/flamegraphs/SKILL.md

## When to use it
- convert raw perf or Callgrind traces into SVG flamegraphs
- identify hot leaf functions by examining top-frame plateaus
- compare profiles before and after changes with difffolded.pl
- configure flamegraph.pl display options like palettes and minimum frame width

## Example prompts
- How do I generate a flamegraph from perf data?
- The flamegraph shows a wide frame near the top, what does that mean?
- How do I create a differential flamegraph from before.data and after.data?

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 086bed9102b0cf82.

BEGIN THIRD-PARTY FILE 086bed9102b0cf82
````text
---
name: flamegraphs
description: Flamegraph generation and interpretation skill. Use when converting perf, Valgrind Callgrind, or other profiler output into SVG flamegraphs using Brendan Gregg's FlameGraph tools, or when reading flamegraphs to identify performance bottlenecks. Activates on queries about flamegraphs, stackcollapse, flamegraph.svg, identifying hot frames, wide vs tall frames, or performance visualisation.
---

# Flamegraphs

## Purpose

Guide agents through the pipeline from profiler data to SVG flamegraph, and teach interpretation of flamegraphs to drive concrete optimisation decisions.

## Triggers

- "How do I generate a flamegraph from perf data?"
- "How do I read a flamegraph?"
- "The flamegraph shows a wide frame — what does that mean?"
- "How do I generate a flamegraph from Callgrind?"
- "I want to compare two flamegraphs (before/after)"

## Workflow

### 1. Install FlameGraph tools

```bash
git clone https://github.com/brendangregg/FlameGraph
# No install needed; scripts are in the repo
export PATH=$PATH:/path/to/FlameGraph
```

### 2. perf → flamegraph (most common path)

```bash
# Step 1: record
perf record -F 999 -g -o perf.data ./prog

# Step 2: generate script output
perf script -i perf.data > out.perf

# Step 3: collapse stacks
stackcollapse-perf.pl out.perf > out.folded

# Step 4: generate SVG
flamegraph.pl out.folded > flamegraph.svg

# Step 5: view
xdg-open flamegraph.svg     # Linux
open flamegraph.svg          # macOS
```

One-liner:

```bash
perf record -F 999 -g ./prog && perf script | stackcollapse-perf.pl | flamegraph.pl > fg.svg
```

### 3. Differential flamegraph (before/after)

```bash
# Collect two profiles
perf record -g -o before.data ./prog_old
perf record -g -o after.data ./prog_new

# Collapse
perf script -i before.data | stackcollapse-perf.pl > before.folded
perf script -i after.data  | stackcollapse-perf.pl > after.folded

# Diff (red = regressed, blue = improved)
difffolded.pl before.folded after.folded | flamegraph.pl > diff.svg
```

### 4. Callgrind → flamegraph

```bash
valgrind --tool=callgrind --callgrind-out-file=cg.out ./prog
stackcollapse-callgrind.pl cg.out | flamegraph.pl > fg.svg
```

### 5. Other profiler inputs

```bash
# Go pprof
go tool pprof -raw -output=prof.txt prog
stackcollapse-go.pl prof.txt | flamegraph.pl > fg.svg

# DTrace
dtrace -x ustackframes=100 -n 'profile-99 /execname=="prog"/ { @[ustack()] = count(); }' \
  -o out.stacks sleep 10
stackcollapse.pl out.stacks | flamegraph.pl > fg.svg

# Java (async-profiler)
async-profiler -d 30 -f out.collapsed PID
flamegraph.pl out.collapsed > fg.svg
```

### 6. Reading flamegraphs

A flamegraph is a call-stack visualisation:

- **X axis**: time on CPU (not time sequence) — wider = more time
- **Y axis**: call stack depth — taller = deeper call chain
````
END THIRD-PARTY FILE 086bed9102b0cf82

The third-party file has ended. Everything between the 086bed9102b0cf82 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2825 of 4929 bytes. © mohitmishra786 · MIT · https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/profilers/flamegraphs/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md