# flamegraph-toolkit

**Repository Path**: chenxuqiang2022/flamegraph-toolkit

## Basic Information

- **Project Name**: flamegraph-toolkit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flame Graph Toolkit

Bash 火焰图生成工具集，支持 CPU / Off-CPU / 内存分配 / 锁竞争 / 缓存缺失 / 通用栈追踪 / 差异对比七种分析模式，生成交互式 SVG 火焰图和 AI 可读的文本报告。

## 快速开始

```bash
# 1. 初始化：下载 FlameGraph 脚本并检查依赖
./flamegraph.sh --setup

# 2. 采集并生成火焰图
./flamegraph.sh -t cpu -c './myapp' -d 60
```

每次运行会在 `output/` 目录下生成三个文件：

| 文件 | 用途 |
|------|------|
| `*.svg` | 交互式火焰图，浏览器打开可点击下钻、搜索 |
| `*.folded` | Folded stacks 原始文本，可直接提供给文本 AI 分析 |
| `*.report.txt` | 摘要报告（热点函数 Top 20、调用路径 Top 10 及占比） |

使用 `--annotate` 时还会生成 `*.annotate.txt`（源码级热点标注）。

## 使用方式

```
./flamegraph.sh -t <type> [options]
```

### 分析类型

| 类型 | 说明 | 采集工具（优先→降级） |
|------|------|----------------------|
| `cpu` | CPU 热点分析 | `perf record -e cycles` → `perf record -e cpu-clock` |
| `offcpu` | Off-CPU 阻塞/等待分析 | bpftrace kprobe → `perf record -e sched:sched_switch` |
| `mem` | 内存分配分析 | bpftrace uprobe malloc → `perf mem record` → `perf record -e sys_enter_mmap,sys_enter_brk` |
| `lock` | 锁竞争分析 | bpftrace mutex kprobe → `perf record -e lock:contention_begin` → `perf record -e sys_enter_futex,sys_exit_futex` |
| `cache` | 缓存/分支预测缺失分析 | `perf record -e cache-misses,branch-misses` → `perf record -e cpu-clock`（降级） |
| `generic` | 导入已有的 folded stack 文件 | 无（需要 `-f` 指定输入） |
| `diff` | 差异火焰图（对比两次 profile） | 无（需要 `--baseline` + `--current`） |

### 参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-t TYPE` | 分析类型：cpu / offcpu / mem / lock / cache / generic / diff | 必填 |
| `-p PID` | 附加到运行中的进程 | - |
| `-c COMMAND` | 运行命令并分析 | - |
| `-C CPUS` | 指定 CPU 核（如 `0`、`0-3`、`0,2,4`） | - |
| `-d SECONDS` | 采集时长（秒） | 30 |
| `-F HZ` | 采样频率（Hz） | 99 |
| `-o DIR` | 输出目录 | `./output` |
| `-f FILE` | 输入 folded stack 文件（仅 generic 模式） | - |
| `--baseline FILE` | 对比基准 folded 文件（仅 diff 模式） | - |
| `--current FILE` | 对比当前 folded 文件（仅 diff 模式） | - |
| `--cache-type TYPE` | 缓存事件类型（仅 cache 模式）：cache-misses / branch-misses / L1-dcache-load-misses / dTLB-load-misses / all | all |
| `--icicle` | 生成冰柱图（自顶向下视角） | - |
| `--annotate` | 生成源码级热点标注（仅 cpu / cache 模式） | - |
| `--screenshot` | 将 SVG 转为 PNG（需 Playwright） | - |
| `--setup` | 下载 FlameGraph 并检查依赖 | - |
| `-h` / `--help` | 显示帮助 | - |

`-p`、`-c`、`-C` 可自由组合（`-p` 和 `-c` 互斥）。

### 示例

