perf-prof

perf-prof 是一款 Linux 系统级性能分析工具，专为长期性能监控设计，具有低开销、广泛兼容性和高可靠性的特点。

English Version

您正在阅读中文版文档。English version available.

项目概述

perf-prof 是一款用户态性能分析工具，基于 libperf、libtraceevent 和 libbpf 构建。它提供实时分析能力，无需将事件数据写入磁盘，在内存中处理并立即丢弃。

核心特性

内存处理：事件在内存中处理并立即丢弃，无持久化存储开销
广泛兼容：支持旧版 Linux 内核（需要 perf_event 支持）
用户态实现：安全执行，快速迭代
模块化架构：30+ 专用分析器应对不同场景
低开销：内核级过滤减少用户空间数据传输
实时分析：实时处理事件，即时反馈

安装

前置依赖

# 安装必需依赖
yum install -y xz-devel elfutils-libelf-devel

# 可选：安装 eBPF 依赖
yum install -y llvm bpftool

从源码构建

# 克隆仓库
git clone https://github.com/OpenCloudOS/perf-prof.git
cd perf-prof

# 构建项目
make

# 详细构建输出
make V=1

# 清理构建产物
make clean

交叉编译

# 使用 CROSS_COMPILE
make CROSS_COMPILE=aarch64-linux-gnu-

# 使用 LLVM
make LLVM=1

使用 Standalone Python 构建

无需安装系统 python3-devel，可使用 python-build-standalone 启用 Python 分析器：

# 下载（自动检测架构，默认 Python 3.12）
packages/download-python-standalone.sh

# 解压
tar xzf cpython-*.tar.gz

# 使用 standalone Python 构建
make PYTHON=python/bin/python3

PYTHON= 选项会自动检测 standalone Python 的路径，设置 PYTHONHOME，并添加 -Wl,-rpath 链接 bundled libpython。可通过 PYTHON_HOME= 覆盖安装路径。

快速入门

列出可用分析器

# 列出所有分析器
./perf-prof -h

# 列出所有 tracepoint 事件
./perf-prof list

CPU 性能分析

# 以 997Hz 采样分析 CPU 使用情况，包含调用栈
./perf-prof profile -F 997 -g

# 使用 DWARF unwind 采样用户态调用栈（比帧指针更可靠）
./perf-prof profile -F 997 -g --user-callchain=dwarf

# 生成火焰图
./perf-prof profile -F 997 -g --flame-graph cpu.folded

# 仅分析用户态，指定 CPU，显示超过 30ms 的采样点
./perf-prof profile -F 997 -C 0-3 --exclude-kernel --than 30

内存泄露检测

# 检测内核内存泄露
./perf-prof kmemleak --alloc "kmem:kmalloc//ptr=ptr/size=bytes_alloc/stack/" \
                     --free "kmem:kfree//ptr=ptr/" --order -m 128 -g

进程调度分析

# 监控任务状态（R, S, D, T, I）
./perf-prof task-state -i 1000

事件跟踪

# 跟踪特定事件
./perf-prof trace -e sched:sched_wakeup,sched:sched_switch -i 1000

# 跟踪并过滤
./perf-prof trace -e "sched:sched_wakeup/prio<10/" -i 1000

分析器

perf-prof 提供 30+ 专用分析器，按类别组织：

CPU 性能分析

profile - CPU 性能采样分析
oncpu - 监控 CPU 上运行的进程

内存分析

kmemleak - 内存泄露检测
kmemprof - 内存分配分析
page-faults - 页面异常跟踪

调度与进程

task-state - 进程状态监控（R, S, D, T, I）
rundelay - 调度运行延迟分析

I/O 性能

blktrace - 块设备 I/O 跟踪

虚拟化

kvm-exit - KVM 退出延迟分析
kvmmmu - KVM MMU 映射观察

硬件监控

hwstat - 硬件状态监控（cycles, IPC）
llcstat - 最后一级缓存监控
tlbstat - dTLB 监控
ldlat-loads - Intel 加载延迟计数
ldlat-stores - Intel 存储指令计数
split-lock - x86 分裂锁检测

中断与定时器

hrtimer - 高精度条件采样
irq-off - 中断关闭检测
watchdog - 硬锁和软锁检测

数据分析

sql - SQL 聚合分析（基于 SQLite）
top - 键值统计分析
multi-trace - 多事件关系分析
syscalls - 系统调用延迟分析
python - Python 脚本事件处理

工具类

trace - 事件跟踪
list - 列出 tracepoint 事件
expr - 表达式测试工具
usdt - 用户静态定义跟踪
breakpoint - 内核/用户空间硬件断点
kcore - 读取内核内存
misc - 杂项跟踪

事件选择

perf-prof 遵循三层事件选择规范：

1. 获取系统事件

# 列出所有事件
./perf-prof list

# 按类别过滤
./perf-prof list | grep -E "^(sched:|kmem:|timer:|irq:)"

2. 查看事件帮助

# 查看事件字段
./perf-prof trace -e sched:sched_wakeup help

# 多个事件
./perf-prof trace -e sched:sched_wakeup,sched:sched_switch help

