CANN Runtime ASCEND_TRACE_RECORD_NUM 详解：Trace 日志目录老化规格的原理与配置实践

CANN Runtime ASCEND_TRACE_RECORD_NUM 详解Trace 日志目录老化规格的原理与配置实践【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime本文围绕 CANN Runtime 的环境变量ASCEND_TRACE_RECORD_NUM展开它用于控制$HOME/ascend/atrace/下 trace 事件子目录的老化自动清理规格。读完本文你将理解该变量的取值范围、默认值与校验规则、trace 目录/文件的命名结构、Host 与 Device 分别计数清理的底层实现以及如何在生产环境中合理配置该参数以规避磁盘空间耗尽问题。1. 功能定位trace 日志为什么需要“老化”trace 机制是指在程序运行过程中将软件栈的维测信息先记录在内存中当程序运行出错或进程结束时才落盘到文件从而避免运行过程中频繁产生和记录日志文件而影响性能参见 查看trace日志。需要注意的是当前仅 Ascend EP 标准形态支持该功能。trace 日志的落盘根目录默认为$HOME/ascend/atrace/且该目录是容器或物理机内所有应用程序共同使用的——新应用进程会不断产生新的事件目录日志会不断增多。若用户不定期清理例如使用系统自带的 logrotate 实现日志切分可能导致磁盘空间不足影响业务正常运行。ASCEND_TRACE_RECORD_NUM正是为此设计的“自动老化”开关它限制单个 trace 根目录下事件子目录的保留数量超过上限时由 trace 记录器自动删除时间戳较老的目录。该环境变量收录于环境变量参考总表 环境变量参考本文即其 ASCEND_TRACE_RECORD_NUM 文档 的展开。2. ASCEND_TRACE_RECORD_NUM 配置详解2.1 功能与取值范围该变量设置 trace 日志文件的老化规格取值范围为[10, 1000]具体指以下目录路径下事件子目录的老化规格$HOME/ascend/atrace/trace_{进程组pid}_{首次加载trace动态库的进程pid}_{首次加载trace动态库的时间戳}/其下的子目录形如schedule_event_{当前进程pid}_{目录生成时的时间戳}几个关键语义需要特别注意Host 侧与 Device 侧分开计数Host 侧的 trace 日志文件和 Device 侧的 trace 日志文件分开计数配置后将分别控制 Host 和 Device 的目录数量。也就是说若配置为 15则 Host 侧最多保留 15 个事件子目录Device 侧也各自最多保留 15 个二者互不挤占额度。老化对象是“子目录”而非“文件”超过数量上限后被删除的是时间戳较老的整个schedule_event_...子目录目录内的 trace 文件随之删除而不是单个文件内的滚动截断。默认值为 10不设置该环境变量时老化规格默认为 10 个目录源码中TRACE_DIR_NUM_DEFAULT 10见 trace_recorder.c。2.2 配置示例export ASCEND_TRACE_RECORD_NUM15表示$HOME/ascend/atrace/trace_{进程组pid}_{首次加载trace动态库的进程pid}_{首次加载trace动态库的时间戳}/下最多生成 15 个名称为schedule_event_{当前进程pid}_{目录生成时的时间戳}的目录。超过该目录数量后会自动删除时间戳较老的目录。从源码看该变量在 trace 动态库初始化阶段被解析trace_recorder.c 中的TraceInitDirNum函数先读取环境变量通过环境量索引MM_ENV_ASCEND_TRACE_RECORD_NUM 4001定义见 mmpa_env_define.h然后进行校验STATIC void TraceInitDirNum(TraceRecorderMgr* mgr) { mgr-maxDirNum TRACE_DIR_NUM_DEFAULT; // 默认值 10 const char* env NULL; MM_SYS_GET_ENV(MM_ENV_ASCEND_TRACE_RECORD_NUM, (env)); if (env NULL) { ADIAG_INF(doesnt set env ASCEND_TRACE_RECORD_NUM, use default dir num%d., mgr-maxDirNum); return; } int32_t value -1; if ((AdiagStrToInt(env, value) TRACE_SUCCESS) (value TRACE_DIR_NUM_MAX) (value TRACE_DIR_NUM_MIN)) { mgr-maxDirNum value; // 合法值[10, 1000] } else { ADIAG_WAR(invalid value [%s] for ASCEND_TRACE_RECORD_NUM, expected range: [10, 1000]. Use default dir num%d., env, mgr-maxDirNum); // 非法值告警并回退默认 10 } }由此可归纳出完整的取值行为表| 配置情况 | 行为 | | -- | -- | | 不设置 | 使用默认值 10并打印doesnt set env ASCEND_TRACE_RECORD_NUM, use default dir num10.| | 设置为 [10, 1000] 内的整数 | 生效并打印set dir numN by env ASCEND_TRACE_RECORD_NUM.| | 设置为空串、非数字、小数、或越界值如 5、1001 | 打印告警invalid value [...] expected range: [10, 1000]回退为默认值 10不会导致进程失败 |这体现了典型的“软失败”设计环境变量配置错误只降级为默认行为不影响业务进程。3. trace 目录结构与文件命名规范3.1 三级目录的命名从 trace_recorder.c 的TraceRecorderGetDirPath函数可以看到trace 日志采用三级目录结构各级格式为~/ascend/atrace/ # 落盘根目录见第 5 节可被 ASCEND_WORK_PATH 改写 └── trace_{进程组pid}_{首次加载trace动态库的进程pid}_{首次加载trace动态库的时间戳}/ └── {event_name}_event_{当前进程pid}_{目录生成时的时间戳}/ # 例如 schedule_event_12345_20260917103000123456源码中的目录拼接格式串印证了上述结构// ~/ascend/atrace/trace_{attr_group_id}_{attr_pid}_{attr_time} %s/%s/%s_%d_%d_%s, g_recorderMgr-rootPath, TRACE_FILE_SUB_PATH, TRACE_DIR_HEAD, TraceAttrGetPgid(), TraceAttrGetPid(), TraceAttrGetTime() // ~/ascend/atrace/trace_.../{tracer_name}_event_{pid}_time %s/%s/%s_%d_%d_%s/%s_event_%d_%s, ..., dirInfo-eventName, dirInfo-pid, dirInfo-dirTime其中event_name为事件类型取值为schedule业务流程异常如算子执行报错等或运行过程中的轨迹信息stackcore进程崩溃或收到异常信号exit进程正常退出析构。目录创建时权限为0750目录内 trace 文件以O_CREAT | O_WRONLY | O_APPEND方式打开文件权限0640见 trace_recorder.c 与 L516保证同一用户可写、同组可读符合日志类文件的常规安全配置。3.2 子目录内的 trace 文件每个事件子目录内会写入若干 trace 文件文件命名与用途如下来自 查看trace日志 的说明| 存储路径 | 说明 | | -- | -- | |schedule_tracer_ts_{device_id}.txt| 当发生 AI Core Error、notify wait 超时时Task Schedule 回传到 host 侧的维测信息包括寄存器、硬件 buffer、bitmap 等 | |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 工具解析 |以schedule事件为例其 tracer 名称常量TRACER_SCHEDULE_NAME schedule定义于 trace_types.hDevice 侧 schedule 事件的目录信息构造见 atrace_client_core.c——注意其中TraceDirInfo的第四个字段isDevice被置为true这正是 Host/Device 分开计数的入口。3.3 Host 与 Device 分开计数的实现trace_recorder.h 中的全局管理器结构体清晰展示了“两个独立目录链表”的设计typedef struct { int32_t maxDirNum; // default is 10, controlled by env ASCEND_TRACE_RECORD_NUM, range [10, 1000] AdiagLock lock; char rootPath[MAX_FILEDIR_LEN 1U]; // ~/ascend/atrace TraceDirList hostDirList; // Host 侧事件子目录链表 TraceDirList deviceDirList; // Device 侧事件子目录链表 TraceDirNode* exitDir; // exit 事件单独存放 char corePath[MAX_FULLPATH_LEN 1U]; } TraceRecorderMgr;maxDirNum即环境变量解析后写入的上限值hostDirList与deviceDirList是两条独立的双向链表节点定义见 trace_recorder.h每条链表各自维护count与自旋锁lock因此“Host 和 Device 分别控制目录数量”是结构层面的保证而非简单的共享配额。4. 老化机制的源码级实现4.1 何时触发老化老化不是在后台线程里周期扫描而是惰性触发每当需要为一个新的 trace 事件子目录落盘时TraceRecorderGetDirPath先构造目标目录路径并mkdir随后调用TraceRecorderSaveNode将其登记到链表登记时才检查配额。核心逻辑见 trace_recorder.cSTATIC void TraceRecorderSaveNode(const TraceDirInfo* dirInfo, TraceDirNode* dirNew) { // if exit_event, no need to aging if (strncmp(dirInfo-eventName, TRACER_EVENT_EXIT, strlen(TRACER_EVENT_EXIT)) 0) { if (g_recorderMgr-exitDir ! NULL) { ADIAG_SAFE_FREE(g_recorderMgr-exitDir); } g_recorderMgr-exitDir dirNew; return; } TraceDirList* dirList (dirInfo-isDevice) ? g_recorderMgr-deviceDirList : g_recorderMgr-hostDirList; // delete node and age the dir if (dirList-count g_recorderMgr-maxDirNum) { TraceDirNode* deleteNode TraceRecorderListPopHead(dirList); TraStatus ret TraceRmdir(deleteNode-dirPath); // 删除最老的目录 if (ret ! 0) { ADIAG_WAR(can not remove dir %s, ret%d, strerr%s., ...); } ADIAG_SAFE_FREE(deleteNode); } // append new node TraceRecorderListAppend(dirList, dirNew); }由此可以确认老化策略的完整语义按链表顺序即时间顺序新目录总是Append到链尾链头始终是时间戳最老的目录count maxDirNum时从链头PopHead并rmdir整目录实现“删最老、留最新”的 LRU 语义。并发安全链表操作全程持有dirList-lockTraceRecorderListPopHead/TraceRecorderListAppend/TraceRecorderListFind均有加锁且GetFd路径外层还持有g_recorderMgr-lock保证多线程并发落盘时的正确性。同名目录去重TraceRecorderFindExistingDir会先在链表中按路径查找已存在的目录直接复用节点而不重复计数见 trace_recorder.c。删除失败不阻断业务rmdir失败时仅打印can not remove dir告警新目录照常追加不会向业务返回错误。4.2 特例exit 事件目录不参与老化注意TraceRecorderSaveNode开头的分支exit事件进程正常退出析构时记录的目录被单独存放在g_recorderMgr-exitDir指针中不进入 host/device 链表、不占用maxDirNum配额、也不参与老化。源码注释// if exit_event, no need to aging明确了这一设计意图——进程退出是排障的关键现场其 trace 目录需要跨“老化周期”保留。4.3 单元测试对老化行为的验证仓库中的单元测试 trace_recorder_utest.cc 直接验证了上述机制可作为行为正确性的依据TraceRecorderGetFd_SameDirAgingKeepsWritableL688-L716设置setenv(ASCEND_TRACE_RECORD_NUM, 10, 1)后连续 11 次获取 fd验证老化过程不破坏当前正在写目录的可写性TraceRecorderGetFd_ConcurrentDirAgingKeepsFirstOpenL718-L764通过 mockTraceOpen阻塞首个打开操作再启动老化线程连续创建 10 个新目录L122-L138验证并发老化时首个已打开的 fd 依然有效即“老化最老目录”不会波及正在写入的目录多处测试在EXPECT_EQ(TRACE_SUCCESS, TraceRecorderInit())前统一通过setenv/unsetenv控制该环境变量覆盖默认值与配置值的初始化路径。这些用例说明老化实现面向多进程、多线程的共享落盘场景做了专门的并发正确性验证。5. 与其他环境变量的协同根目录从哪里来ASCEND_TRACE_RECORD_NUM控制的是“目录数量”而目录的“位置”由另一条解析链决定。trace_recorder.c 的TraceInitRootPath逻辑为若编译期定义了ATRACE_ROOT_PATH直接使用该宏否则优先读取环境变量ASCEND_WORK_PATHTraceGetEnvPath见 L161-L177要求路径存在且可写必要时逐级mkdir并做realpath规范化再否则回退到用户主目录下的$HOME/ascend/。因此完整组合配置示例为# 自定义 trace 落盘根目录可选 export ASCEND_WORK_PATH/home/test # 事件子目录老化上限[10, 1000]默认 10 export ASCEND_TRACE_RECORD_NUM15配置后/home/test/atrace/trace_.../下的schedule_event_...子目录按 15 个的规格自动老化。两个变量分别控制“在哪”与“留多少”互不干扰。6. 使用约束与支持范围使用约束无。该变量可独立配置不依赖其他环境变量配置非法时自动回退默认值不产生副作用。支持的型号全量芯片支持。适用前提老化清理依托 trace 机制落盘行为而 trace 机制当前仅 Ascend EP 标准形态支持参见 查看trace日志在未启用 trace 落盘的环境中该变量不会引起任何目录清理动作。7. 实践建议结合源码行为给出三条可落地的配置建议容量估算每个事件子目录内含一个或多个schedule_tracer_*.txt/.bin文件异常密集场景高频报错的联调环境下目录生成速度可能很快。配置较大的ASCEND_TRACE_RECORD_NUM会保留更长的排障窗口但需评估$HOME/ascend/atrace或ASCEND_WORK_PATH所在分区的剩余空间反之长期运行的稳定业务可保持默认 10让最老目录尽快被回收。保留现场优先由于exit事件目录不参与老化进程退出类现场天然保留但schedule/stackcore目录会被按数量淘汰若某次异常的现场已被老化删除则无法事后追捞——对排障要求高的节点建议适当调大该值如 100 以上并配合 logrotate 做二级兜底。验证配置是否生效配置生效与否可直接观察 trace 根目录下的目录数量或在维测日志中检索关键字get dir num by env ASCEND_TRACE_RECORD_NUM/set dir num生效日志与invalid value [...] for ASCEND_TRACE_RECORD_NUM回退告警均可用于快速确认当前运行参数。8. 小结ASCEND_TRACE_RECORD_NUM是 CANN Runtime trace 子系统中一个“小变量、大作用”的老化规格参数取值范围 [10, 1000]、默认 10、非法值静默回退它通过TraceRecorderMgr中 Host/Device 两条独立目录链表实现分开计数在每次新事件目录落盘时以 LRU 方式删除最老目录且对exit事件目录予以豁免。源码实现位于 trace_recorder.c 与 trace_recorder.h单元测试位于 trace_recorder_utest.cc配合 查看trace日志 与 环境变量参考 可形成对该功能的完整认知闭环。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考