PyTorch 可配置日志系统 torch._logging 完全指南TORCH_LOGS 与 set_logs 实战与源码剖析【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorchPyTorch 内置了一套可配置的日志系统模块名为torch._logging允许对 Dynamo、AOTAutograd、Inductor、Distributed 等不同组件分别设置独立的日志级别既能完全静默某个组件也能把另一个组件的日志开到最大详细程度。本文以官方文档 docs/source/logging.md 为主体结合 torch/_logging/_internal.py、torch/_logging/_registrations.py 等源码系统讲解TORCH_LOGS环境变量与torch._logging.set_logsPython API 两种配置方式、全部组件与制品artifact清单、日志格式与输出控制以及底层注册与初始化机制帮助你精准定位torch.compile编译链路中的各类问题。一、系统概览组件Component与制品Artifacttorch._logging将日志分为两个抽象层次组件Component一组相关功能模块的集合。每个组件拥有一个日志级别默认均为logging.WARN。例如dynamo组件对应torch._dynamo及其子模块inductor组件对应torch._inductor。制品Artifact与组件关联的特定调试信息只存在开启/关闭两种状态默认均为False。例如aot_graphs制品会打印 AOTDispatch 切分后的 FX 前向/反向图。制品用或-前缀修饰是无效操作no-op因为它们是开关而非级别。两者关系开启某个组件通常会连带开启其关联制品除非该制品被标记为off_by_default。这类制品过于啰嗦只有被显式点名时才会输出该选项定义于_registrations.py中。系统的两种配置入口完全等价环境变量TORCH_LOGS适合命令行一次性开启Python APItorch._logging.set_logs适合在脚本/notebook 中按需开启。该功能目前处于 **beta** 阶段未来可能发生破坏性变更同时它**尚未覆盖 PyTorch 所有组件**的日志输出。二、通过 TORCH_LOGS 环境变量配置TORCH_LOGS是一个逗号分隔的[-]component列表其中component是下文列出的组件名。前缀规则前缀语义效果降低组件的日志级别显示更多日志等价logging.DEBUG-提高组件的日志级别显示更少日志等价logging.ERROR无前缀保持默认等价logging.INFO默认行为即组件未被列出时的表现。这一前缀解析逻辑可以在源码 torch/_logging/_internal.py 的get_name_level_pair中得到印证if name[0] INCR_VERBOSITY_CHAR: # level logging.DEBUG elif name[0] DECR_VERBOSITY_CHAR: # - level logging.ERROR else: level logging.INFO完整解析流程位于_parse_log_settingstorch/_logging/_internal.py先去除空白、按逗号切分再对每个名字判定是已注册日志、已注册制品还是可导入的模块名此时会通过_get_module_and_submodules递归展开该模块及其全部子模块实现目录式批量设置。注意该函数带functools.lru_cache装饰同一字符串只解析一次。2.1 环境变量的特殊值help 与 helpTORCH_LOGShelp抛出包含可见制品列表与示例的ValueError相当于内置帮助TORCH_LOGShelp输出全部已注册名字含内部制品对应源码help_message(verboseTrue)torch/_logging/_internal.py非法输入会给出_invalid_settings_err_msg提示列出所有合法设置项。2.2 目录式日志directory-based loggingTORCH_LOGS还接受任意完整限定模块名fully qualified name把该模块及其所有子模块的日志级别一并设置。官方示例TORCH_LOGStorch._functorch._aot_autograd会将torch._functorch._aot_autograd及其全部子模块设为DEBUG。这与set_logs(modules{...})中为未注册模块设置级别是同一套机制。2.3 Windows 环境变量引号处理Windows 的cmd/PowerShell在传递环境变量时会自动加上外层引号导致值形如schedule,inductor,output_code。为此源码提供了process_env_var_string_for_windowstorch/_logging/_internal.py在sys.platform win32时自动剥除首尾成对出现的或。三、组件Components完整清单所有组件默认级别均为logging.WARN。下表汇总文档列出的全部组件并补充了源码_registrations.py中登记的对应 Python 模块映射组件名说明底层注册的日志模块节选all特殊组件配置所有组件的默认级别映射到torchaotAOTAutograd 组件torch._functorch.aot_autograd、torch._functorch._aot_autogradasync_compileInductor 异步编译 workertorch._inductor.async_compile、torch._inductor.compile_worker.tracked_process_poolautogradautograd 组件torch.autogradc10dPyTorch Distributed 中的 c10d 通信操作torch.distributed.distributed_c10d、torch.distributed.rendezvouscacheInductor 缓存组件torch._inductor.remote_cache、torch._inductor.fb.remote_cacheddpDistributedDataParallel组件torch.nn.parallel.distributed、torch._dynamo.backends.distributeddistributedPyTorch Distributed 组件torch.distributed、torch._dynamo.backends.distributed、torch.nn.parallel.distributeddtensorDTensor组件torch.distributed._tensor、torch.distributed.tensordynamic动态形状dynamic shapes组件torch.fx.experimental.symbolic_shapes、torch.fx.experimental.sym_node、torch.fx.experimental.recordingdynamoTorchDynamo 组件torch._dynamo及DYNAMIC所列模块exportexport 组件torch.export、torch.export.dynamic_shapes、torch._export.*等fake_tensorFakeTensor 组件torch._subclasses.fake_tensorfsdpFullyShardedDataParallel组件torch.distributed.fsdp、torch.distributed._composable.fsdpinductorTorchInductor 组件torch._inductor、torch._inductor.cudagraph_treesnative_dslnative DSL 组件torch._nativeonnxONNX 导出器组件torch.onnxpp分布式流水线pipelining组件torch.distributed.pipeliningtorch顶层torch组件torchyour.custom.module任意未注册模块提供完整限定名后启用如some.random.module上述模块映射均可在 torch/_logging/_registrations.py 中找到对应register_log调用该文件是短别名 → logger 限定名的唯一事实来源。四、制品Artifacts完整清单与 off_by_default 语义制品默认状态为False。标记为 off by default 的制品仅靠提高其父组件的日志级别不会开启必须显式点名。例如把inductor组件设为DEBUGoutput_code制品依然不会输出除非在设置中显式写出output_code。制品名输出内容off by defaultaot_graphsAOTDispatch 切分后生成的 FX 前向/反向图否aot_graphs_effectsAOTDispatch 生成的 FX 图用于调试 effects 处理否aot_joint_graphAOTAutograd 生成的 joint 前向-反向联合图切分前否annotation在图节点上创建注解的详细步骤是autotuning_inputs自动调优期间每个 kernel 的输入张量 shape/dtype/strides是autotuning自动调优选择kernel 源码、性能、调优参数是auto_chunkerauto chunker 相关日志是benchmarkingInductor 详细的基准测试信息是bytecodeDynamo 原始及修改后的字节码是cachingInductor 详细的缓存信息是compiled_autogradcompiled autograd 日志含图否compiled_autograd_verbosecompiled autograd 日志并附带 C 信息如 autograd 节点 → FX 节点映射是compute_dependenciesInductor 计算依赖信息是cudagraphsInductor 生成代码包装 CUDA graph 的信息否cudagraph_static_inputsDynamo、AOT、CUDA graph 中的静态输入处理是ddp_graphsDDPOptimizer 为提前触发通信而切分图后生成的每张子图否fusionInductor 详细的融合决策是graphDynamo 追踪得到的图AOTDispatch 之前表格格式否graph_breaksDynamo 决定需要 graph break 的时刻否graph_codeDynamo 追踪图的 Python 代码否graph_code_verbose详尽的 FX pass 日志如tensorify_python_scalars、runtime_assert否graph_region_expansion重复图区域追踪器duplicate graph region tracker扩展算法的详细步骤是graph_sizesDynamo 图中所有 FX 节点的大小否guards每个被编译 Dynamo frame 的 guards否hierarchical_compile分层编译hierarchical compilation调试信息是incremental增量自动调优信息是inductor_metricsInductor 指标如num_bytes、nodes_num_elem、node_runtimes是ir_post_fusionInductor 融合 pass 之后的 IR是ir_pre_fusionInductor 融合 pass 之前的 IR是kernel_codeInductor 逐 kernel 生成的代码是loop_ordering循环重排loop ordering相关日志是loop_tiling循环分块loop tiling相关日志是node_runtime_estimation编译期优化决策所需的节点运行时间估计是not_implementedmulti-dispatch 返回NotImplemented时的日志消息否onnx_diagnosticsONNX 导出器诊断日志是output_codeInductor 生成的最终代码Triton 或 C是overlapInductor 计算/通信重叠决策是overlap_schedulingInductor 重叠调度 pass 信息是perf_hintsInductor 性能提示是post_grad_graphsInductor post-grad passes 之后生成的 FX 图否pre_grad_graphsInductor pre-grad passes 之前的 FX 图否recompilesDynamo 重编译图的原因否recompiles_verbose重编译期间失败的全部 guard 检查含未真正运行的是scheduleInductor 调度器信息是side_effectsDynamo 代码生成产生的副作用变量、属性、cell、全局变量的变更否sym_node各类SymNode操作的额外信息是trace_bytecodeDynamo 追踪字节码时的指令与当前栈否trace_call可用时打印逐表达式追踪细节否trace_shape_events为回放而记录的每个ShapeEnv操作的追踪是trace_sourceDynamo 执行字节码时打印文件名、行号与源码否verbose_guards详尽的 guard 信息是从源码 torch/_logging/_registrations.py 可以看到制品的注册形态例如register_artifact( output_code, Prints the code that Inductor generates (either Triton or C), off_by_defaultTrue, visibleTrue, ) register_artifact( recompiles, Prints the reason why we recompiled a graph. Very, very useful., visibleTrue, )其中visibleTrue的制品会出现在TORCH_LOGShelp的默认提示里off_by_defaultTrue则进入off_by_default_artifact_names集合torch/_logging/_internal.py。此外源码中还登记了partitioned_scatter、native_dsl_compile等制品以及测试专用的custom_format_test_artifact文档注明内部测试专用制品已省略。4.1 制品在代码中如何被输出制品日志并非通过普通logging.getLogger输出而是调用getArtifactLogger(module_qname, artifact_name)torch/_logging/_internal.py获取一个命名为module.__artifact_name的特殊 logger。其关键行为若制品off_by_default且未被显式开启设置log.propagate False防止日志冒泡到祖先 logger 被顺带打印若制品被显式开启则setLevel(logging.DEBUG)并恢复propagate True。这也是显式点名才输出语义的代码实现基础。torch/_logging/__init__.py的开头注释torch/_logging/init.py给出了接入指引先在_registrations.py注册模块/制品再在日志点调用getArtifactLogger。五、Python APItorch._logging.set_logsset_logstorch/_logging/_internal.py是 Python 侧的配置入口以关键字参数形式支持上述全部组件与制品import logging import torch._logging # 将 dynamo 组件设为 DEBUG并开启 graph_code 制品 torch._logging.set_logs(dynamologging.DEBUG, graph_codeTrue) # 为未注册的任意模块设置级别 torch._logging.set_logs(modules{unregistered.module.name: logging.DEBUG})关键语义与文档、docstring 一致组件参数all、dynamo、aot、autograd、inductor、dynamic、distributed、c10d、ddp、fsdp、dtensor、onnx、export等接受日志级别整数默认logging.WARN制品参数bytecode、aot_graphs、graph、guards、recompiles、output_code、schedule、fusion、overlap、sym_node等接受布尔值默认Falsemodules字典参数以完整限定模块名为 key、级别为 value用于两种场景——(1) 新增了尚未在此函数中添加关键字参数的组件/制品(2) 为未注册模块设置级别。它是把新注册项快速接入现有 API 的扩展点。优先级规则源码第 497-501 行明确实现TORCH_LOGS环境变量对set_logs具有完全优先权——若环境变量已设置调用set_logs会打印警告Using TORCH_LOGS environment variable for log settings, ignoring call to set_logs并直接返回。参数校验也很严格制品若收到非布尔值会抛ValueErrorExpected bool to enable artifact日志级别不在logging._levelToName中会抛ValueError并列出合法级别无法识别的名字会抛ValueError提示可用项。DEFAULT_LOGGINGtorch/_logging/_internal.py还预置了一套建议组合如dynamo/aot/inductor为INFO开启graph_breaks、guards、recompiles等可用于set_logs(**torch._logging.DEFAULT_LOGGING)快速启动。六、官方示例速查文档末尾给出五个典型示例逐一说明命令效果TORCH_LOGSdynamo,aotTorchDynamo 设为DEBUGAOT 设为INFOTORCH_LOGS-dynamo,inductorTorchDynamo 设为ERRORTorchInductor 设为DEBUGTORCH_LOGSaot_graphs开启aot_graphs制品TORCH_LOGSdynamo,scheduleTorchDynamo 设为DEBUG并开启schedule制品TORCH_LOGSsome.random.module,schedulesome.random.module设为DEBUG并开启schedule制品其中无前缀即 INFO与源码get_name_level_pair的默认分支一致见上文。Python 侧等价写法torch._logging.set_logs(dynamologging.DEBUG, aotlogging.INFO) torch._logging.set_logs(dynamologging.ERROR, inductorlogging.DEBUG) torch._logging.set_logs(aot_graphsTrue) torch._logging.set_logs(dynamologging.DEBUG, scheduleTrue) torch._logging.set_logs(modules{some.random.module: logging.DEBUG}, scheduleTrue)七、进阶日志格式与输出目标除TORCH_LOGS外源码 torch/_logging/_internal.py 还定义了多个配套环境变量环境变量作用TORCH_LOGS_FORMAT自定义日志输出格式例如TORCH_LOGS_FORMAT%(levelname)s: %(message)s合法 key 包括levelname、message、pathname、levelno、lineno、filename、name特殊值short/basic映射到 Python 内置logging.BASIC_FORMATTORCH_LOGS_OUT将日志同时输出到文件例如TORCH_LOGS_OUT/tmp/output.txt适合输出较长时使用_init_logs会在读取后追加一个FileHandlerTORCH_TRACE结构化 trace 日志的目录配合 tlparse 生成编译报告TORCH_DTRACE更详细的调试追踪可能显著拖慢程序开启后GET_DTRACE_STRUCTURED True结构化记录会写入指定目录TORCH_LOGS_TRACE_ID_FILTER按 trace id 过滤输出的 trace 日志在默认未设置TORCH_LOGS_FORMAT时日志由自定义的TorchLogsFormattertorch/_logging/_internal.py格式化行首包含进程 rank 前缀如[rank0]:在dist.is_initialized()时输出、glog 风格级别缩写DEBUG→V、INFO→I、WARNING→W、ERROR→E、CRITICAL→C、时间戳、进程号、相对模块路径与行号、trace id 以及制品前缀[__artifact_name]便于在大规模分布式日志中快速筛选。_init_logstorch/_logging/_internal.py是整套系统的装配入口流程为先_reset_logs将所有已注册 logger 重置组件恢复WARNING且propagateFalse制品恢复NOTSET且propagateTrue再从环境变量更新log_state随后为每个注册 logger 挂载_StderrHandler跟随当前sys.stderr兼容测试捕获场景见 torch/_logging/_internal.py若设置了TORCH_LOGS_OUT则追加文件 handler最后配置各制品 logger 并初始化结构化 trace handler。八、典型排查场景torch._logging的常见用途是调试torch.compile编译链路以下组合覆盖最频繁的需求重编译recompilation问题TORCH_LOGSrecompiles打印每次重编译的原因需要查看全部失败的 guard 检查时叠加recompiles_verboseoff by default需显式开启。查看 Dynamo 捕获的图TORCH_LOGSgraph表格格式或graph_codePython 代码格式graph_sizes查看节点张量大小trace_source对照源码逐行定位。graph break 定位TORCH_LOGSgraph_breaks打印 Dynamo 决定切图的位置是分析torch.compile性能瓶颈的第一手信息。AOTAutograd 图TORCH_LOGSaot_graphs查看切分后的前向/反向图aot_joint_graph查看切分前的联合图。Inductor 生成代码TORCH_LOGSinductor,output_code,kernel_code同时提高 Inductor 级别并输出最终 Triton/C 代码schedule、fusion、ir_pre_fusion/ir_post_fusion用于深入编译器内部决策。配合TORCH_LOGS_OUT可将这些冗长输出重定向到文件避免刷屏TORCH_LOGSdynamo,graph_breaks,recompiles,aot_graphs,output_code \ TORCH_LOGS_OUT/tmp/compile_debug.log python train.py九、注意事项与限制该功能处于beta阶段配置项名称、语义可能在后续版本调整目前未覆盖 PyTorch 全部组件的日志若某个模块没有对应注册可借助your.custom.module/modules机制传入完整限定模块名临时启用TORCH_LOGS环境变量的优先级高于set_logs调用混用两者时以环境变量为准源码会忽略set_logs并打印提示部分制品compiled_autograd_verbose、autotuning_inputs、trace_shape_events等会带来明显性能开销官方文档注明off by default正是为了默认避免这类高开销输出仅在显式调试时开启。十、源码延伸阅读配置入口与全部实现torch/_logging/_internal.py重点set_logsL211、_parse_log_settingsL807、_init_logsL1166、TorchLogsFormatterL958、getArtifactLoggerL643组件与制品的注册清单torch/_logging/_registrations.py模块对外导出与接入指引torch/_logging/init.py官方文档原文docs/source/logging.md配套观测工具结构化 trace / tlparse介绍见 docs/source/user_guide/torch_compiler/compile/programming_model.observability.md掌握上述组件、制品与两条配置链路后你便可以在不修改任何代码的前提下对 PyTorch 编译栈的任意环节按需调音快速定位 graph break、重编译、算子融合与 kernel 生成等深层问题。【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考