第五章：性能可观测——计时系统与调优实践

本章学习目标：掌握 evaluate_and_call 进行微基准测试，以及 Timer 单态类进行生产环境全流程耗时采集与分析。

5.1 为什么需要统一的计时系统

性能调优的第一步是测量。没有精确的数据，优化就变成了盲目的猜测。

在 eroam 的早期开发中，计时代码散落在各处：有的模块用 std::clock，有的用 ros::Time，有的直接打印 ROS_INFO。这种碎片化的做法带来了三个问题：测量精度不一致导致数据无法横向对比；重复实现性能统计逻辑浪费开发时间；最关键的是，生产环境的真实耗时与开发阶段的基准测试结果往往对不上——你优化了代码，却不知道在实际运行中有没有效果。

system_timer_support 模块的设计目标就是解决这些痛点。它提供两套互补的接口：一套用于开发阶段的微基准测试，另一套用于生产环境的全流程监控。两者共享相同的时间测量精度，但针对不同的使用场景做了优化。

5.2 微基准测试：evaluate_and_call

开发阶段需要回答的问题是：这个函数到底有多快？evaluate_and_call 就是为此设计的。

它的工作方式很直接：接收一个可调用对象、一个标识名称、一个迭代次数，然后执行指定次数，计算平均耗时并输出到日志。这类似于 Python 的 timeit 模块，或者 Google Benchmark 的简化版本。

// 来自 src/sys_utils.h，第13行起
template <typename Func>
void evaluate_and_call(Func&& func, const std::string& func_name, uint32_t times) {
    auto t1 = std::chrono::high_resolution_clock::now();
    for (uint32_t i = 0; i < times; ++i) {
        func();
    }
    auto t2 = std::chrono::high_resolution_clock::now();
    auto dt = std::chrono::duration_cast<std::chrono::duration<double, std::milli>>(t2 - t1);
    // 输出平均耗时和调用次数
}

5.2.1 设计权衡：为什么不用外部基准测试库

你可能会问：为什么不直接用 Google Benchmark 或 Hayai？这些库功能更丰富，统计也更专业。

evaluate_and_call 的存在是为了降低使用门槛。引入外部依赖意味着额外的编译配置、版本兼容性问题，以及学习成本。对于 eroam 的核心开发场景——快速验证 KD 树操作、点云转换等函数的耗时——这个 20 行左右的模板函数已经够用。它用 std::chrono::high_resolution_clock 保证纳秒级精度，用模板转发引用避免函数对象拷贝，用 glog 直接输出结果到日志系统，无需额外配置。

代价是功能受限：没有自动统计方差、没有 CPU 缓存预热、没有防止编译器优化的技巧。如果你需要 publication-quality 的基准测试数据，仍然应该使用专业工具。但对于日常开发中的"这个改动让代码变快还是变慢"，evaluate_and_call 足够高效。

5.2.2 使用场景与注意事项

典型的使用场景是验证 KD 树操作的性能。假设你想知道单点插入的耗时：

#include "sys_utils.h"

// 测试 KD 树单点插入，重复 100 次取平均
fx::evaluate_and_call([]() {
    kd_tree.Insert(test_point);
}, "KDTree::Insert", 100);

输出示例：

I0912 14:32:00.123456 1234 sys_utils.h:25] Method KDTree::Insert average call time/count: 0.23/100 ms.

关键前置条件：times 必须大于等于 1。传入 0 会导致除零错误，这是模块未显式检查的一个边界情况。

副作用假设：evaluate_and_call 假设被测函数执行多次是安全的。如果你的函数会修改全局状态（比如真的往 KD 树里插入数据），多次执行会累积副作用。此时应该使用纯测试数据，或在 lambda 中包裹重置逻辑。

5.3 生产环境监控：Timer 单态类

微基准测试回答"能有多快"，生产监控回答"实际有多快"。两者的差异在于：生产环境有真实的数据分布、真实的内存压力、真实的线程竞争。

Timer 类的设计类似于飞机上的"飞行数据记录仪"（black box）。它在系统运行期间静默记录所有关键操作的耗时，不输出任何日志，直到你主动查询或导出。这种设计避免了日志洪水对性能的影响，同时保留了完整的统计信息。

