Performance Benchmarks

性能基准测试

FastQTools 内置完整的性能基准测试系统，支持回归检测、基线管理和报告生成。

---

最新性能数据（100K reads, 150bp）

操作	吞吐量	耗时
FastQReader Medium	1696.50 MB/s	18.8 ms
FastQWriter Medium	1.76 M reads/s	57.0 ms
Filter Combined (100K)	1.67 M reads/s	60.5 ms
Stat Full (100K)	301.91 MB/s	104.6 ms

---

快速开始

# 构建 benchmark 目标
cmake --build build-clang-release --target benchmarks

# 运行基准测试
./scripts/benchmark run

# 生成报告
./scripts/benchmark report

# 检测性能回归
./scripts/benchmark compare baseline.json current.json

---

CLI 命令

benchmark run — 运行测试

./scripts/benchmark run [options]

Options:
  --output, -o    指定输出文件路径
  --filter        过滤要运行的测试（正则表达式）
  --repetitions   重复次数（默认: 1）
  --ci            CI 模式

benchmark report — 生成报告

./scripts/benchmark report [options]

Options:
  --input, -i     输入 JSON 文件
  --format, -f    输出格式 (markdown, summary, readme)
  --charts        生成图表（需要 matplotlib）

benchmark compare — 回归检测

./scripts/benchmark compare <baseline> <current> [options]

Options:
  --warning-threshold   警告阈值（默认: 10%）
  --critical-threshold  严重阈值（默认: 20%）
  --ci                  CI 模式输出

benchmark baseline — 基线管理

./scripts/benchmark baseline save <name>   # 保存基线
./scripts/benchmark baseline list           # 列出基线
./scripts/benchmark baseline delete <name>  # 删除基线

benchmark data — 测试数据

./scripts/benchmark data generate          # 生成测试数据集
./scripts/benchmark data validate <file>   # 验证 FASTQ 格式

---

基准测试类别

IO 基准测试

测试项	说明
BM_FastQReader_*	读取性能（纯文本 / gzip）
BM_FastQWriter_*	写入性能（含 gzip 压缩）

Filter 基准测试

测试项	说明
BM_Filter_NoFilter	无过滤（基线）
BM_Filter_MinLength	最小长度过滤
BM_Filter_MinQuality	最小质量过滤
BM_Filter_MaxNRatio	N 比例过滤
BM_Filter_Combined	组合过滤

Stat 基准测试

测试项	说明
BM_Stat_Basic	基本统计
BM_Stat_BaseComposition	碱基组成统计
BM_Stat_QualityDistribution	质量分布统计
BM_Stat_LengthDistribution	长度分布统计
BM_Stat_Full	完整统计

---

测试数据集

使用合成 FASTQ 数据，确保结果可重复：

数据集	Reads 数量	Read 长度	文件大小
Small	10,000	150bp	~2.5 MB
Medium	100,000	150bp	~25 MB
Large	1,000,000	150bp	~250 MB

---

关键指标

指标	说明	单位
mean_time_ns	平均执行时间	纳秒
std_dev_ns	标准差	纳秒
throughput_mbps	数据吞吐量	MB/s
throughput_reads_per_sec	Reads 吞吐量	reads/s
peak_memory_bytes	峰值内存	bytes

---

JSON 输出格式

{
  "metadata": {
    "timestamp": "2026-01-12T10:30:00Z",
    "git_commit": "abc123",
    "cpu_model": "Intel Core i7",
    "core_count": 8
  },
  "results": [
    {
      "name": "BM_FastQReader_Medium",
      "category": "io",
      "iterations": 100,
      "mean_time_ns": 50000000,
      "throughput_mbps": 200.5
    }
  ]
}

---

CI 集成

自动运行时机

• Push 到 main 或 develop 分支
• Pull Request 到 main 分支
• 每周一 UTC 00:00 定时运行
• 手动触发

回归检测

级别	阈值	结果
警告	性能下降 10–20%	CI 报告警告
严重	性能下降 >20%	CI 失败

---

目录结构

benchmark_results/
├── results/           # 历史测试结果 (YYYY-MM-DD_HH-MM-SS_<commit>.json)
├── baselines/         # 命名基线 (<name>.json)
├── reports/           # 生成的报告
│   ├── latest.md
│   └── charts/*.svg
└── data/              # 测试数据
    ├── small_10k.fastq
    ├── medium_100k.fastq
    └── large_1m.fastq

---

添加新的基准测试

1. 创建测试文件

在 tools/benchmark/ 目录下创建 .cpp 文件：

#include <benchmark/benchmark.h>
#include <fqtools/io/fastq_reader.h>

namespace fq::benchmark {

static void BM_MyNewBenchmark(::benchmark::State& state) {
    for (auto _ : state) {
        // 被测代码
        ::benchmark::DoNotOptimize(result);
    }
    state.SetItemsProcessed(state.iterations() * num_items);
    state.SetBytesProcessed(state.iterations() * bytes);
}

BENCHMARK(BM_MyNewBenchmark)
    ->Args({10000})
    ->Args({100000})
    ->Unit(::benchmark::kMillisecond);

}  // namespace fq::benchmark

2. 更新 CMakeLists.txt

add_benchmark(benchmark_my_new
    my_new_benchmark.cpp
)

---

测试环境

项目	推荐配置
操作系统	Ubuntu 22.04 LTS
编译器	Clang 21 / GCC 15
构建类型	Release (-O3)
CPU	多核 x86_64
内存	16GB+ RAM

---

性能优化建议

建议	说明
使用多线程	--threads N 设为 CPU 核心数
增大 batch size	大文件场景下提升吞吐
压缩输出	.gz 后缀自动启用压缩
Release 构建	确保使用 -O3 -march=native
关闭调试日志	-q 静默模式减少 I/O 开销

---

故障排除

问题	解决
构建失败	确保已安装 Google Benchmark：conan install . --build=missing
结果不稳定	关闭其他 CPU 密集程序、增加 --repetitions、使用 Release 构建
图表生成失败	pip install matplotlib

---

相关页面

• Architecture — 并发模型与性能设计
• Build and CI — 构建系统
• Code Quality Tools — 分析与调优工具