企业官网建设流程全解析

• CANN
• Ascend
• 人工智能
• 任务调度

导读

trace机制是CANN Runtime提供的一套"内存记录、异常落盘"的维测信息采集方案：程序运行期间，软件栈将维测信息写入内存（避免频繁产生日志文件拖慢业务），仅在程序运行出错或进程结束时才落盘到文件。本文基于 docs/zh/log_ref/viewing_trace_logs.md 系统讲解 trace 日志的落盘路径规则、三类事件（schedule / stackcore / exit）的触发场景、各类日志文件的含义与解析方式，并对照 src/dfx/trace 目录下的实现源码（尤其是 trace_recorder.c）验证目录与文件的生成逻辑，同时给出 ASCEND_WORK_PATH、ASCEND_LOG_DEVICE_FLUSH_TIMEOUT、ASCEND_TRACE_RECORD_NUM 三个关键环境变量的取值范围、默认值与配置示例。阅读完本文，你将能够在 AI Core Error、notify wait 超时、Host 进程崩溃等典型故障场景下，快速定位 trace 日志落盘位置并正确解读其中的维测信息。

trace机制的设计动机：为什么用内存记录而非实时落盘

在AI训练/推理业务中，Runtime、HCCL、AICPU 等软件栈组件在运行时会持续产生大量维测信息。如果全部实时写入磁盘，会产生两个问题：

• 性能劣化：频繁的日志文件创建与 IO 写入会显著拖累业务进程，尤其在高频算子执行场景下；
• 磁盘压力：正常运行期间的日志大多无定位价值，白白消耗磁盘空间。

因此 trace 机制采用"先写内存、按需落盘"的设计：

1. 程序运行过程中，软件栈的维测信息被记录在内存中；
2. 仅当程序运行出错（如算子执行报错）或进程结束（正常退出或崩溃）时，才将内存中的信息落盘到文件。

该机制与常规的应用类日志（docs/zh/log_ref/log_overview.md 中所述$HOME/ascend/log下的 debug/run/security 日志）相互独立、互为补充：常规日志持续记录运行过程，trace 日志则聚焦异常现场与进程生命周期关键节点。

适用前提：当前仅Ascend EP 标准形态支持 trace 功能；RC 形态与 Control CPU 开放形态用户请参阅 docs/zh/log_ref/log_overview.md 中的对应日志查看章节。

落盘路径与目录结构：三级目录的命名规则

根目录与自定义路径

trace 日志落盘根目录默认为：

$HOME/ascend/atrace/

若需要修改落盘位置，可通过环境变量ASCEND_WORK_PATH指定，例如：

export ASCEND_WORK_PATH=/home/test

设置后，trace 日志将落盘到/home/test/ascend/atrace/下（环境变量仅替换$HOME部分，ascend/atrace子路径保持不变）。

三级目录命名规则

trace 日志的完整落盘路径为：

$HOME/ascend/atrace/trace_{进程组pid}_{首次加载trace动态库的进程pid}_{首次加载trace动态库的时间戳}/{event_name}_event_{当前进程pid}_{目录生成时的时间戳}/

各字段含义如下：

| 路径字段 | 含义 | | -- | -- | |trace_{进程组pid}| 进程组 ID（pgid），同一业务进程组内共享 | |{首次加载trace动态库的进程pid}| 进程中首次加载 trace 动态库（atrace 库）的进程 PID | |{首次加载trace动态库的时间戳}| 首次加载 trace 动态库的时间 | |{event_name}| 事件类型，取值为schedule、stackcore、exit| |{当前进程pid}| 当前发生事件/落盘的进程 PID | |{目录生成时的时间戳}| 该事件目录创建的时间 |

其中event_name（事件类型）的三种取值含义为：

• schedule：业务流程异常，例如算子执行报错、notify wait 超时等；
• stackcore：进程崩溃或收到异常信号；
• exit：进程正常退出析构。

源码验证：目录与文件名的实际生成逻辑

上述路径规则可以在源码中得到直接印证。在 trace_recorder.c 的TraceRecorderGetDirPath函数中，目录按如下次序逐级创建：

