Rust Flamegraph

Rust Flamegraph 性能分析

前置条件

cargo install cargo-flamegraph
sudo sysctl kernel.perf_event_paranoid=0  # 允许非 root 采样

工作流

Step 1: 确定分析目标

明确要分析的操作和测试入口：

• 哪个函数/模块需要分析？
• 对应的测试在哪里？（lib unit test / 集成测试 / bench）
• 预期的性能瓶颈在哪？（IO / CPU / 内存分配 / 锁争用）

Step 2: 准备测试入口

优先使用集成测试（tests/ 目录），cargo flamegraph --unit-test 对 lib 内测试支持不稳定。

# 集成测试（推荐）
cargo flamegraph --dev [OPTIONS] --test  --  [test_args]

# bench
cargo flamegraph --dev [OPTIONS] --bench  -- 

关键原则：

• 测试函数内用 std::time::Instant 计时并 eprintln! 输出，配合 --nocapture
• 测试数据量要足够大（建议 10w+ 操作），否则采样点不足
• 随机数据范围要足够大，避免重复（如 0..5000 而非 0..500）
• 将耗时操作集中在单个测试函数中，避免 build 阶段混入火焰图

典型测试结构：

#[test]
fn perf_xxx() {
    // 1. 准备数据（不计入测量）
    let data = prepare_data();
    
    // 2. 计时执行（这是火焰图分析的目标）
    let start = Instant::now();
    for item in &data {
        target_function(item);
    }
    let elapsed = start.elapsed();
    
    // 3. 输出结果
    eprintln!("ops: {:.0}/s, per_op: {:.2?}", 
        count as f64 / elapsed.as_secs_f64(), elapsed / count as u32);
}

Step 3: 生成火焰图

# 推荐参数
cargo flamegraph \
  --dev \                          # debug 编译（保留函数名）
  --no-inline \                    # 不内联，保留函数调用栈
  --image-width 1500 \             # 宽图，看清函数名
  --freq 8000 \                    # 采样频率 8000Hz
  --palette rust \                 # Rust 友好配色
  --test  --  --nocapture

参数说明：

| 参数 | 说明 | 建议值 | |------|------|--------| | --dev | debug 编译，保留符号 | 必选 | | --no-inline | 禁止内联，展开调用栈 | 推荐 | | --image-width | SVG 宽度(px) | 1500-2000 | | --freq | perf 采样频率(Hz) | 8000-99999 | | --palette | 配色方案 | rust / io / hot | | --test | 集成测试文件名 | 对应 tests/ 下的文件 | | --bench | bench 文件名 | benches/ 下的文件 |

输出: 项目根目录生成 flamegraph.svg

Step 4: 提取热点数据

从 SVG 中提取函数占比（自动化脚本）：

# 提取热点函数及占比，按占比降序
rg '' flamegraph.svg | \
  sed 's/.*\(.*\).*/\1/' | \
  rg -v 'kernel|syscall|page_fault|_dl_|glibc|__GI_|_start|clone|thread_start|_int_free|_int_malloc|cfree|libc_start' | \
  sort -t'(' -k2 -rn | head -30

输出格式: function_name (N samples, X.XX%)

重点关注：

• 项目自身函数（含 crate 名或模块路径）
• 标准库中的热点（alloc::, core::, DashMap 等）
• 内存分配相关（malloc, _int_malloc, sysmalloc）

Step 5: 分析热点

常见热点模式及优化方向：

| 热点模式 | 典型占比 | 优化方向 | |----------|----------|----------| | str::split + fold | 10-15% | 预计算/缓存编码结果 | | DashMap::insert | 10-20% | 减少写入/批量写入/Arc 替代 String key | | DashMap::get | 5-15% | 缓存查找结果/减少查表次数 | | alloc::fmt::format | 2-5% | 预分配 String/避免热路径 format! | | String::hash | 3-10% | Arc 替代 String/换用更快的 hasher | | malloc/_int_malloc | 5-15% | 对象池/预分配/减少 clone | | malloc_consolidate | 1-3% | 减少内存碎片/用 jemalloc | | Drop (析构) | 5-10% | 延迟析构/对象池复用 | | Arc::clone | 1-5% | 减少引用计数操作/传引用 |

Step 6: 量化对比

优化前后用相同参数生成火焰图，对比：

1. 同一函数占比变化
2. 总采样时间变化
3. eprintln! 输出的 ops/s 变化

火焰图管理：

# 重命名保留（SVG 被 .gitignore 排除，不提交）
mv flamegraph.svg flamegraph__.svg

常见问题

perfeventparanoid 报错

Error: Access to performance monitoring and observability operations is limited

解决: sudo sysctl kernel.perf_event_paranoid=0

no automatically selectable target

Error: crate has no automatically selectable target

解决: 用 --test 或 --bench 指定目标，而非 --unit-test

samples too few

火焰图信息稀疏 → 提高测试数据量或提高 --freq

build_trie 阶段占比过高

测试中 build 阶段被采样 → 在测试函数中仅对目标操作计时，build 放在计时外

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hellyguo
• Source: hellyguo/self-ai-spec
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.