用 experiment 完成一次可核验的 Hygon Trace 采集

hygon-trace-toolchain - 这篇文章属于一个选集。

§ 2: 本文

阅读信息
内容类型：教程
难度：高级
适合谁：已获得目标平台个人操作员账号、准备运行标准 STREAM 或 MLC Trace 的工程师
前置知识：SSH、Linux 命令行、CPU/NUMA 编号
读完后：先 dry-run 固定计划，再由 Experiment 管理 workload、锁、host controls、采集、Parser 与证据包
依据版本：<TRACE_HOST> Experiment 4.1.3 and standard templates verified 2026-08-23
验证日期：2026-08-23

下面这条命令在终端中执行时，不会启动被测负载，也不会向 PMU、SMN 或 Pattern 寄存器写入任何配置：

experiment run stream-copy-trace-qualified \
  --dry-run --json \
  --label copy-baseline-r1 \
  --cpu-list 0-15 \
  --threads 16 \
  --memory-node 0 \
  --completion stop_after_pipeline

它会在毫秒级时间内输出一份结构化的完整执行计划（plan）：明确 workload 绑定拓扑、三个硬件 stage 的执行顺序、所有底层可执行二进制的 SHA-256 哈希值、待应用的宿主机硬件控制，以及正式运行时会产生的具体副作用。在 <TRACE_HOST> 实测中，该命令返回码为 0，dry-run 结束后服务器状态依然保持为 TRACE=IDLE。

本教程面向已获得测试机个人操作员账号的工程师，演示如何从零完成一次端到端的可核验采集。目标不仅是得到若干原始 trace 文件，而是建立一套严谨的实验闭环：现场状态检查 → dry-run 审计计划 → 批准窗口执行 → 证据完整性核验 → Parser 报告解读与状态恢复。

本文不触发新的硬件采集。正式采集会占用全局 Trace Session、修改并回读硬件控制寄存器并生成大文件，必须在经过批准的实验窗口内进行。

用 experiment 从状态与模板资格检查、dry-run 审阅和批准窗口执行，到三层验收、报告检查与主机状态恢复的 Trace Run 流程 — 图：先审阅无副作用计划，获准后正式采集，再同时核对运行、完整性、分析结果和状态恢复。

1. 从个人操作员入口和当前状态开始
#

使用个人分配的 SSH 别名登录测试机：

ssh trace-lab-host

测试机上的公开命令通过受控的包装器自动处理底层提权，操作员无需也不能手工执行 sudo experiment ...。系统会自动提取 $SUDO_USER 或当前 POSIX 登录用户名，并将其固化到 run.json 的 operator 字段中。在非交互式检查中，trace-status --json 返回的操作员身份为当前个人账户，而非无差别的 root。

登录后的第一步是读取机器现场状态：

trace-status
trace-status --brief
trace-status --json

--brief 适合在进入终端时快速扫视：

<TRACE_HOST> TRACE=IDLE map=0x11000000@0x2080000000 dst=S1D5/16M

--json 则提供了可供脚本和自动化检查解析的完整结构：

{
  "schema": "hygon.trace-status/v4",
  "operator": "operator-a",
  "trace": {"state": "IDLE"},
  "pct": {"bypass": "off", "prefetch": "off"},
  "memmap": {"command": 3, "method": 1, "save_socket": 1, "save_die": 5, "ring_mib": 16},
  "errors": []
}

在开始任何采集前，必须确认以下四项基线事实：

trace.state 必须为 IDLE；
errors 数组为空；
拓扑回读信息（hostname、memmap 物理基址、save CDD 目标）符合预期；
pct（bypass/prefetch）字段反映的是主机当前物理寄存器的现状，而不是本次运行希望设置的目标值。

若发现 trace.state 为 BUSY，说明已有其他操作员或后台任务占用了 Trace Session。此时切忌强行删除 /run/lock/ 下的锁文件，必须等待占用者释放；否则竞争启动将直接返回错误码 75。

2. 先按资格选择模板
#

