[RFC]: Mooncake UbDiag 两层分发与单 RPM 可复现交付

[qinyufei63]

Changes proposed

背景

Mooncake 的核心数据路径已经使用 UbDiag PerfPoint 埋点。现有使用方式若要求用户另行安装与 Mooncake 编译时 libubdiag.so 完全匹配的 CLI，会引入版本漂移、ABI 不一致和交付拆分问题；同时，默认构建不应强制引入 UbDiag 运行时依赖。

本 RFC 对应 PR #13，目标是在不改变 Mooncake 默认运行依赖的前提下，建立可复现的两层集成和单 RPM 交付链路。

目标

• 默认 Layer 0 使用 UBDIAG_DISABLE：保留 PerfPoint 调用语法，编译为空实现，不链接或打包 UbDiag CLI/动态库。
• 可选 Layer 1 使用 FetchContent：从固定仓库拉取并校验完整 40 位提交 8df2c2844d402e2e4dcd5ceab2424e8d36c5f99f，在同一 CMake 图中构建 libubdiag.so 与 ubdiag CLI。
• Layer 1 只生成一个 Mooncake RPM；包内同时包含 Mooncake、UbDiag CLI、同源动态库、配置和 provenance 文件。
• 打包阶段拒绝系统路径、PATH 或 LD_LIBRARY_PATH 中其他 UbDiag 版本的干扰。
• 最终 RPM 清除构建目录 RPATH/RUNPATH，并记录最终打包字节的 SHA256。

方案

源码身份

CMake 同时记录可读 ref 和不可变完整 SHA。无论在线 FetchContent 还是离线工作树，均要求：

1. HEAD 等于期望 SHA；
2. 工作树无已跟踪或未跟踪改动；
3. 预先存在的 UbDiag::ubdiag_lib 目标必须由当前 Mooncake 构建树创建；
4. UbDiag 二进制目录携带源码提交标记，来源变化时仅重建该依赖目录。

两层编译

模式	CMake 选项	编译行为	RPM 内容
Layer 0	MOONCAKE_ENABLE_UBDIAG=OFF	头文件 + UBDIAG_DISABLE 空实现	不含 UbDiag CLI/库/配置
Layer 1	MOONCAKE_ENABLE_UBDIAG=ON	同源构建 shared SDK、CLI、P99、PerfLog	Mooncake + CLI + libubdiag.so.0.6.0 + 配置 + provenance

打包信任链

CMake 生成结构化 manifest，RPM 脚本只解析允许字段，并仅从当前 BUILD_DIR/_deps/ubdiag-build 取产物。打包时再次核验源码 SHA、工作树、构建标记、CLI 对动态库的 NEEDED、应用消费者、暂存文件一致性和最终 RPATH。Layer 0 反向拒绝任何 UbDiag 文件或链接依赖。

用户接口

MOONCAKE_ENABLE_UBDIAG 是唯一模式开关；MOONCAKE_UBDIAG_SOURCE_DIR 支持离线洁净 Git 工作树。详细命令与运行方式见 docs/ubdiag_integration_guide.md，架构与实现见 docs/mooncake_ubdiag_two_layer_technical_delivery.md。

兼容性与影响

• 默认模式继续保持零 UbDiag 运行时依赖。
• Layer 1 增加 UbDiag 编译时间、RPM 体积和共享内存运行需求。
• 构建机必须可获得精确 UbDiag Git 对象；离线目录必须保留 Git 元数据。
• 出包机与运行机可以不同，来源证明约束的是打包进 RPM 的产物。
• 不引入系统 UbDiag fallback，避免不受控版本被装入 RPM。

验证

已完成：

• Layer 0/Layer 1 配置、编译和同一构建根切换；
• 错误 SHA、脏源码、伪造 CMake target、篡改构建标记、系统假 UbDiag 干扰等负向门禁；
• AArch64 双节点真实 UB write/read benchmark；
• UbDiag summary/detail/P99/PerfLog/raw table/watch/history 与 6 类 CSV 导出；
• Layer 0/Layer 1 单 RPM 内容、精确提交、CLI/库 SHA256、消费者链接和 RPATH/RUNPATH 校验。

非目标

• 不提供或消费客户系统 UbDiag 包；
• 不在运行时切换 Layer 0/Layer 1；模式在编译和出包阶段确定；
• 不在本 RFC 中修改 Mooncake 业务埋点语义。

Before submitting a new issue...

• Make sure you already searched for relevant issues and read the documentation

[github-actions]

Thanks for opening this issue, @qinyufei63!

Field	Value
Issue	#15
GitHub user ID	287730107
Reporter	@qinyufei63

A maintainer will triage this when possible. To help us respond faster, please include:

• Mooncake version or commit SHA
• Environment (OS, CUDA/driver, RDMA stack if relevant)
• Steps to reproduce and expected vs. actual behavior

Useful links: Documentation · Contributing guide

This message was posted automatically by the issue bot.

[qinyufei63]

PR #13 已完成合并，merge commit 为 e42c08c344bbcd0559c354b65c419078f3907552。

最终交付已按评审后的边界落地：

• Layer 0 默认使用固定 UbDiag 源码头文件与 UBDIAG_DISABLE 空实现，不链接或打包 UbDiag 运行时；
• Layer 1 使用系统 UbDiag RPM 提供的共享库、CMake SDK 和同安装前缀 CLI，并校验 CLI/共享库的 VERSION-RELEASE.ARCH 一致；
• Layer 0 与 Layer 1 均生成单一 Mooncake RPM，Layer 1 RPM 同时携带所选 CLI、libubdiag.so* 和可选配置；
• AArch64 双节点真实 UB、PerfPoint/P99/PerfLog、六类 CSV、L0/L1 RPM 出包及隔离回装均已通过。

本 RFC 的交付目标已由 PR #13 完成。原 RFC 中“Layer 1 通过 FetchContent 同源构建”的早期方案已被最终的“消费系统 UbDiag RPM”方案取代，具体实现以已合并代码和用户指南为准，因此按 completed 关闭。