1. 根目录~/ascend（TraceRecorderCreateRootDir）；
2. ~/ascend/atrace（TRACE_FILE_SUB_PATH定义为"atrace"，见 trace_recorder.c）；
3. 一级目录trace_{pgid}_{pid}_{time}，对应源码中的格式化串"%s/%s/%s_%d_%d_%s"，其中%d_%d_%s依次取自TraceAttrGetPgid()、TraceAttrGetPid()、TraceAttrGetTime()；
4. 二级事件目录{event_name}_event_{pid}_{time}，对应源码中的"%s/%s/%s_%d_%d_%s/%s_event_%d_%s"，其中%s_event_%d_%s依次取自事件名dirInfo->eventName、当前进程 PIDdirInfo->pid、目录生成时间dirInfo->dirTime。

而最终日志文件的命名在TraceRecorderGetFd函数中生成（trace_recorder.c），格式化串为：

%s/%s_tracer_%s%s

即{事件目录}/{tracerName}_tracer_{objectName}{suffix}。其中tracerName即schedule、stackcore等事件名，objectName为上报轨迹信息的模块对象名（如ts_{device_id}或 Runtime/HCCL/AICPU 的模块名），suffix为.txt或.bin等扩展名。这也解释了为什么实际文件中会出现schedule_tracer_ts_0.txt、schedule_tracer_runtime.txt这类命名——它们都遵循{event_name}_tracer_{object_name}.{suffix}的统一格式。

此外，源码 trace_recorder.c 显示：对于exit事件，每次都会新建目录（TraceRecorderFindExistingDir对 exit 事件直接返回 NULL），而schedule/stackcore事件会复用已存在的同名事件目录，避免同一事件重复落盘产生目录碎片。

trace日志文件说明

落在事件目录下、以schedule_tracer_*/stackcore_tracer_*开头的文件即实际的 trace 日志，其含义如下表：

| 存储路径（事件目录内） | 说明 | | -- | -- | |schedule_tracer_ts_{device_id}.txt| 当发生AI Core Error、notify wait 超时时，Task Schedule 回传到 Host 侧的维测信息，包括寄存器、硬件 buffer、bitmap等，用于还原 Device 侧算子执行异常现场 | |stackcore_tracer_{signal}_{tid}_{program_name}_{time}.txt| 当Host 业务进程崩溃时记录的轻量级 core 文件，包括栈帧地址和基地址，该文件需要使用asys 工具解析 | |schedule_tracer_{object_name}.txt|Runtime、HCCL等模块在运行过程中上报的轨迹信息，记录进程运行过程，文本格式可直接查看 | |schedule_tracer_{object_name}.bin|AICPU等模块在运行过程中上报的轨迹信息，以二进制格式存储，同样需要使用asys 工具解析 |

几点使用要点：

• {device_id}为 Device ID，{tid}为崩溃线程 ID，{program_name}为崩溃的程序名，{time}为时间戳，均以实际落盘文件为准；
• .txt文件为文本格式，可直接用cat、grep、less等命令查看；.bin文件为二进制格式，需使用 asys 工具进行符号化解析才能得到可读的调用栈与轨迹信息；
• schedule_tracer_ts_{device_id}.txt是定位 AI Core Error 场景的关键文件，配合错误码与 plog 日志（参见 docs/zh/log_ref/viewing_logs_ep.md）可完成从 Host 错误信息到 Device 异常现场的完整回溯。

相关环境变量配置

围绕 trace 日志的落盘、回传与老化，有三个环境变量直接相关，均定义在 docs/zh/env_vars 目录下。

ASCEND_WORK_PATH：指定落盘根目录

设置 trace 日志落盘路径的基础路径（替换默认的$HOME部分），适用于希望将维测产物统一收敛到指定目录（如独立数据盘）的场景。

export ASCEND_WORK_PATH=/home/test

ASCEND_LOG_DEVICE_FLUSH_TIMEOUT：Device侧日志回传延时

trace 机制强调"内存记录、异常落盘"，而 Device 侧的维测信息需要回传到 Host 侧统一落盘。业务进程退出前，系统默认提供2000ms的延时用于将 Device 侧信息回传至 Host 侧，超时后业务进程退出；未回传成功的信息则直接在 Device 侧落盘（路径为/var/log/npu/slog）。

可通过环境变量ASCEND_LOG_DEVICE_FLUSH_TIMEOUT调整该延时，详见 ASCEND_LOG_DEVICE_FLUSH_TIMEOUT.md：

• 取值范围：[0, 180000]，单位为 ms；
• 默认值：2000；
• 配置示例：

export ASCEND_LOG_DEVICE_FLUSH_TIMEOUT=5000