experiment run 支持直接引用模板库中的预置模板，或传入一份完整的 Spec JSON。在日常标准测试中，应当优先选择预置模板，因为它们已经锁定了 stage 编排顺序、Pattern profile 规则与参数覆盖范围。

当前环境中核心的四个标准（standard）模板为：

模板标识	适用 Workload	默认完成策略（completion）	场景特点
`stream-copy-trace-qualified`	STREAM Copy	`stop_after_pipeline`	内存带宽基准，流水线完成后主动停止测试进程
`stream-add-trace-qualified`	STREAM Add	`stop_after_pipeline`	三操作数访存基准，流水线完成后主动停止测试进程
`mlc-throughput-trace-qualified`	MLC throughput (`-T`)	`wait`	针对特定读写比例的固定时长吞吐测试，等待进程自然退出
`mlc-loaded-latency-trace-standard`	MLC loaded latency	`wait`	加载时延曲线测试，探针核与加载核独立配置

除上述四个标准模板外，系统还包含若干 qualified 模板（用于 PMU-only、C3/C4 等进阶诊断）。另外需要特别注意：系统中的 mysql-trace-contract、nvme-fio-contract 与 speccpu-trace-contract 属于 contract-only 模板。虽然它们包含结构 schema 并在虚拟单元测试中能够通过，但在真实生产机上对应的 hardware adapter 尚未完成资格认证，正式 run 调用会被严格拒绝。不要把“Spec schema 校验通过”误报为“硬件流水线已支持该业务负载”。

调用方式上也有一个严格的参数陷阱：

# 正确：传入 catalog 模板标识，支持追加 --label、--threads 等类型化模板参数
experiment run stream-copy-trace-qualified --dry-run --label test

# 错误：直接传入模板的物理 JSON 文件路径
experiment run /opt/hygon-trace/current/experiment/templates/stream-copy-trace-qualified.json \
  --dry-run --label test

后一种写法会触发错误提示：Spec files do not accept template parameters。这是因为工具链将绝对路径视为不可更改的静态完整 Spec；若要动态覆盖参数，必须使用 catalog 模板标识。

3. 用 dry-run 检查将要发生什么
#

在触碰物理硬件前，必须对计划进行预审。以 STREAM Copy 为例：

experiment run stream-copy-trace-qualified \
  --dry-run --json \
  --label copy-baseline-r1 \
  --cpu-list 0-15 \
  --threads 16 \
  --memory-node 0 \
  --completion stop_after_pipeline \
  --bypass off \
  --prefetch off

重点审阅输出 JSON 中的五组关键事实：

3.1 Workload 绑定拓扑
#

{
  "operation": "copy",
  "cpu_list": "0-15",
  "threads": 16,
  "memory_node": 0,
  "prefetch": "current"
}

cpu_list 表示逻辑 CPU 编号。在多 Socket 或多 NUMA 机器上，必须通过 numactl -H 或 lscpu 确认这些编号对应的物理 Socket、Die 与 Core 归属，不能仅凭连续编号推断其物理临近性。

3.2 宿主机硬件控制（Host controls）
#

{"req_bypass": "off", "prefetch": "off"}

这是本次 Run 明确申请的硬件状态。Experiment 仅在持有 hardware lease 后才会下发修改，并在采集结束后保证恢复。注意 workload.params.prefetch=current 与外层的 host_controls.prefetch=off 并不矛盾：前者指示 workload 启动脚本不要私自下发 MSR 修改，后者则由 Engine 在更高的硬件事务层级统一管控整机状态。

3.3 流水线阶段（Pipeline）
#

pmu_pre → trace → pmu_post

流水线是严格顺序执行且具备 fail-fast 语义的序列。在进入每个阶段前后，Engine 都会反复复验目标 workload 进程的健康与身份状态。

3.4 二进制身份固化
#

plan 不仅指定了执行程序，还记录了被测负载启动器、PatternCaptureTool.instrumented 采集器以及 PMU 监控脚本的二进制 SHA-256 摘要。任何外部动态链接库或脚本的非预期替换，都无法逃过 plan 阶段的哈希固化。

3.5 副作用清单（Side effects）
#