5.3.1 架构与数据流

数据流说明：

• 业务流程中的任意位置调用 Timer::Evaluate(func, name)，耗时数据自动存入全局 records_ 映射表
• 映射表以函数名为键，TimerRecord 结构体为值，后者包含函数名字符串和耗时向量
• 流程结束后，通过 PrintAll、DumpIntoFile 或 GetMeanTime 获取统计结果
• Clear 方法清空所有记录，同时自动调用 ikd-Tree 的 clear 方法，完成全链路状态重置

5.3.2 单态设计：便利与陷阱

Timer 是一个纯静态类——没有实例，所有方法都是静态的，所有数据都是静态的。这种设计消除了"把定时器实例传到哪一层"的问题。在 eroam 的单流水线架构中，全局唯一的统计结果正好满足需求。

代价是测试隔离困难。单元测试 A 写入的记录会残留到单元测试 B，导致统计结果污染。解决方案是在每个测试用例开始时调用 Timer::Clear()，但这引入了另一个陷阱：Clear 会联动重置 ikd-Tree 状态。如果你只想清空计时记录而保留树结构，不能直接调用 Clear。

5.3.3 时钟选择：steady_clock 的保守主义

Timer::Evaluate 使用 std::chrono::steady_clock 而非 high_resolution_clock。这是一个刻意的保守选择。

high_resolution_clock 在某些平台上等价于系统实时时钟，会受到 NTP 同步、用户手动调时的影响。想象你的 SLAM 系统运行了 2 小时，期间系统时间被回调了 1 分钟——用实时时钟计算出的耗时会出现负数或异常大的值。steady_clock 保证单调递增，不受系统时间变更干扰，代价是部分平台下精度略低。

对于 eroam 关注的毫秒级操作耗时，这种精度损失可以忽略。稳定性优先于极致精度。

5.3.4 线程安全：显式的单线程假设

Timer 不是线程安全的。records_ 映射表没有任何同步保护，多线程并发调用 Evaluate 会导致数据竞争，表现为统计数值错乱或程序崩溃。

这个设计选择基于 eroam 的架构现实：核心 SLAM 流程是单线程顺序执行的，KD 树的并行查询在内部管理自己的线程池，不需要外部计时介入。如果你的扩展代码确实需要多线程计时，必须自行添加互斥锁保护所有 Timer 方法调用。

单线程场景下支持重入。你可以在被测量的函数内部再次调用 Timer::Evaluate，嵌套计时会正常记录到各自的键名下。

5.3.5 使用示例：完整的监控流程

#include "timer.h"

void ProcessFrame(const PointCloud& cloud) {
    // 记录点云预处理耗时
    eroam::common::Timer::Evaluate([&]() {
        auto downsampled = VoxelDownsample(cloud);
        auto deskewed = DeskewByIMU(downsampled);
        return deskewed;
    }, "PreprocessFrame");
    
    // 记录 KD 树批量插入耗时
    eroam::common::Timer::Evaluate([&]() {
        kd_tree.Add_Points(deskewed);
    }, "KDTree::Add_Points");
    
    // 记录近邻查询耗时
    std::vector<int> indices;
    eroam::common::Timer::Evaluate([&]() {
        kd_tree.Nearest_Search(query_point, 5, indices);
    }, "KDTree::Nearest_Search");
}

// 运行结束后导出分析
void DumpPerformanceReport() {
    // 控制台打印所有统计结果
    eroam::common::Timer::PrintAll();
    
    // 导出为 CSV，便于用 Python/R 分析
    eroam::common::Timer::DumpIntoFile("session_performance.csv");
    
    // 程序化获取特定指标
    double avg_preprocess = 
        eroam::common::Timer::GetMeanTime("PreprocessFrame");
    
    // 准备下一轮测试
    eroam::common::Timer::Clear();  // 注意：这会同时清空 KD 树！
}

5.4 两套接口的对比与选择

