调试工作流程¶

本文引用的文件 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/oom_debugging.md - docs/error_codes.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

目录¶

引言
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考量
故障排查指南
结论
附录

引言¶

本指南面向使用 XLA 的开发者与工程师，提供从问题发现到根因定位与修复闭环的系统化调试流程。内容覆盖问题分类、信息收集、假设验证、工具选择策略、日志与错误处理、以及调试报告的标准化记录方法。文档同时给出针对不同问题类型的工具组合建议（如 HLO Dump、多机 HLO 运行器、XProf 等），并总结常见错误码与错误来源，帮助快速定位瓶颈与异常。

项目结构¶

围绕调试主题，仓库中与之直接相关的核心文档与源码模块如下： - 文档层：调试工作流、工具与 HLO Dump、OOM 调试、错误码与概览 - 源码层：错误检查与致命错误处理、调试选项标志解析、状态宏与错误传播

graph TB
subgraph "文档"
DW["调试工作流<br/>docs/megascale/debugging_workflow.md"]
TOOLS["工具与命令行工具<br/>docs/tools.md"]
HDUMP["HLO Dump 使用指南<br/>docs/hlo_dumps.md"]
OOM["OOM 调试与 XProf<br/>docs/oom_debugging.md"]
EC["错误码索引<br/>docs/error_codes.md"]
EO["错误概览与分类<br/>docs/errors_overview.md"]
end
subgraph "源码"
CHK["XLA_CHECK 宏与断言<br/>xla/error/check.h"]
FES["致命错误 Sink<br/>xla/error/fatal_error_sink.h"]
DOF["调试选项标志解析<br/>xla/debug_options_flags.h"]
SM["状态宏与错误传播<br/>xla/status_macros.h"]
end
DW --> TOOLS
DW --> HDUMP
DW --> OOM
DW --> EC
DW --> EO
TOOLS --> HDUMP
TOOLS --> OOM
EO --> EC
EO --> CHK
EO --> FES
EO --> DOF
EO --> SM

图表来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/oom_debugging.md - docs/error_codes.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

章节来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/oom_debugging.md - docs/error_codes.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

核心组件¶

调试工作流（Megascale）：提供挂起、性能、落后节点等场景的诊断步骤与日志定位要点。
工具与命令行工具：涵盖 HLO 运行、多机运行、HLO 优化与格式转换、PTX 编译、HLO 隔离等工具链。
HLO Dump：统一的 HLO 输出机制，支持文本、Proto、快照、可视化等多种格式，并可按编译阶段筛选输出。
OOM 调试：结合 XProf Memory Viewer 定位峰值内存与热点算子。
错误码与错误概览：对运行时与编译时错误进行分类与索引；解释 Status 与 CHECK 失败的区别及处理方式。
错误检查与致命错误 Sink：提供 XLA_CHECK/QCHECK/DHECK 宏与致命错误上下文增强。
调试选项标志：通过 XLA_FLAGS/环境变量注入调试行为，支持重置默认值、燃料控制等。

章节来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/oom_debugging.md - docs/error_codes.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

架构总览¶

下图展示从“问题发现”到“修复闭环”的端到端流程，以及与工具与文档的对应关系：

flowchart TD
A["问题发现<br/>日志/指标/崩溃"] --> B["问题分类<br/>运行时/编译时/性能/挂起"]
B --> C["信息收集<br/>HLO Dump/多机运行/快照/XProf"]
C --> D["假设验证<br/>对比基准/隔离最小化/Pass 测试"]
D --> E["根因定位<br/>错误码/错误来源/致命错误上下文"]
E --> F["修复与回归验证<br/>回滚/参数调整/补丁提交"]
F --> G["报告归档<br/>问题描述/重现步骤/分析过程/方案"]
C --> |HLO Dump| H["HLO Dump 使用指南"]
C --> |多机/SPMD| I["工具与命令行工具"]
C --> |OOM 分析| J["OOM 调试与 XProf"]
E --> |错误码/概览| K["错误码索引与概览"]
E --> |错误检查| L["XLA_CHECK/QCHECK/DHECK"]
E --> |致命错误| M["致命错误 Sink"]
E --> |调试选项| N["调试选项标志解析"]

图表来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/oom_debugging.md - docs/error_codes.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

详细组件分析¶

组件一：调试工作流（Megascale）¶

挂起问题定位：通过“Megascale 检测到挂起”类日志，区分坏芯片、网络问题、模块不一致、HLO 指纹不匹配、数据输入停滞、不可恢复错误与未知错误等场景。
性能问题定位：获取 XProf 会话，检查 DMA 映射、零拷贝通信、网络延迟与带宽、Collective Slack 等。
工具配合：HLO Dump、多机 HLO 运行器、网络分析 Notebook、XProf Memory Viewer。