• 使用建议：
  • 若业务进程不需要等待所有 Device 侧信息回传，可设置为0（立即退出）；
  • 若业务进程退出后仍有 Device 侧信息未回传（可从 device-app-pid 的日志内容判断），建议设置更大的延时；
  • 可通过echo $ASCEND_LOG_DEVICE_FLUSH_TIMEOUT查看当前配置；未配置、配置为空或配置为非法值时会采用默认值 2000；
  • 使用约束：仅适用于 Ascend EP 标准形态，全量芯片支持。

ASCEND_TRACE_RECORD_NUM：控制trace日志老化

trace 目录会随业务运行不断增长，为避免磁盘被占满，系统提供目录级老化能力。环境变量ASCEND_TRACE_RECORD_NUM用于控制trace_{进程组pid}_{首次加载trace动态库的进程pid}_{首次加载trace动态库的时间戳}/目录下schedule_event_{当前进程pid}_{目录生成时的时间戳}子目录的数量上限，详见 ASCEND_TRACE_RECORD_NUM.md：

• 取值范围：[10, 1000]；
• 计数方式：Host 侧的 trace 日志目录和 Device 侧的 trace 日志目录分开计数，配置后会分别控制 Host 与 Device 的事件目录数量；
• 配置示例：

export ASCEND_TRACE_RECORD_NUM=15

表示trace_*目录下最多保留 15 个schedule_event_*子目录，超过该数量后自动删除时间戳较老的目录；

• 使用约束：无；全量芯片支持。

日志增长与磁盘空间维护

需要特别注意的是：trace 日志目录是容器或物理机内所有应用程序共同使用的。随着新应用进程不断启动，trace_{进程组pid}_...目录会持续增加，日志总量不断增长。官方文档给出如下维护建议：

• 定期清理：定期清理$HOME/ascend/atrace/目录，避免磁盘空间不足影响业务正常运行；
• 自动化切分：可以使用系统自带的logrotate实现日志切分与轮转，将清理动作自动化；
• 结合老化策略：将ASCEND_TRACE_RECORD_NUM老化机制与周期性清理结合，可同时控制目录数量上限与整体磁盘占用。

典型故障场景下的trace日志定位流程

结合上文内容，在两类高频故障场景中，trace 日志的定位路径如下：

场景一：AI Core Error 或 notify wait 超时

1. 确认业务进程在 Host 侧运行的 PID；
2. 在$HOME/ascend/atrace/trace_{进程组pid}_{首次加载trace动态库的进程pid}_{首次加载trace动态库的时间戳}/schedule_event_{进程pid}_{时间戳}/目录下查找schedule_tracer_ts_{device_id}.txt；
3. 该文件记录了 Task Schedule 回传的寄存器、硬件 buffer、bitmap等维测信息，可据此还原 Device 侧异常现场；
4. 如需完整的任务执行轨迹，可进一步查看同目录下 Runtime、HCCL、AICPU 模块的schedule_tracer_{object_name}.txt/.bin文件（.bin文件用 asys 工具解析）。

场景二：Host 进程崩溃或收到异常信号

1. 在.../stackcore_event_{进程pid}_{时间戳}/目录下查找stackcore_tracer_{signal}_{tid}_{program_name}_{time}.txt；
2. 该文件是崩溃时刻的轻量级 core 文件，包含栈帧地址和基地址；
3. 使用asys 工具对该文件进行解析，还原崩溃现场的调用栈（signal、tid、program_name字段可用于快速确认崩溃信号类型、线程与程序）。

小结

CANN Runtime 的 trace 机制以"内存记录、异常落盘"为核心设计，在保障业务性能的同时，为 AI Core Error、notify wait 超时、进程崩溃等异常场景保留了完整的维测现场。掌握$HOME/ascend/atrace/trace_{pgid}_{pid}_{time}/{event}_event_{pid}_{time}/三级目录命名规则、四类*_tracer_*日志文件的含义，以及 ASCEND_WORK_PATH、ASCEND_LOG_DEVICE_FLUSH_TIMEOUT、ASCEND_TRACE_RECORD_NUM 三个环境变量的配置方法，即可在故障发生时快速定位并解读 trace 日志。相关实现细节可进一步阅读 src/dfx/trace 目录下的源码（入口为 trace_recorder.c 与 trace_event.c），并将 trace 日志与 docs/zh/log_ref/log_overview.md 介绍的应用类日志（plog）配合使用，形成完整的故障定位证据链。

• CANN
• Ascend
• 人工智能
• 任务调度