```bash
# CPU 分析：对指定命令采样 60 秒
./flamegraph.sh -t cpu -c './myapp' -d 60

# CPU 分析：生成冰柱图（自顶向下视角）
./flamegraph.sh -t cpu -c './myapp' -d 30 --icicle

# CPU 分析：带源码级热点标注
./flamegraph.sh -t cpu -c './myapp' -d 30 --annotate

# CPU 分析：附加到进程 1234，仅采样 0 和 2-4 号核
./flamegraph.sh -t cpu -p 1234 -C 0,2-4 -d 30

# Off-CPU 分析：查找进程 1234 的阻塞原因
./flamegraph.sh -t offcpu -p 1234 -d 60

# 内存分析：追踪 myapp 的内存分配热点
./flamegraph.sh -t mem -c './myapp' -d 30

# 锁竞争分析：追踪多线程程序的锁等待
./flamegraph.sh -t lock -c './myapp' -d 30

# 缓存缺失分析：分析 cache-miss 热点
./flamegraph.sh -t cache -c './myapp' -d 30

# 缓存缺失分析：仅分析 branch-miss
./flamegraph.sh -t cache -c './myapp' -d 30 --cache-type branch-misses

# 差异火焰图：对比优化前后的性能变化
./flamegraph.sh -t diff --baseline baseline.folded --current current.folded

# 通用模式：导入已有的 folded stack 文件
./flamegraph.sh -t generic -f stacks.folded

# 指定 CPU 核进行系统级分析（无需 -p 或 -c）
./flamegraph.sh -t cpu -C 0,1 -d 30

# 生成火焰图并截图为 PNG
./flamegraph.sh -t cpu -c './myapp' -d 30 --screenshot
```

## 输出示例

### report.txt

```
=== Flame Graph Report ===
Type: CPU | Duration: 30s | CPU Cores: 0,2-4
Total Samples: 2970

Top 20 Hot Functions (% total):
  18.3%  handle_request
  12.1%  parse_json
   8.7%  db_query
   ...

Top 10 Call Paths:
  main -> server_loop -> handle_request -> parse_json  [15.2%]
  main -> server_loop -> handle_request -> db_query    [8.7%]
  ...
```

### annotate.txt（--annotate 模式）

```
=== Source Annotation Report ===
Generated: Sat Apr 19 11:19:14 PM CST 2026
Perf data: output/20260419_231902_cpu_raw.perf

--- Function: cpu_quick_sort ---
 Percent |  Source code & Disassembly of test_workload for cpu-clock
-----------------------------------------------------------------------------------------------------------
    0.00 :   160b:   endbr64
   50.00 :   1610:   mov    %rsp,%rbp
    0.00 :   1613:   sub    $0x20,%rsp
...
```

### diff.report.txt（diff 模式）

```
=== Differential Flame Graph Report ===
Type: Diff | Baseline: baseline.folded | Current: current.folded

Baseline samples: 2970
Current samples:  3150
Total change: 6.1%

Top 15 Regressions (functions with biggest increase):
    +120  handle_request  (baseline: 540, current: 660)
     +45  parse_json      (baseline: 360, current: 405)

Top 15 Improvements (functions with biggest decrease):
     -30  db_query        (baseline: 260, current: 230)
...
```

### AI 集成

#### 方式一：Claude Code Skill（推荐）

通过 install.sh 将 flamegraph-analyzer skill 安装到目标项目，即可在 Claude Code 中用自然语言完成端到端的性能分析：

```bash
# 安装 skill 到目标项目（--setup 同时下载 FlameGraph 渲染脚本）
./install.sh --setup /path/to/my-project

# 在目标项目中启动 Claude Code，然后输入：
/flamegraph-analyzer 1234               # 分析运行中的进程
/flamegraph-analyzer ./my_app           # 运行并分析
/flamegraph-analyzer output/report.txt  # 分析已有报告
/flamegraph-analyzer                    # 自动搜索当前目录的报告文件
```

安装后会在目标项目的 `.claude/commands/flamegraph-analyzer/` 下生成完整的工作环境（SKILL.md + flamegraph.sh + lib/ + FlameGraph/）。