flowchart TD
S["开始"] --> E1["检测挂起错误"]
E1 --> C1{"根因分类"}
C1 --> |坏 TPU 芯片| R1["避免该主机/重启/联系团队"]
C1 --> |网络问题| R2["检查底层网络/定位故障链路"]
C1 --> |模块不一致| R3["确认所有 Worker 运行相同程序/检查指纹"]
C1 --> |HLO 指纹不匹配| R4["收集 HLO Dump 并交叉比对"]
C1 --> |数据输入停滞| R5["确认数据源可达/解析正确/无读取限速"]
C1 --> |不可恢复错误| R6["查看具体错误日志并针对性修复"]
C1 --> |未知错误| R7["全量摘要分析"]
R1 --> P["性能分析<br/>XProf/Memory Viewer/网络分析"]
R2 --> P
R3 --> P
R4 --> P
R5 --> P
R6 --> P
R7 --> P
P --> F["修复与验证"]

图表来源 - docs/megascale/debugging_workflow.md

章节来源 - docs/megascale/debugging_workflow.md

组件二：工具与命令行工具¶

HLO 运行与多机运行：run_hlo_module、multihost_hlo_runner 支持平台选择、参考实现对比、SPMD 与跨主机通信。
HLO 优化与格式转换：hlo-opt 支持多阶段输出（HLO/LLVM/Triton/PTX）、设备无关与设备模式、Pass 注册与自定义流水线。
PTX 编译：ptx-opt 将 LLVMIR 优化后生成 PTX，并可导出中间 IR。
HLO 隔离：isolate_hlo 提取单条指令及其上下文，便于最小化复现。

sequenceDiagram
participant Dev as "开发者"
participant Tool as "命令行工具"
participant Backend as "目标后端"
participant Ref as "参考实现"
Dev->>Tool : 选择平台/Pass/输出阶段
Tool->>Backend : 编译/运行/对比
Backend-->>Tool : 中间产物/结果
Tool-->>Dev : 文本/Proto/HTML 可视化
Dev->>Ref : 对比参考实现/定位差异

图表来源 - docs/tools.md

章节来源 - docs/tools.md

组件三：HLO Dump 配置与分析¶

环境变量与程序化接口：通过 XLA_FLAGS 或 JAX 接口在本地/Colab 环境中启用 HLO Dump，支持文本、Proto、快照、Graphviz URL/HTML 等格式。
按 Pass 过滤：使用正则表达式筛选特定阶段（如 SPMD/传播）以减少输出规模。
复现实验：使用 run_hlo_module 在 CPU/GPU 后端上用伪数据或快照数据重放，加速迭代。

flowchart TD
A["设置 XLA_FLAGS/JAX 参数"] --> B["触发编译/执行"]
B --> C{"选择输出格式"}
C --> |文本| D["before_optimizations/after_optimizations"]
C --> |Proto| E["HloProto/HloSnapshot"]
C --> |可视化| F["Graphviz URL/HTML"]
D --> G["按 Pass 过滤/命名定位"]
E --> G
F --> G
G --> H["run_hlo_module 重放/对比"]

图表来源 - docs/hlo_dumps.md

章节来源 - docs/hlo_dumps.md

组件四：OOM 调试与 XProf¶

使用 jax.profiler.trace 捕获 Profile，启动 XProf 并打开 Memory Viewer，聚焦 HBM 峰值与热点算子。
结合错误概览中的资源耗尽错误类型，定位输入/中间/输出张量的异常尺寸与布局。

sequenceDiagram
participant Prog as "示例程序"
participant Prof as "Profiler"
participant XProf as "XProf"
participant MV as "Memory Viewer"
Prog->>Prof : 开始/停止 Trace
Prof-->>Prog : 生成日志目录
Prog->>XProf : 指定日志目录与端口
XProf->>MV : 加载并展示内存视图
MV-->>Prog : 峰值点与热点算子

图表来源 - docs/oom_debugging.md

章节来源 - docs/oom_debugging.md

组件五：错误处理与异常捕获¶

错误来源与分类：Status（可恢复）与 CHECK 失败（致命）两类路径，分别用于用户输入校验与内部不变式破坏。
错误码索引：按运行时/编译时分类，便于快速映射与检索。
XLA_CHECK/QCHECK/DHECK 宏：提供与 Abseil CHECK 兼容的 API，附加错误码与 DebugMe 上下文，便于定位。
致命错误 Sink：作为 absl::LogSink 的扩展，为致命错误附加额外调试上下文。
调试选项标志：通过 XLA_FLAGS/环境变量注入调试行为，支持重置默认值、Pass 燃料控制等。

