Rust Bench — Rust 性能基准测试与剖析框架

English version

Rust 程序运行时性能基准测试、数据采集、终端可视化与剖析工具包。基于 rustc-perf 构建，扩展了运行时基准测试能力、自定义指标、TUI 比较界面与多平台（GitCode/GitHub）多仓库支持。

代码库中存在继承自上游 rustc-perf 的编译时基准测试机制，但非本项目重点。本 README 与文档集覆盖运行时基准测试与分布式基准测试系统。

功能

运行时基准测试——用硬件性能计数器（perf_event_open）、墙钟计时与内存峰值，衡量 Rust 程序在给定 rustc 下的执行速度。
本地与分布式——单机基准测试（结果存 SQLite），或自动化流程：中心 Site 接收 webhook，Collector 从 Postgres 队列拉取任务，比较评论回发到 PR/MR。
剖析——Cachegrind（指令级）与 perf-record（采样）；cachegrind 可比较两个 rustc 构建。
多平台、多仓库——在 GitCode 与 GitHub 上对 Rust 工具链与非 Rust 仓库（如 Daft 数据框库）跨多架构并行基准测试。

安装

预编译二进制包

预编译二进制包可在 Releases 页面下载。

包名	内容
rust-bench-collector	`collector` 二进制 + 运行时 benchmark 模块源码 + `site-config.toml` 模板
rust-bench-site	`site` 二进制 + `site-config.toml` 模板

下载、解压后按照包内 README 即可使用，无需编译。

从源码编译

cargo build --release

详见本地基准测试指南。

快速上手

前置条件

Linux（perf_event 硬件计数必需）。
Rust stable 工具链。

启用用户态性能计数：

sudo bash -c 'echo -1 > /proc/sys/kernel/perf_event_paranoid'

运行基准测试（最小示例）

# 用 nightly 工具链基准测试标准库运行时套件
./target/release/collector bench_runtime_local +nightly --group std

# 在交互式 TUI 中比较两次运行
./target/release/collector bench_cmp --db results.db

<RUSTC> 接受 rustc 可执行路径或 + 前缀工具链名。基准测试名为 module_path::fn_name，故前缀过滤对完整路径匹配（如 --include std_bench::hash）。

已知限制

CI 模式（PostgreSQL + webhook）目前仅支持 daft 模块。其他模块（monoio、auron、firecracker、wasmtime、tikv）仅支持本地模式（bench_runtime_local）。

文档

完整文档位于 docs/。命令与细节的唯一真源是对应指南，而非本 README。

指南（流程——怎么做）：

本地运行基准测试——bench_runtime_local、过滤、输出、bench_cmp TUI。
编写运行时基准测试——#[bench] 宏与自定义框架。
剖析基准测试——Cachegrind 与 perf-record；比较两个 rustc 构建。
部署 Site——Docker、Postgres、site-config.toml、webhook 端点。
部署 Collector——注册、collect-job-queue.sh、机器准备。
接入 GitCode 与 GitHub——webhook 配置、/rust-bench 命令、完成评论。

参考文档（事实——是什么）：

架构 · 配置 · 任务队列 · 部署模型 · 比较分析 · 术语表
数据库 schema · 手动修改

项目结构

rust-bench/
├── collector/                 # 基准测试执行器 + benchlib 测量库
│   ├── benchlib/             # 链接进每个运行时基准测试二进制
│   ├── benchlib-macros/      # #[bench] 过程宏
│   ├── runtime-benchmarks/   # 运行时基准测试套件（std、core、alloc、fmt、daft、...）
│   ├── compile-benchmarks/    # 遗留编译时套件（不在范围）
│   └── src/
│       ├── bin/collector.rs  # CLI 入口
│       ├── runtime/          # 运行时基准测试执行 + 剖析
│       └── compare/screen.rs# bench_cmp TUI
├── database/                 # SQLite/Postgres 层 + schema 文档
├── site/                     # Web 服务器 + 任务队列 + 平台（GitCode/GitHub）集成
│   └── src/{main,server,load,job_queue,github,request_handlers}.rs
├── docs/                     # 参考文档 + 指南（本文档集）
├── site-config.toml          # Site 配置模板
├── Dockerfile                # Site 多阶段 Docker 构建
├── docker-compose.yml        # 测试用一次性 Postgres 16
└── Cargo.toml                # 工作区配置