Hygon Trace Toolchain：从采集脚本到证据状态机

阅读信息

• 内容类型：解释
• 难度：中级
• 适合谁：需要理解 Hygon Trace 采集与分析链路的性能工程师
• 前置知识：Linux 命令行、PMU 与 trace 的基本概念
• 读完后：四个入口共同实现从当前事实、计划、采集到资格判定的证据状态机
• 依据版本：<TRACE_HOST> release directory 4.1.4; Experiment/Parser 4.1.3; Status 4.1.4; verified 2026-08-23
• 验证日期：2026-08-23

一次真实的 Trace Run 可以在结果中同时出现下面四行状态：

Capture status  : succeeded
Integrity state : valid
Analysis status : usable
Warning         : ccm_pmu_trend_deviation

在传统单脚本采集视角下，这几行容易引起困惑：既然采集成功，为什么分析只是“可用”还要带 warning？如果存在漂移警告，为什么完整性又是 valid？

它们描述的是三个完全不同的事实层级：

• Capture succeeded 说明底层采集流水线按顺序执行完毕；
• Integrity valid 说明 Run 目录下的所有文件经过 SHA-256 校验，与采集结束时的声明完全一致；
• Analysis usable 说明 Parser 确认必需的证据门（时间戳单调性、包格式、时钟基准）全部通过；
• Warning 则如实记录指标层面的物理限制（例如 CCM 与 PMU 计数口径偏差），提示分析者不要把请求路径上的观测直接等同于 DRAM 物理带宽。

理解 Hygon Trace Toolchain 的核心就在于：它不是一组松散的辅助脚本，而是一套把“宿主机现场状态”收敛为“可复核实验证据”的状态机。

1. 四个公开入口各守一道边界

#

2026-08-23 在 <TRACE_HOST> 上核对到的公开入口及其职责划分如下：

宿主机没有名为 trace-parser 的独立命令，Parser 的对外标准入口正是 pattern-trace。同样，底层的私有 backend、PatternCaptureTool 可执行程序以及 Python 内部模块均为内部实现细节，并非面向操作员的公开接口。

划分这四道边界，是为了终结传统的 ad-hoc 采集隐患： 如果操作员手工启动一个 workload，另开终端直接调用底层的 PatternCaptureTool 二进制，将几个 .raw 碎片拷贝出来并凭文件名推断测试场景，整个过程就会留下无法弥补的证据缺口：

• 采集触发时 workload 到底处于启动、预热还是稳定阶段？
• 硬件寄存器上的 ReqBypass 和 prefetch 当时究竟配置了什么值？采集异常退出后是否已经安全恢复？
• 生成的 raw 文件在转存和分析过程中是否被截断或损坏？

离开工具链的上下文约束，孤立的 raw 文件无法自证可信度。

2. 一次运行怎样变成证据包

#

工具链通过严格的生命周期管理，将一次采集收敛为可审计的 Run，依次回答六个关键问题：

1. 当前事实是什么？ 通过 trace-status 读取 Session 占用状态、主机硬件控制（host controls）以及 memmap 物理映射。
2. 准备执行什么？ 借助 experiment run ... --dry-run --json，在完全不触碰硬件的前提下，把输入模板和参数物化为一份无副作用的静态执行计划（plan）。
3. 谁拥有这次运行？ 进入正式 experiment run 后，系统建立以操作员命名空间、UTC 时间戳和稳定模板类型标识的唯一输出目录。
4. 采集是否按契约完成？ Engine 通过日志标记确认 workload 真正达到就绪态，并在硬件租约下按顺序推进 PMU 和 Pattern 采集。
5. Run 还是原来的 Run 吗？ 采集结束时，Engine 固化所有产物并生成 SHA256SUMS；后续通过 experiment show 复核磁盘上的文件集是否与声明完全吻合。
6. 证据够不够支持解释？ pattern-trace 对生成的证据包进行严格资格审查，核对时间线单调性、包流连续性以及前后 PMU 漂移。