plan 会逐一列出正式运行将会执行的操作：创建 Run 目录、拉起 workload、获取硬件独占租约、下发并回读 host controls、执行 PMU/Pattern 采样，并在结束后仅终止由 Experiment 自身启动的子进程。审阅无误后，方可进入执行环节。

4. 在批准窗口启动正式 Run
#

确认 dry-run 计划无误且窗口获批后，去掉 --dry-run 标志即可进入正式采集：

experiment run stream-copy-trace-qualified \
  --json \
  --label copy-baseline-r1 \
  --cpu-list 0-15 \
  --threads 16 \
  --memory-node 0 \
  --completion stop_after_pipeline \
  --bypass off \
  --prefetch off

绝对不要将命令包装为外层嵌套：

# 错误用法：严禁多层嵌套
trace-run -- experiment run ...

experiment run 内置的包装器已经管理了 Trace Session 的生命周期；重复套用 trace-run 会导致生命周期锁冲突或逻辑重叠。

在底层，正式运行按序推进以下十个阶段：

申请 Trace Session，主机 trace-status 变为 BUSY；
校验 Host Profile、模板合法性、依赖工具路径及二进制签名；
创建标准输出目录 /home/<operator>/trace/runs/<type>/<UTC>/；
启动 workload 进程，等待其产生可审计的 readiness 日志事件；
获取 hardware lease，配置 ReqBypass/prefetch 寄存器并立即回读确认；
严格按顺序触发 pmu_pre、trace（Pattern）与 pmu_post；
依据 completion 策略安全终止自启动的 workload 或等待其完成；
将 ReqBypass 与 prefetch 寄存器原子化恢复为采集前的原始状态；
密封生成 run.json 描述体与所有产物的 SHA256SUMS；
若 Pattern 采集成功，自动拉起 Parser 生成初始分析摘要与报告。

采集完成后，正常 Run 目录下包含规范的元数据与数据目录；只有在某个 stage 异常失败或被外部信号中断时，输出目录中才会生成用于事后排查的 debug/ 目录。

5. 用 show 和 report 验收，不要只看退出码
#

采集命令返回 0 仅代表执行器自身未发生致命崩溃。合格的工程交付必须核验 Run 的完整状态。

首先列出当前操作员归档的 Run 列表：

experiment list

选中目标 Run 路径进行完整性与状态审阅：

RUN=<OPERATOR_HOME>/trace/runs/stream-copy-trace-qualified/20260821T040924Z
experiment show "$RUN"

该命令会对磁盘上所有文件执行实时的 SHA-256 校验，并输出顶层状态：

run.status            = succeeded
integrity.state       = valid
integrity.verified    = 82 / 82
run.analysis.status   = usable

验收时应依次核对五个核心字段：

integrity.state：必须为 valid，integrity.failures 必须为空；
run.status：顶层运行状态为 succeeded，run.errors 为空；
run.stages[].status：所有硬件 stage 均正常结束；
run.observations.host_controls：确认 requested、applied 与 restored 的值按预期流转；
run.analysis.status：Parser 的准入状态（usable 或 rejected）。

随后查看生成的面向人类的 Markdown 分析报告：

less "$RUN/analysis/report.md"

在 20260821T040924Z 基准 Run 中，报告显示 Analysis: usable，PMU 测得的均值带宽为 71.953 GB/s，UMC 硬件计数器均值带宽为 72.322 GB/s，两者相对偏差仅为 0.513%；同时报告中如实保留了 ccm_pmu_trend_deviation 警告。这一数值仅作为该示例 Run 的验收示范，不代表该硬件的全局峰值性能。

最后，再次核对主机是否已完全脱离采集状态：

trace-status --brief

正常退出后，主机必须回到 TRACE=IDLE，且 bypass/prefetch 恢复到运行前的原始状态（示例 Run 请求的是 on/on，记录显示原始为 off/off、生效为 on/on、最终恢复为 off/off）。

6. 出错时按状态层恢复
#

当实验未能正常收尾时，应根据返回码与状态机层次定界问题：

