tlparse / TORCH_TRACE

创建时间: 2025年7月29日 | 最后更新时间: 2025年7月29日

tlparse / TORCH_TRACE 是一对工具，它们会生成看起来 像这样 的编译报告。

收集 trace 相当直接。要收集 trace，像这样运行你的模型：

TORCH_TRACE="/tmp/tracedir" python foo.py
pip install tlparse
tlparse /tmp/tracedir

即使你在运行分布式作业，这种方法也同样适用，为每个 rank 提供一个 trace。它会打开你的浏览器，显示与上面生成的 HTML 类似的 HTML。如果你在为某个复杂的、你无法独立复现的问题提交 bug 报告，通过附加在 /tmp/tracedir 中生成的 trace 日志，你仍然可以极大地帮助 PyTorch 开发者。

警告

trace 日志包含你所有的模型代码。如果模型是敏感的，请不要共享 trace 日志。trace 日志不包含权重。

tlparse 的输出主要面向 PyTorch 开发者，并且日志格式易于上传和在 GitHub 上共享。然而，即使你不是 PyTorch 开发者，你仍然可以从中提取有用的信息。我们建议从报告中的内联帮助文本开始，它解释了其内容。以下是你从 tlparse 中可以获得的一些见解：

• 通过查看堆栈树，了解了哪些模型代码被编译了？如果你不熟悉被编译的代码库，这一点尤其有用！

• 有多少个图中断/独立的编译区域？（每个独立的编译区域都是一个着色的块，例如 [0/0]）。潜在图中断的帧是浅绿色 [2/4]。如果有很多帧，这可能令人怀疑，并表明你的代码与 torch.compile 不太匹配。

• 我重新编译了一个特定帧多少次？重新编译了很多次的帧会看起来像：[10/0] [10/1] [10/2] - 如果某个东西被重新编译了很多次，这非常可疑，值得深入研究，即使它不是你问题的根源。

• 是否存在编译错误？发生错误的帧会看起来像 [0/1]。

• 我为给定帧生成了哪些中间编译器产品？例如，你可以查看生成的顶级 FX 图或生成的 Triton 代码。

• 特定帧是否有相关信息？你可以在 compilation_metrics 中找到它们。

TORCH_LOGS

你可以使用 TORCH_LOGS 环境变量选择性地启用 torch.compile 堆栈的某些部分进行日志记录。 TORCH_LOGS 实际上是 tlparse 日志的来源。 TORCH_LOGS 环境变量的格式如下：

TORCH_LOGS="<option1>,<option2>,..." python foo.py

你也可以通过编程方式使用 torch._logging.set_logs 设置日志选项。

import logging
torch._logging.set_logs(graph_breaks=True, dynamic=logging.DEBUG)

最有用的选项是：

• graph_breaks：记录用户代码中图中断的位置以及图中断的原因。

• guards：记录生成的 guard。

• recompiles：记录哪个函数被重新编译以及导致重新编译的失败 guard。

• dynamic：记录与动态形状相关的日志。

• output_code：记录 Inductor 生成的代码。

一些更有用的 TORCH_LOGS 选项包括：

选项	描述
+all	输出所有 torch.compile 组件的调试日志。
+dynamo	输出 TorchDynamo 的调试日志。
+aot	输出 AOTAutograd 的调试日志。
+inductor	输出 TorchInductor 的调试日志。
dynamic	输出动态形状相关的日志。
graph_code	输出 Dynamo 生成的 FX 图的 Python 代码。
graph_sizes	输出 Dynamo 生成的 FX 图的张量大小。
trace_bytecode	输出 Dynamo 正在追踪的字节码指令以及 Dynamo 正在跟踪的符号解释器堆栈。
trace_source	输出 Dynamo 当前正在追踪的原始源文件的代码行。
bytecode	输出 Dynamo 生成的字节码。
guards	输出生成的 guard。
recompiles	输出重新编译的原因（仅第一个失败的 guard 检查）。
recompiles_verbose	输出重新编译发生时所有失败的 guard 检查。
aot_graphs	输出 AOTAutograd 生成的图。
aot_joint_graphs	输出 AOTAutograd 生成的联合前向-后向图。
output_code	输出 Inductor 生成的代码。
kernel_code	输出 Inductor 按每个 kernel 生成的代码。
schedule	输出 Inductor 调度日志。
perf_hints	输出 Inductor perf hint 日志。
fusion	输出 Inductor fusion 日志。

有关选项的完整列表，请参阅 torch._logging 和 torch._logging.set_logs。

tlparse 与 TORCH_LOGS 的区别

一般来说，我们建议在遇到问题时首先使用 tlparse。 tlparse 非常适合调试大型模型和获得模型如何被编译的总体概述。另一方面，对于小型示例和需要精细调试细节的情况，当我们已经知道是哪个 torch.compile 组件导致问题时，TORCH_LOGS 是更好的选择。