标准 STREAM Trace 的内部流水线设计为：

launch workload
      ↓ (readiness evidence)
pmu_pre → trace (Pattern) → pmu_post
      ↓
Parser qualification and report

这里的关键在于：就绪判定绝不依赖盲目的固定等待（sleep）。 STREAM adapter 会实时监听 workload 输出流中的特定就绪标记并将其存为审计证据。Engine 在 collector 启动前、采集进行中和采集完成后，会对 workload 进程的身份进行多重采样与校验。为了防止 Linux 系统的 PID 回绕（PID reuse）导致将无关进程误判为目标测试程序，系统将进程 PID 与系统 boot ID、/proc/<pid>/stat 中的 starttime（进程启动时钟滴答数）共同绑定为不可伪造的身份元组。

采集流水线在 Pattern 硬件采样前后，分别设置了 pmu_pre 与 pmu_post 两个基线阶段。这样设计的目的是捕捉采集窗口前后的硬件计数漂移，从而向分析人员揭示背景负载是否在测试期间对总线造成了干扰。

3. Session lock 与 hardware lease 不是同一把锁

#

在高负载性能测试机上，并发控制分为两个不同层级：

操作员层级：[ Trace Session Lock ] (生命周期长，防止多人冲突，竞争返回 75)
                   ↓
硬件控制层级：[ Host Hardware Lease ] (生命周期短，原子事务配置/恢复寄存器)

Trace Session

#

面向操作员的使用周期。当执行 experiment run、PatternCaptureTool 包装器或 trace-run 时，锁机制会将 trace-status 中的状态从 IDLE 置为 BUSY。如果有其他操作员此时尝试启动新的采集，命令会立即拒绝执行并退出，返回专用退出码 75。当进程正常结束，或者捕获到 HUP、INT、TERM 信号时，包装器会负责执行 Session 的清理与释放。

Hardware lease

#

面向 Engine 内部的具体硬件执行阶段。PMU 与 Pattern collector 都会声明 hardware=true 属性。Engine 仅在真正需要读写物理硬件的阶段才获取全局排他的硬件租约。只有在持有硬件租约的前提下，Engine 才会对 ReqBypass 与 prefetch 寄存器下发修改，并立即执行回读验证；无论采集成功、抛出异常还是遭遇人为中断，Engine 都会在清理分支中将寄存器原子化恢复到 Run 开始前的基准状态。

这两层锁的侧重点不同：

• Session 锁防止两个操作员在同一台机器上并发执行实验、污染现场；
• Hardware lease 则防止内部不同 stage 或外部进程并发修改底层 SMN/MSR 寄存器。

操作员在终端中看到 Trace=IDLE，仅表示当前没有活跃的 Trace Session，绝不意味着可以跳过模板参数校验、磁盘空间预检和二进制签名确认。

4. succeeded、valid、usable 必须分别读取

#

在 <TRACE_HOST> 上保留的一份基准 Run 为例：

<OPERATOR_HOME>/trace/runs/
  stream-copy-trace-qualified/20260821T040924Z

使用 experiment show 检查该 Run 时，会得到如下结论：

Capture   : succeeded
Integrity : valid (82/82 files verified)
Analysis  : usable

这三个属性分别对应三个独立且递进的验证维度：

Capture succeeded

#

确认 workload 顺利进入就绪状态，pmu_pre、trace（Pattern）与 pmu_post 三个硬件 stage 均按预期退出码完成，Run 正常收尾。它只证明“采集动作执行完毕”，但不能证明生成的文件在事后未被篡改，也不能保证所有硬件计数都具有完全相同的物理意义。

Integrity valid

#

验证当前目录下的文件集合与生成时刻记录的清单严格一致。以该 Run 为例，清单中的 82 个文件全部通过了 SHA-256 校验。这一步回答的是“我们此刻看到的数据，是否依然是采集完成时所封存的原始证据”。