退出码 75：Session 或硬件租约占用
#

说明命令尚未触碰硬件，由于检测到并发 Session 或底层 hardware lock 繁忙而主动放弃。此时应使用 trace-status 确认占用者与进程 ID，等待其自然退出或与相关操作员沟通，绝对不要强行删除 /run/lock/ 下的锁文件。

退出码 2：配置或执行技术错误
#

若在 dry-run 阶段触发，通常是模板参数不合法或资源绑定冲突，检查返回的结构化 hygon.error/v1 中的 kind、message 和 JSON 指针 pointer。若在正式采集期间触发，说明某个 stage 运行失败，应检查 Run 目录下的 run.json.errors、对应 stage 的日志文件以及 debug/ 目录中的现场记录。

退出码 3：Parser rejected（资格准入未通过）
#

此状态说明底层 Capture 流水线本身已经 succeeded，硬件采集动作已完整完成并留存，但数据未能满足分析器的物理准入规则（例如时钟基准漂移过大或数据包缺失）。切勿把退出码 3 当成“采集丢包丢失”而将 Run 目录直接删除。保留 Run，查阅 analysis/summary.json 中的 qualification.failed_checks 字段以分析具体失败原因。

Parser 技术异常（Technical failure）
#

若 Capture 已经完成，但 Parser 自身由于环境或未捕获异常退出，底层的 Capture 状态仍然判定为 succeeded，且生成文件的完整性仍然有效。此时可以通过第三篇介绍的 pattern-trace 独立重跑分析，严禁直接在磁盘上手工修改 raw 文件以强行通过检查，因为那会破坏哈希清单导致 integrity.state 变为 invalid。

附录：常用模板配方
#

以下配方均应先附带 --dry-run --json 审阅参数拓扑，获准后再在实验窗口内正式执行。

STREAM Add
#

experiment run stream-add-trace-qualified \
  --dry-run --json \
  --label add-baseline-r1 \
  --cpu-list 0-15 --threads 16 --memory-node 0 \
  --completion stop_after_pipeline \
  --bypass off --prefetch off

MLC throughput（高负载吞吐）
#

experiment run mlc-throughput-trace-qualified \
  --dry-run --json \
  --label mlc-throughput-r1 \
  --load-cpus 0-15 --memory-node 0 \
  --duration 500 --pattern W7 \
  --bypass off --prefetch off

MLC loaded latency（时延曲线）
#

测试时延时，探测核心（probe-cpu）必须与施加压力的加载核心（load-cpus）保持严格互斥隔离：

experiment run mlc-loaded-latency-trace-standard \
  --dry-run --json \
  --label mlc-loaded-r1 \
  --probe-cpu 0 --load-cpus 1-15 --memory-node 0 \
  --duration 500 --pattern W7 --random false \
  --bypass off --prefetch off

所有模板均严格遵循同一执行模式：先 dry-run 固化计划与可执行哈希，在确认硬件拓扑与主机状态后，方可在批准窗口内完成一次可核验的 Trace 实验。

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

hygon-trace-toolchain - 这篇文章属于一个选集。

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

§ 2: 本文

§ 3: 用 pattern-trace 验证、重分析与解释 Trace 结果

§ 4: Hygon Trace Toolchain 操作与扩展速查

1. 从个人操作员入口和当前状态开始#

2. 先按资格选择模板#

3. 用 dry-run 检查将要发生什么#

3.1 Workload 绑定拓扑#

3.2 宿主机硬件控制（Host controls）#

3.3 流水线阶段（Pipeline）#

3.4 二进制身份固化#

3.5 副作用清单（Side effects）#

4. 在批准窗口启动正式 Run#

5. 用 show 和 report 验收，不要只看退出码#

6. 出错时按状态层恢复#

退出码 75：Session 或硬件租约占用#

退出码 2：配置或执行技术错误#

退出码 3：Parser rejected（资格准入未通过）#

Parser 技术异常（Technical failure）#

附录：常用模板配方#

STREAM Add#

MLC throughput（高负载吞吐）#

MLC loaded latency（时延曲线）#

相关文章