Skill 工作流程：
1. **采集配置** — 交互式选择分析类型（CPU/Off-CPU/内存/锁/缓存）、采集时长等参数
2. **数据驱动分析** — 解析报告数据，定位热点函数和瓶颈
3. **源码增强分析** — 自动搜索并关联源码，给出代码级优化建议（无源码时自动降级）
4. **优化方案汇总** — 按优先级输出优化建议表，支持追问深入分析

#### 方式二：手动集成

文本大模型可直接读取 `*.folded` 和 `*.report.txt` 进行分析：

```bash
# 将报告提供给 AI 分析
cat output/*.report.txt | your-ai-cli "分析这个火焰图报告中的性能瓶颈"

# 将 folded stacks 提供给 AI 深度分析
cat output/*.folded | your-ai-cli "找出调用路径最深的热点函数"

# 将源码标注提供给 AI 分析
cat output/*.annotate.txt | your-ai-cli "哪些函数的缓存命中率最低？如何优化？"
```

多模态模型可使用 `--screenshot` 生成 PNG 截图进行视觉分析。

## 项目结构

```
flamegraph-toolkit/
├── flamegraph.sh            # 主入口脚本
├── install.sh               # Skill 安装脚本
├── lib/
│   ├── common.sh            # 公共函数（日志、参数校验）
│   ├── render.sh            # SVG 渲染 + 报告 + 差异报告生成
│   ├── annotate.sh          # 源码级标注（perf annotate）
│   ├── screenshot.sh        # Playwright SVG → PNG
│   └── collectors/
│       ├── cpu.sh           # CPU 采集器
│       ├── offcpu.sh        # Off-CPU 采集器
│       ├── mem.sh           # 内存采集器
│       ├── lock.sh          # 锁竞争采集器
│       ├── cache.sh         # 缓存/分支缺失采集器
│       ├── generic.sh       # 通用导入器
│       └── diff.sh          # 差异火焰图
├── Makefile               # 编译验证程序
├── FlameGraph/              # Brendan Gregg's FlameGraph（--setup 下载）
├── skills/
│   └── flamegraph-analyzer/
│       └── SKILL.md         # Claude Code 性能分析 skill
├── docs/                    # 设计文档和实现计划
├── output/                  # 默认输出目录
└── tests/
    ├── test_argparse.sh     # 参数解析测试
    ├── test_report.sh       # 报告生成测试
    ├── test_diff_report.sh  # 差异报告测试
    ├── test_icicle.sh       # 冰柱图模式测试
    └── workload/            # 工作负载验证程序
        └── test_workload.c
```

## 依赖

| 工具 | 必需 | 用途 |
|------|------|------|
| `bash` | 是 | 脚本运行环境 |
| `perf` (linux-tools) | 是 | CPU / Off-CPU / 内存 / 锁 / 缓存数据采集 |
| `perl` | 是 | 运行 FlameGraph 脚本 |
| `curl` | 否 | `--setup` 下载 FlameGraph |
| `bpftrace` | 否 | Off-CPU、内存、锁分析增强（更精确） |
| `npx` + `playwright` | 否 | `--screenshot` 截图功能 |

## 运行测试

```bash
./tests/test_argparse.sh    # CLI 参数校验测试
./tests/test_report.sh      # 报告生成测试
./tests/test_diff_report.sh # 差异报告测试
./tests/test_icicle.sh      # 冰柱图模式测试
```

## 环境要求

- Linux 服务器，建议 root 权限
- `perf_event_paranoid` 设置为允许采集（root 或设置 `/proc/sys/kernel/perf_event_paranoid` 为 0 或 -1）
- 内核支持 perf events，eBPF/bpftrace 需较新内核（4.x+）

## VM / 容器环境兼容性

工具集内置多级降级机制，在虚拟化或容器环境中可自动适配：