classDiagram
class XLA_CHECK {
+断言失败时输出错误码与链接
+附加 DebugMeContext
}
class XLA_QCHECK {
+非堆栈/非注册处理器
+适用于输入校验
}
class XLA_DCHECK {
+仅调试模式
+不安全依赖求值
}
class FatalErrorSink {
+拦截 FATAL 日志
+附加 XLA 上下文
}
class DebugOptionsFlags {
+解析 XLA_FLAGS
+重置默认值
+Pass 燃料控制
}
class StatusMacros {
+Status 返回与传播
+错误消息拼接
}
XLA_CHECK --> FatalErrorSink : "致命错误增强"
XLA_CHECK --> DebugOptionsFlags : "受调试标志影响"
XLA_QCHECK --> DebugOptionsFlags
XLA_DCHECK --> DebugOptionsFlags
StatusMacros --> DebugOptionsFlags : "日志级别/过滤"

图表来源 - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

章节来源 - docs/errors_overview.md - docs/error_codes.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

依赖关系分析¶

文档间依赖：调试工作流依赖工具与 HLO Dump；OOM 调试依赖 XProf；错误概览与错误码为定位提供索引。
源码间依赖：错误宏与致命错误 Sink 为日志与错误处理提供统一入口；调试选项标志贯穿编译/运行期的调试行为注入。

graph LR
DW["调试工作流"] --> TOOLS["工具与命令行工具"]
DW --> HDUMP["HLO Dump"]
DW --> OOM["OOM 调试"]
EO["错误概览"] --> EC["错误码索引"]
EO --> CHK["XLA_CHECK/QCHECK/DHECK"]
EO --> FES["致命错误 Sink"]
EO --> DOF["调试选项标志"]
EO --> SM["状态宏"]

图表来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/oom_debugging.md - docs/error_codes.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

章节来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/oom_debugging.md - docs/error_codes.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

性能考量¶

通过 XProf 获取通信/计算/内存层面的时序与占用，识别带宽受限、RPC 延迟尾部、Collective Slack 过小等问题。
利用 HLO Dump 与多机运行器验证 SPMD 语义一致性，避免模块不一致导致的性能退化。
使用 OOM 调试定位峰值内存热点，结合 Memory Viewer 评估输入/中间/输出张量的形状与布局优化空间。

章节来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/oom_debugging.md

故障排查指南¶

通用步骤
快速定位：依据日志中的“Megascale 检测到挂起/不可恢复错误/未知错误”等关键字，进入对应章节。
证据收集：开启 HLO Dump（文本/Proto/快照），必要时启用 vmodule/verbose 选项；收集 XProf 与网络分析。
假设验证：对比多机/多设备结果，隔离最小化 HLO，运行单个 Pass 观察行为变化。
修复确认：回滚参数/补丁，重复验证；记录变更与效果。
工具选择策略
编译/运行一致性：run_hlo_module 与 multihost_hlo_runner。
编译管线观测：hlo-opt（阶段切换/Pass 执行/格式转换）。
设备无关/设备相关：ptx-opt（LLVMIR->PTX）。
最小化复现：isolate_hlo。
日志与错误处理
设置合适的日志级别与过滤（参考调试选项标志与环境变量）。
使用 XLA_CHECK/QCHECK/DHECK 宏在关键路径输出上下文信息。
致命错误由 FatalErrorSink 拦截并附加 XLA 上下文，便于根因分析。

章节来源 - docs/megascale/debugging_workflow.md - docs/tools.md - docs/hlo_dumps.md - docs/errors_overview.md - xla/error/check.h - xla/error/fatal_error_sink.h - xla/debug_options_flags.h - xla/status_macros.h

结论¶

本指南将调试流程结构化为“问题发现—分类—信息收集—假设验证—根因定位—修复—报告归档”的闭环，并配套工具链与错误处理机制，帮助在复杂异构环境中快速收敛问题。建议在日常开发中固化 HLO Dump 与 XProf 的使用习惯，建立最小化复现与对比实验的标准流程，以提升问题定位效率与修复质量。

附录¶

调试报告模板（建议字段）
问题描述：现象、时间窗口、影响范围
重现步骤：最小可复现脚本/命令、环境与版本
采集证据：HLO Dump/Proto/快照、XProf、网络分析、日志片段
分析过程：Pass 过滤/对比/隔离、错误码与来源定位
解决方案：参数调整/代码修复/回滚策略、验证结果
后续建议：回归测试、监控告警、文档更新