3. 事件语法

EVENT: sys:name[/filter/ATTR/ATTR/.../]
       kprobe:func[/filter/ATTR/ATTR/.../]
       kretprobe:func[/filter/ATTR/ATTR/.../]
       uprobe:func@"file"[/filter/ATTR/ATTR/.../]
       uretprobe:func@"file"[/filter/ATTR/ATTR/.../]

过滤器语法（内核态执行）

# 数值比较
./perf-prof trace -e "sched:sched_wakeup/pid>1000/"
./perf-prof trace -e "sched:sched_wakeup/prio<10/"

# 字符串匹配
./perf-prof trace -e 'sched:sched_wakeup/comm=="java"/'
./perf-prof trace -e 'sched:sched_wakeup/comm~"pyth*"/'

# 逻辑组合
./perf-prof trace -e "sched:sched_wakeup/pid>1000 && prio<10/"

属性（用户态执行）

stack                     # 启用调用栈
alias=str                # 事件别名
max-stack=int            # 最大栈深度
key=EXPR                 # 事件关联键
top-by=EXPR              # 排序字段
comm=EXPR                # 进程名显示
ptr=EXPR                 # 指针字段
size=EXPR                # 大小字段
num=EXPR                 # 数值分布字段

帮助系统

# 分析器帮助（包含示例）
./perf-prof trace -h
./perf-prof task-state -h

# 事件帮助（包含字段信息）
./perf-prof trace -e sched:sched_wakeup help
./perf-prof kmemleak --alloc kmem:kmalloc --free kmem:kfree help

文档

主文档

主要选项参考 - 完整命令行选项

分析器文档

profile - CPU 性能分析
task-state - 进程状态监控
multi-trace - 多事件分析
sql - SQL 聚合分析
top - 键值统计
kmemleak - 内存泄露检测
kvm-exit - KVM 退出分析
blktrace - 块设备 I/O 跟踪
trace - 事件跟踪
python - Python 脚本事件处理

高级主题

事件过滤 - Trace event 过滤器语法
表达式 - 表达式语言参考

测试

# 运行所有测试
cd tests
pytest

# 运行特定测试文件
pytest test_profile.py

# 使用自定义运行时和内存泄漏检查
pytest --runtime=20 --memleak-check=2000

开发

项目结构

perf-prof/
├── src/                  # 项目源码
│   ├── *.c              # 核心框架和分析器模块（30+ 个分析器）
│   ├── bpf-skel/        # BPF skeleton 程序
│   ├── filter/          # 事件过滤器（BPF, tracepoint, PMU）
│   └── sqlite/          # SQLite源码和扩展模块
├── lib/                  # 基础库（libperf, libtraceevent, libbpf）
├── arch/                 # 架构相关代码
├── include/              # 包含头文件
├── tests/                # 测试套件
├── docs/                 # 文档
├── packages/             # 打包脚本和补丁
└── skills/               # AI 辅助分析技能包

核心组件

监控框架：

src/monitor.c/h - 核心框架
src/tep.c/h - Trace 事件解析器
src/trace_helpers.c/h - Trace 事件工具
src/stack_helpers.c/h - 栈遍历和符号解析

分析单元：

每个分析器都是 src/ 下独立的 .c 文件
通过 PROFILER_REGISTER() 宏注册
支持 init, deinit, interval, read, sample 回调

事件处理管道

事件源 → 过滤器 → 环形缓冲区 → 排序 → 分析器 → 输出

添加新分析器

创建源文件 src/new_profiler.c
实现 profiler 结构体及所需回调
定义 name, desc, argc, option
使用 PROFILER_REGISTER() 注册
在 src/Build 文件中添加：perf-prof-y += new_profiler.o
在 tests/ 目录中添加测试

贡献

欢迎贡献！请遵循以下准则：

Fork 仓库
创建特性分支
为新功能编写测试
确保所有测试通过
提交 Pull Request

许可证

本项目采用 GPLv2 许可证。详见 LICENSE。

代码规范

遵循 Linux 内核编码风格
编写清晰、可维护的代码
为新功能包含测试
编写公共 API 和接口文档

致谢

基于 Linux内核组件构建：

libperf
libtraceevent
libbpf
其他实用库

FilesExpand file tree

README_CN.md

Latest commit

History

README_CN.md

File metadata and controls

perf-prof

目录

English Version

项目概述

核心特性

安装

前置依赖

从源码构建

交叉编译

使用 Standalone Python 构建

快速入门

列出可用分析器

CPU 性能分析

内存泄露检测

进程调度分析

事件跟踪

分析器

CPU 性能分析

内存分析

调度与进程

I/O 性能

虚拟化

硬件监控

中断与定时器

数据分析

工具类

事件选择

1. 获取系统事件

2. 查看事件帮助

3. 事件语法

过滤器语法（内核态执行）

属性（用户态执行）

帮助系统

文档

主文档

分析器文档

高级主题

测试

开发

项目结构

核心组件

事件处理管道

添加新分析器

贡献

许可证

代码规范

相关链接

致谢