选择依据很简单：如果你在写代码、做优化、验证改动效果，用 evaluate_and_call；如果你在跑完整数据集、分析系统瓶颈、生成性能报告，用 Timer。

5.5 性能调优实践：从数据到行动

有了计时数据，如何指导优化？以下是 eroam 开发中的典型流程。

5.5.1 识别热点

首先用 Timer 跑完一个典型数据集，导出 CSV 后用简单脚本分析：

import pandas as pd
df = pd.read_csv('session_performance.csv')
print(df.groupby('operation')['time_ms'].agg(['mean', 'std', 'count']))

寻找两个信号：平均耗时占比高的操作，以及标准差异常大的操作。前者是优化收益最大的目标，后者往往暗示着缓存未命中、内存分配抖动或分支预测失败。

5.5.2 微基准验证假设

假设你发现 KDTree::Add_Points 占用了 40% 的总时间，怀疑是点云排序开销导致。写一个隔离的基准测试：

// 测试不同批次大小的插入性能
for (int batch_size : {100, 500, 1000, 5000}) {
    auto batch = GenerateRandomPoints(batch_size);
    fx::evaluate_and_call([&]() {
        test_tree.Add_Points(batch);
    }, "Add_Points_" + std::to_string(batch_size), 100);
}

如果数据显示批次越大、单点平均耗时越低，说明你的假设正确——批量处理摊平了固定开销。反之则需要寻找其他原因。

5.5.3 回归测试防止退化

性能优化最怕"进两步退一步"。将关键指标的基准测试加入 CI 流程，每次提交自动对比：

// 在测试套件中
TEST(PerformanceRegression, KDTreeInsert) {
    // 建立基线环境
    SetupStandardTree();
    
    fx::evaluate_and_call([]() {
        StandardInsertWorkload();
    }, "KDTree_Regression_Test", 1000);
    
    // 解析日志或捕获输出，断言平均耗时 < 阈值
    // 实际实现可能需要重定向 glog 输出
}

5.6 常见陷阱与排查

症状：统计数据明显偏离预期

检查函数名是否唯一。Timer 以字符串为键聚合数据，两个不同操作使用相同名称会导致统计混合。建议采用 Module::Class::Method 的命名规范。

症状：GetMeanTime 崩溃或返回异常值

确认该函数名已被记录过。GetMeanTime 对不存在的键没有保护，直接访问会导致未定义行为。生产代码应先确保测量代码被执行，或添加存在性检查（当前 API 未直接提供，需自行封装）。

症状：Clear 后 KD 树行为异常

Timer::Clear 的设计意图是全链路重置，它会自动调用 ikd_tree.clear()。如果你只想清空计时记录而保留树结构，目前模块没有提供单独的接口。这是设计上的耦合，需要在架构层面接受。

症状：多线程场景下统计错乱

如前所述，Timer 不是线程安全的。如果必须在多线程环境使用，封装一个线程安全的包装类：

class ThreadSafeTimer {
    static std::mutex mtx_;
public:
    template<typename Func>
    static void Evaluate(Func&& func, const std::string& name) {
        std::lock_guard<std::mutex> lock(mtx_);
        eroam::common::Timer::Evaluate(std::forward<Func>(func), name);
    }
    // 同理封装其他方法...
};

注意这会引入锁竞争开销，高频调用的测量点可能成为新的瓶颈。

5.7 本章小结

性能可观测性建立在两个工具之上：evaluate_and_call 用于开发阶段的快速验证，Timer 用于生产环境的持续监控。两者分工明确，但共享相同的设计哲学——最小侵入、最低开销、最简接口。

关键记住三点：始终调用 Clear 隔离测试运行，始终保证函数名全局唯一，始终确认你的线程模型与 Timer 的单线程假设兼容。有了可靠的测量数据，优化就不再是猜测，而是有方向的工程实践。

5.8 延伸阅读

• src/sys_utils.h：evaluate_and_call 的完整实现
• src/timer.h / src/timer.cc：Timer 类定义与实现
• thirdparty_ikd_tree.md：KD 树模块，计时系统的主要用户之一
• Google Benchmark 文档：当 evaluate_and_call 无法满足需求时的升级路径