| 采集器 | 首选方案 | 降级方案 | 降级触发条件 |
|--------|---------|---------|-------------|
| CPU | `perf record -e cycles`（硬件 PMU） | `perf record -e cpu-clock`（软件事件） | 硬件计数器不可用（如 `max_precise=0`） |
| Off-CPU | bpftrace `kprobe:finish_task_switch` | `perf record -e sched:sched_switch` | bpftrace 不可用或内核符号不可访问 |
| Memory | bpftrace `uprobe:libc:malloc` | `perf mem record` → `perf record -e sys_enter_mmap,sys_enter_brk` | bpftrace/libc 不可用或硬件 PMU 不支持 |
| Lock | bpftrace `kprobe:__mutex_lock` | `perf record -e lock:contention_begin` → `perf record -e sys_enter_futex,sys_exit_futex` | bpftrace/kallsyms 不可用 |
| Cache | `perf record -e cache-misses,branch-misses` | `perf record -e cpu-clock` | 硬件 PMU 不可用（VM 中常见） |

运行时可通过 `[WARN]` 日志确认当前使用的采集方式。例如：

```
[WARN] Hardware PMU unavailable, using cpu-clock (software event)
[WARN] bpftrace collection failed, trying perf fallback...
[WARN] perf mem not supported, using syscalls:sys_enter_mmap,sys_enter_brk
[WARN] No mutex lock symbols found in /proc/kallsyms
[WARN] Hardware cache events unavailable, falling back to cpu-clock
```

### 已验证环境

| 环境 | CPU | Off-CPU | Memory | Lock | Cache | 备注 |
|------|-----|---------|--------|------|-------|------|
| 腾讯云 VM (AMD EPYC 7K62, 5.15 内核) | cpu-clock 降级 | perf sched_switch 降级 | sys_enter_mmap/brk 降级 | futex 降级 | cpu-clock 降级 | 硬件 PMU 不可用，bpftrace kprobe 受限 |
| 物理 Linux 服务器 (预期) | cycles 原生 | bpftrace 原生 | bpftrace uprobe 原生 | bpftrace kprobe 原生 | cache-misses 原生 | 全功能可用 |

## 验证程序

内置 C 语言多线程验证程序 `test_workload.c`，可产生可预测的工作负载用于测试：

```bash
# 编译
make

# 各模式测试
./flamegraph.sh -t cpu -c './test_workload cpu 30' -d 30
./flamegraph.sh -t offcpu -c './test_workload offcpu 30' -d 30
./flamegraph.sh -t mem -c './test_workload mem 30' -d 30
./flamegraph.sh -t lock -c './test_workload mixed 30' -d 30
./flamegraph.sh -t cache -c './test_workload cpu 30' -d 30
./flamegraph.sh -t cpu -c './test_workload mixed 30' -d 30   # 6 线程混合
./flamegraph.sh -t cpu -c './test_workload cpu 10' -d 10 --annotate  # 带源码标注
./flamegraph.sh -t cpu -c './test_workload cpu 10' -d 10 --icicle    # 冰柱图
./flamegraph.sh -t generic -f output/*.folded                  # 重放已有数据

# 差异火焰图
./flamegraph.sh -t cpu -c './test_workload cpu 10' -d 10
cp output/*_cpu.folded /tmp/baseline.folded
./flamegraph.sh -t cpu -c './test_workload cpu 10' -d 10
cp output/*_cpu.folded /tmp/current.folded
./flamegraph.sh -t diff --baseline /tmp/baseline.folded --current /tmp/current.folded
```

验证程序覆盖的工作负载：

| 工作负载 | 函数 | 验证场景 |
|---------|------|---------|
| CPU 密集 | `cpu_bubble_sort`, `cpu_quick_sort`, `cpu_prime_sieve`, `cpu_matrix_multiply` | CPU 火焰图热点识别 |
| I/O 阻塞 | `io_short_sleep`, `io_file_read_write`, `io_futex_wait` | Off-CPU 阻塞点定位 |
| 内存分配 | `mem_malloc_free_churn`, `mem_realloc_grow`, `mem_calloc_pattern` | 内存分配热点追踪 |
| 多线程混合 | 2 CPU + 2 Off-CPU + 2 Memory 线程 | 复杂场景综合验证 |

## 致谢

基于 [Brendan Gregg 的 FlameGraph](https://github.com/brendangregg/FlameGraph) 工具链构建。