Analysis usable

#

表明 pattern-trace 所内置的硬性资格规则（Profile 格式校验、时间单调性、通道对齐）均已通过。

值得注意的是，该 Run 的最终分析报告中包含一条警告：

ccm_pmu_trend_deviation = -64.199%

这表明 CCM（Cache Coherent Master）请求路径上观测到的流量趋势与 PMU 实测数据存在显著偏差。但这并不意味着 Run 是损坏的。Parser 明确指明：CCM 反映的是互连网络交叉开关处的请求流，受协议开销和分包机制影响，不能直接换算为物理 DRAM 的吞吐带宽；报告以 PMU 和 UMC 控制器计数作为物理带宽的裁决标准，同时将 CCM 作为请求层行为特征予以保留。

因此，usable 的真正含义是：在报告所声明的测量口径与物理边界之内，该证据包具备学术和工程上的解释资格。 它既不代表没有 warning，也不代表所有层级的原始数值可以直接等同。

5. 版本也必须分层描述

#

在复杂服务器环境中，简单的“查看软件版本”往往充满歧义。在 <TRACE_HOST> 宿主机上：

如果仅看 /opt/hygon-trace/current 指向的 4.1.4 目录，就会误以为所有工具组件均已升级到 4.1.4；而实际上核心的 Experiment 执行器与 Parser 包仍然保持在 4.1.3 版本。

此外，本地源码仓库 <TRACE_SOURCE_ROOT> 的 Git HEAD 标签可能是 4.0.1，而未提交的工作树已经演进到 4.1.3，甚至包含服务器上尚未部署的 taiji-export 试验功能。如果在撰写实验复盘或向团队同步时只笼统写一句“基于 4.1 版本采集”，后续复现工作将极易陷入混乱。

严谨的规范表述应当精确到层级：

“本文基于 2026-08-23 在 <TRACE_HOST> 上核对的部署行为：release 目录为 4.1.4，Experiment 与 Parser 组件为 4.1.3，Status 组件为 4.1.4。”

若涉及未提交的工作树代码，则必须单独注明为“本地未部署能力”，不得混淆为生产环境行为。

6. 更新后的心智模型

#

综上所述，Hygon Trace 实验的交付物不再是一堆脱离上下文的 .raw 文件，而是一个具有完整生命周期、可追溯、可审计的 Run 证据实体：

现场基线确认 (trace-status)
  → 无副作用计划物化 (experiment run --dry-run)
  → 明确操作员命名空间与进程身份绑定 (experiment run)
  → 硬件租约排他保护与寄存器原子恢复 (Hardware lease)
  → 密文哈希锚定的文件完整性 (SHA256SUMS)
  → 具备边界声明与限制标注的领域分析 (pattern-trace)

在日常操作中，性能工程师应当遵循这一顺序：先用 trace-status 与 dry-run 锁定预期，获准后再触发正式 Run，最后分别核验 Capture、Integrity 和 Analysis 三个维度的状态。第二篇将按照这一模型，完整演练一次符合规范的 STREAM Trace 实验。

附录：证据范围

#

• 本地源码：<TRACE_SOURCE_ROOT> 工作树，2026-08-23 执行 make test 通过；ruff 未安装，相关可选 lint 检查已跳过。
• 服务器行为：2026-08-23 在 <TRACE_HOST> 实测的 CLI help 输出、各组件 pyproject 配置、trace-status --json 以及标准模板的 dry-run 响应。
• 基准 Run 证据：引用自既有归档 20260821T040924Z 的 experiment show 输出、analysis/summary.json 与 analysis/report.md。
• 测试边界说明：本文档未对生产硬件触发新的物理采集；文中所引用的具体带宽与漂移数值仅用于解释分析器的数据产出与判定逻辑，不构成该硬件平台的通用性能基准结论。

本文采用 CC BY-NC-SA 4.0 许可。