asys工具功能与使用约束全解oam-tools 一键式故障信息收集与维测指南【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-toolsasys 是 oam-tools 开源仓库中面向Ascend EP 形态提供的故障信息收集工具可通过单条命令一键收集软硬件信息、日志、dump、算子编译产物等维测数据并内置健康检查、综合检测、文件解析、实时堆栈导出、AI Core Error 解析与性能采集等 11 类能力。本文将围绕 asys 的功能全景、可收集信息清单与使用约束三大主线展开并结合仓库源码主入口 src/asys/asys.py、命令行解析 src/asys/cmdline/cmd_parser.py讲清命令分发链路与底层实现帮助读者在实际故障定位中正确、高效地使用该工具。一、工具定位为 Ascend EP 形态量身打造的一键式故障收集器在昇腾环境出现算子报错、设备异常、业务卡死等故障时快速拿到完整、准确的现场信息是定位问题的第一步。asys 工具的设计目标正是一键式收集不复跑业务即可把散落在 Host、Device 各处的软件信息、日志、dump 文件、算子编译产物等一次性归集到统一输出目录大幅压缩人工排查时收集信息的时间成本。从源码看asys 是一个以asys为命令入口的 Python 程序其命令分发逻辑集中在 src/asys/asys.pymain()依次完成参数查重、命令行解析、环境类型识别、配置文件加载、输出目录创建最后按命令分发到对应的执行类命令到执行类的映射定义在EXECUTE_CMD_FUNCsrc/asys/asys.py包括collect、launch、info、diagnose、health、analyze、config、profiling共 8 个功能命令工具启动后会在当前目录或--output指定的前缀路径下创建asys_output_timestamp形式的输出目录并在--tar开启时压缩为 tar.gz 归档src/asys/asys.py。最核心的使用前提是该工具仅支持在 Ascend EP加速卡直连服务器形态下使用Ascend RC裸金属/容器形态下仅collect不带-r参数与launch两个命令可用其余功能一律不支持该限制同时体现在 src/asys/asys.py 与 src/asys/cmdline/cmd_parser.py 的源码逻辑中。二、功能全景11 类维测能力一览asys 将故障定位场景拆解为以下 11 类能力每类均对应独立的子命令或参数模式功能说明对应命令/模式故障信息收集不复跑业务仅收集软硬件信息、日志等故障信息asys collect业务复跑故障信息收集复跑业务后再收集软硬件信息、日志等asys launch --task...软硬件、Device状态信息展示收集安装包版本、Device 温度、功率等asys info -rstatus/software/hardware健康检查检查所有或指定 Device 的健康状态不健康时展示报错信息asys health -did综合检测压力检测、HBM 硬件检测、CPU 检测、AI Core STL 硬件检测asys diagnose -rstress_detect/hbm_detect/cpu_detect/aicore_stl_detect组件检测当前仅支持 AI Vector 组件检测不支持并行执行asys diagnose -rcomponenttrace/coredump/stackcore/coretrace/UB 文件解析解析各类二进制/明文文件以便定位问题asys analyze -rtrace/coredump/coretrace/stackcore/ub实时堆栈导出适用于业务进程卡住场景导出堆栈定位问题asys collect -rstacktrace --remotepid环境配置获取或恢复指定配置asys config --get/--restore --stress_detectAI Core Error 故障信息解析业务日志含 aivec/aicore error exception 报错时快速定位原因asys analyze -raicore_error --path...性能数据采集采集 aicore、dvpp、memory、link、os、power 等关键性能数据asys profiling -raicore,... -p秒这些功能在源码中均有对应实现模块仓库 src/asys 下的collect/、launch/、info/、health/、diagnose/、analyze/、config_cmd/、profiling/目录与之一一对应可结合具体源码深入研读。三、命令框架从命令行参数到功能分发的源码链路asys 的命令与参数体系统一由 src/asys/cmdline/cmd_parser.py 定义其中Command枚举src/asys/cmdline/cmd_parser.py声明了 8 个命令及其支持的参数集合Arg枚举则声明了每个参数的名称、类型、取值约束与帮助信息。核心规则如下短参数-ddeviceId、-r模式、-p采集周期使用单横线长参数--output、--tar、--task、--path、--file、--timeout等使用双横线互斥与联动analyze命令的--file与--path互斥src/asys/cmdline/cmd_parser.pyconfig命令的--get与--restore互斥源码中通过预扫描 argv 手动校验src/asys/cmdline/cmd_parser.py。参数合法性校验由 src/asys/cmdline/arg_checker.py 实现其中比较有代表性的约束包括路径类参数不允许包含空格与非法字符且支持校验目录是否存在/是否可写check_arg_exist_dir、check_arg_create_dir--tar仅接受T/True/F/False不区分大小写check_arg_tar-d取值必须在[0, 63]且小于实际 Device 数量check_arg_device_id下限/上限定义在 src/asys/common/const.pylaunch的--task必须指向可执行脚本sh/bash/python且不支持脚本内部后台执行的方式拉起任务check_arg_executable。四、asys 可收集的信息清单详解下表是 asys 工具支持收集的信息的完整清单继承自原文档表 1其中日志信息与自定义算子配置信息两类对运行权限和环境变量有明确依赖务必对照执行分类描述软件信息涉及软件包版本、环境变量、软件依赖、系统信息。日志信息包括以下信息Host 侧 CANN 软件栈日志Host 侧 message 日志Device 侧固件日志 device-* 日志需 root 权限Device 侧系统日志 message、device-os 日志需 root 权限黑匣子、stackcore 文件、coretrace 文件需 root 权限任务打印日志run 包安装日志需 run 包安装用户与应用程序执行用户一致才可收集。dump 信息包括以下信息GE dump 图TF Adapter dump 图发生 AI Core Error 时生成的 dump 文件。算子编译 *.o、*.json 文件算子编译生成的产物文件。算子编译过程信息文件仅支持在业务复跑launch时收集内容包括编译成功/失败、编译结果是复用缓存/在线编译/二进制等。能否收集取决于是否设置NPU_COLLECT_PATH环境变量设置后系统会在该变量指定目录下新建子目录extra-info/ops/并写入op_compile_stats.logasys 方可收集不设置则不生成该文件asys 也无法收集。自定义算子配置信息*.json 文件取决于两个环境变量设置ASCEND_OPP_PATH算子库安装路径时按${ASCEND_OPP_PATH}/vendors/config.ini的load_priority字段收集${ASCEND_OPP_PATH}/vendors下config/*.json设置ASCEND_CUSTOM_OPP_PATH自定义算子包安装路径时收集该目录下config/*.json两者均未设置则不收集。用户用例执行的命令信息记录用户执行任务的命令。调试版本的二进制信息即${ASCEND_OPP_PATH}/debug_kernel目录下的信息需提前配置ASCEND_OPP_PATH未配置或配置不正确时默认不收集。说明上述NPU_COLLECT_PATH、ASCEND_OPP_PATH、ASCEND_CUSTOM_OPP_PATH等环境变量的详细配置说明请查阅昇腾社区《环境变量参考》手册原文档在说明中给出的官方环境变量参考文档。输出目录结构与典型产物以asys collect为例完整命令与参数见 故障信息收集执行后会在{output}/asys_output_timestamp下生成以下目录结构├── asys_output_timestamp ├── software_info.txt // 安装包版本、环境变量、依赖软件、系统信息 ├── hardware_info.txt // host 与 device 侧硬件信息内核版本、CPU 型号、内存/硬盘使用、设备个数、aicpu 个数等 ├── status_info.txt // device 信息包括芯片型号、CPU 和 AI Core 利用率等 ├── health_result.txt // device 健康信息包括故障码和故障信息 └── dfx ├── bbox // Device 侧的黑匣子信息 ├──>make,make --version cmake,cmake --version unzip,unzip -v zlib1g,dpkg -l zlib1g| grep zlib1g| grep ii zlib1g-dev,dpkg -l zlib1g-dev| grep zlib1g-dev| grep ii libsqlite3-dev,dpkg -l libsqlite3-dev| grep libsqlite3-dev| grep ii openssl,dpkg -l openssl| grep openssl| grep ii libssl-dev,dpkg -l libssl-dev| grep libssl-dev| grep ii libffi-dev,dpkg -l libffi-dev| grep libffi-dev| grep ii五、使用约束与注意事项asys 的使用边界由以下 6 条约束定义违反任意一条都可能导致收集失败或数据失真不支持 Ascend RC 形态仅 EP 形态可用RC 下仅支持collect不带-r与launch命令源码限制见 src/asys/asys.py。相同用户、相同时间段、同机器同时作业时收集到的数据会有交叉多任务并发收集会互相干扰产生归属不清的维测数据。非 root 用户获取到的数据范围受限具体限制参见上文信息清单中的需 root 权限标注如 Device 侧固件日志、系统日志、黑匣子、stackcore、coretrace 文件等。集群、容器、虚拟机、云场景不支持一键式工具收集故障信息asys 面向物理 EP 服务器设计请在符合形态的环境中使用。不建议多进程并行执行asys 涉及大量维测信息收集内存占用较大多进程并行可能导致执行出错或环境异常。trace 日志过多会拖慢执行asys 会检索 trace 日志所在目录若$HOME/ascend/atrace/下 trace 日志文件过多可能导致执行时间长。建议在需要时先清理该目录trace 日志的详细介绍可查阅《日志参考》中的查看 trace 日志章节。六、各功能命令与参数速查以下为各功能的命令格式与关键参数参数默认值、取值范围均以仓库文档与源码为准1. 故障信息收集collectasys collect --task_dirpath1 --tarTrue --outputpath2task_dir可选指定收集算子编译文件*.o、*.json和 dump 文件GE dump 图、TF Adapter dump 图、exception dump的目录未指定或未收集到时工具会按环境变量自动收集。自动收集受环境变量影响执行 asys 命令时环境变量值需与业务运行时的值保持一致涉及ASCEND_PROCESS_LOG_PATH、NPU_COLLECT_PATH、DUMP_GRAPH_PATH、ASCEND_WORK_PATH、ASCEND_CACHE_PATH、ASCEND_CUSTOM_OPP_PATH。tar可选T/True压缩为 *.tar.gz 且不保留原目录F/False不压缩默认。参数值不区分大小写。output可选结果输出目录的前缀路径最终输出目录为{output}/asys_output_timestamp不带该参数时输出到命令行执行目录。若指定值为空、无效字符串、路径无写权限或创建目录失败工具将退出报错。2. 业务复跑故障信息收集launchasys launch --tasksh ../app_run.sh --tarTrue --outputpathtask必选复跑业务的完整执行命令如sh ../app_run.sh。不支持执行脚本内部直接后台执行如脚本里执行python3 test.py 此类任务无法感知结束点暂不支持。注意事项launch 执行时会自动开启NPU_COLLECT_PATH、ASCEND_PROCESS_LOG_PATH、ASCEND_WORK_PATH三个环境变量用于临时存放收集信息结束时会自动关闭若用户手动设置了这些环境变量或任务脚本中覆盖了它们将导致对应信息无法收集。另外若用户主动终止 launch 命令业务子进程可能未退出需要用户自行终止。业务复跑默认开启算子编译文件、GE dump 图、TF Adapter dump 图收集可通过 src/asys/conf/asys.ini 中[launch]段配置开关与级别[launch] graph TRUE // 是否收集 Graph 图信息TRUE/FALSEFALSE 时 dump_ge_graph、dump_graph_level 不生效 ops TRUE // 是否收集算子编译信息TRUE/FALSE dump_ge_graph 2 // dump 图内容多少取 2 表示不含权重等数据的基础版 dump对应环境变量 DUMP_GE_GRAPH dump_graph_level 3 // dump 图数量取 3 表示 dump 最后阶段的生成图对应环境变量 DUMP_GRAPH_LEVEL log_level INFO // 应用类日志全局级别及各模块级别对应环境变量 ASCEND_GLOBAL_LOG_LEVEL log_event_enable TRUE // 是否开启 Event 日志TRUE/FALSE对应 ASCEND_GLOBAL_EVENT_ENABLE log_print_to_stdout FALSE // 是否在终端屏幕打印日志TRUE/FALSE对应 ASCEND_SLOG_PRINT_TO_STDOUT注意asys 启动时环境变量默认使用该文件配置值但若复跑任务脚本中将这些环境变量配置为其它值则会发生覆盖以脚本中的值为准可能造成收集的维测信息不满足定位需求。3. 软硬件、Device 状态信息展示infoasys info -rstatus -ddeviceIdr必选status显示 device 信息芯片型号、温度、健康状态、CPU 和 AI Core 信息等software显示 Host 软件信息系统/内核版本、CANN 包版本等hardware显示 Host 与 Device 硬件信息Host 的 CPU 型号核数、内存/硬盘容量Device 的 NPU 个数型号、AI CPU/AI Core/AI Vector 个数等。d可选指定 deviceId仅-rstatus时有效默认展示 device 0 的信息。各产品型号输出有所不同以实际输出为准。4. 健康检查healthasys health -ddeviceIdd可选不指定时显示所有 device 的健康状态指定时若 device 异常屏幕仅显示前 5 组故障码与故障信息全部故障码与故障信息会写入 health_result.txt 文件在 collect/launch 收集时。故障级别与健康状态对应关系提示-Healthy正常状态也显示 Healthy、次要-Warning、重要-Alarm、紧急-Critical、未知-Unknown。5. 综合检测diagnoseasys diagnose -rstress_detect -ddeviceId --outputpath # AI Core 压力检测耗时可能较长 asys diagnose -rhbm_detect -ddeviceId --timeoutnum --outputpath # HBM 检测 asys diagnose -rcpu_detect -ddeviceId --timeoutnum --outputpath # CPU 检测 asys diagnose -raicore_stl_detect -ddeviceId --outputpath # AI Core STL 硬件检测仅 Ascend 950PR/950DT必须在物理机且 root 用户下执行Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品不支持综合检测功能。r必选检测模式。stress_detect需环境中提前安装算子二进制包Ascend-cann-*-ops-*.run压力检测涉及对 device 侧部分电压调整异常退出时电压可能无法自行恢复可通过环境配置功能手动恢复电压。timeout可选检测时长秒默认 600 秒仅 HBM 检测与 CPU 检测生效HBM 取值范围[0, 604800]0 表示仅执行一轮CPU 取值范围[1, 604800]上限/默认定义见 src/asys/common/const.py。output可选检测结果文件diagnose_result_{time_stamp}.txt的保存目录不带则结果仅在终端屏幕显示。结果判定检测为 Warn 时可查看 Host 侧 plog 日志默认$HOME/ascend/log/run|debug/plog/plog-{pid}_*.log按关键字[ERROR] AML筛选并按错误码前缀定位1 开头为用例/任务下发失败2 开头为精度比对失败3/4 开头为硬件问题。HBM 检测返回数值 0 时该值表示检测后新增 ECC 错误个数用于提前激发风险地址报错并隔离。6. 组件检测componentasys diagnose -rcomponent -ddeviceId --outputpath当前仅支持 AI Vector 组件检测不支持并行执行-d不指定时默认检测所有 devicePass 表示正常Fail 表示异常检测结果为 Fail 时可查看debug_info.txt日志定位问题。7. 文件解析analyzeasys analyze -rtrace --filefilename --outputpath asys analyze -rcoredump --core_filecore --exe_fileapp --symbol0|1 --outputpath asys analyze -rstackcore --pathdir|--filefile --symbol_pathdir1,dir2 --reg0|1|2 --outputpath asys analyze -rub --pathdir --outputpathr必选trace*.bin 文件解析为 .txt、coredump、coretrace、stackcore、ub。使用 asys 工具的环境版本需与产生 trace 日志的环境版本保持一致。--file/--path互斥参数trace、coretrace、stackcore模式二选一coredump模式使用--core_file与--exe_file。--symbol仅 coredump是否在结果中保留解析失败的栈帧以??表示0 不保留默认、1 保留。--symbol_path仅 stackcore可执行文件与依赖动态库路径子目录不检索默认取 stackcore 文件中的动态库路径。--reg仅 stackcore寄存器数据添加模式0 不添加默认、1 仅线程添加、2 所有栈帧添加。8. 实时堆栈导出stacktraceasys collect -rstacktrace --remotepid --all --quiet --timeoutnum --outputpath适用于训练、推理业务进程卡住场景业务未卡死时执行可能遇到信号发送失败、bin 文件生成超时、解析失败等异常不支持对同一个卡住进程并行导出堆栈。remote必选配合-rstacktrace卡住进程的进程 ID要求 ≥ 2进程不存在则报错退出。all必选导出卡住进程中所有线程的堆栈信息。quiet可选关闭导出过程中的用户交互确认默认开启需确认服务器是否打开 trace 处理的信号集。timeout可选导出超时时间取值范围[1, 60]秒默认 10 秒。原理说明导出实时堆栈需向指定进程发送信号 35若通过环境变量ASCEND_COREDUMP_SIGNALnone关闭了信号集则会终止卡住进程无法导出堆栈。建议执行前先清理$HOME/ascend/atrace/下的 trace 日志避免检索耗时过长。9. 环境配置configasys config -ddeviceId --get --stress_detect # 查询压测相关配置 asys config -ddeviceId --restore --stress_detect # 恢复压测相关配置必须在物理机且 root 用户下执行Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品不支持。--get与--restore互斥--stress_detect表示压测相关配置AI Core Voltage、Bus Voltage 等配合--get查询、配合--restore恢复。10. AI Core Error 故障信息解析asys analyze -raicore_error -ddeviceId --path${HOME}/aic_err_info_timestamp适用场景业务日志或屏幕打印包含 there is an aivec error exception 或 there is an aicore error exception 等 AI Core Error 报错时。注意事项为保证解析准确性复现问题前建议先清理日志--output目录不能是--path目录或其子目录避免循环拷贝。path不配置时工具自动收集故障信息同样受ASCEND_PROCESS_LOG_PATH、NPU_COLLECT_PATH、DUMP_GRAPH_PATH、ASCEND_WORK_PATH、ASCEND_CACHE_PATH、ASCEND_CUSTOM_OPP_PATH影响若这些环境变量都不存在则从执行命令的当前目录收集。若收集到多个 AI Core Error 问题按日志时间解析第一次出现的问题。11. 性能数据采集profilingasys profiling -raicore -p10 -d0 --output./ --aic_metricsPipeUtilizationr必选采集类型支持dvpp、aicore、os、memory、link、power可多个以英文逗号分隔。p必选采集间隔秒最小值 1最大值 30*24*3600即 src/asys/common/const.py 中的MAX_PERIOD。d可选deviceId仅支持单个默认 0。aic_metrics可选采集类型含 aicore 时生效AI Core PMU 类型支持PipeUtilization默认计算/搬运单元耗时占比、ArithmeticUtilizationcube/vector 指令耗时占比、Memory、MemoryL0、MemoryUB、ResourceConflictRatio、L2Cache、MemoryAccess这些取值与 src/asys/cmdline/cmd_parser.py 中AIC_METRICS枚举完全一致。输出目录为{output}/asys_profiling_result_{timestamp}执行成功后会调用底层 msprof 完成采集与数据导出见 src/asys/profiling/asys_profiling.py。七、常见问题FAQ业务复跑报错ctrlz 中止后残留进程冲突现象先使用ctrlz中止业务复跑 task再次拉起时屏显出现Segmentation fault (core dumped)、BrokenPipeError: [Errno 32] Broken pipe等错误。原因ctrlz等操作导致任务异常终止但存在任务进程残留且仍在进行重定向写文件等操作与新启动的 asys 复跑任务相互冲突。处理复跑前查询是否存在运行中的推理/训练进程 id手工 kill 相关进程后再重新复跑。实时堆栈导出超时报错现象[ASYS] [ERROR]: Generating the stackcore bin file timeout.该报错可能由以下场景导致实时堆栈导出功能还未初始化完成需等待初始化完成可根据 plog 日志默认$HOME/ascend/log/run|debug/plog/plog-{pid}_*.log中的attr init success关键字判断。ASCEND_COREDUMP_SIGNAL被设置为 none关闭了部分信号集根据 plog 日志中的close the signal capture function关键字判断需重新设置该环境变量打开信号集。用户业务已执行完成相关资源已释放根据 plog 日志中的unregister all signal handlers, can not capture signal关键字判断需再次执行业务才能导出。功能本身异常在 plog 日志中搜索ERROR关键字查看具体报错联系技术支持。八、总结asys 将故障定位中最繁琐的信息收集环节收敛为一条命令覆盖了从常规信息收集collect、业务复跑launch、状态展示info、健康检查health、硬件检测diagnose、文件解析analyze、实时堆栈导出stacktrace到环境配置config、性能采集profiling的完整维测链路。使用时的三条关键纪律是确认 Ascend EP 形态RC 下功能受限、确保环境变量与业务运行时一致否则收集的信息不准确、遵守权限与并行约束root 权限要求、勿多进程并行。在此基础上结合 src/asys 源码、src/asys/conf/asys.ini 与 src/asys/conf/dependent_package.csv 等配置文件按需定制即可形成一套高效、可复用的昇腾故障现场采集与定位流程。【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 asys工具功能与使用约束全解：oam-tools 一键式故障信息收集与维测指南
asys工具功能与使用约束全解oam-tools 一键式故障信息收集与维测指南【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-toolsasys 是 oam-tools 开源仓库中面向Ascend EP 形态提供的故障信息收集工具可通过单条命令一键收集软硬件信息、日志、dump、算子编译产物等维测数据并内置健康检查、综合检测、文件解析、实时堆栈导出、AI Core Error 解析与性能采集等 11 类能力。本文将围绕 asys 的功能全景、可收集信息清单与使用约束三大主线展开并结合仓库源码主入口 src/asys/asys.py、命令行解析 src/asys/cmdline/cmd_parser.py讲清命令分发链路与底层实现帮助读者在实际故障定位中正确、高效地使用该工具。一、工具定位为 Ascend EP 形态量身打造的一键式故障收集器在昇腾环境出现算子报错、设备异常、业务卡死等故障时快速拿到完整、准确的现场信息是定位问题的第一步。asys 工具的设计目标正是一键式收集不复跑业务即可把散落在 Host、Device 各处的软件信息、日志、dump 文件、算子编译产物等一次性归集到统一输出目录大幅压缩人工排查时收集信息的时间成本。从源码看asys 是一个以asys为命令入口的 Python 程序其命令分发逻辑集中在 src/asys/asys.pymain()依次完成参数查重、命令行解析、环境类型识别、配置文件加载、输出目录创建最后按命令分发到对应的执行类命令到执行类的映射定义在EXECUTE_CMD_FUNCsrc/asys/asys.py包括collect、launch、info、diagnose、health、analyze、config、profiling共 8 个功能命令工具启动后会在当前目录或--output指定的前缀路径下创建asys_output_timestamp形式的输出目录并在--tar开启时压缩为 tar.gz 归档src/asys/asys.py。最核心的使用前提是该工具仅支持在 Ascend EP加速卡直连服务器形态下使用Ascend RC裸金属/容器形态下仅collect不带-r参数与launch两个命令可用其余功能一律不支持该限制同时体现在 src/asys/asys.py 与 src/asys/cmdline/cmd_parser.py 的源码逻辑中。二、功能全景11 类维测能力一览asys 将故障定位场景拆解为以下 11 类能力每类均对应独立的子命令或参数模式功能说明对应命令/模式故障信息收集不复跑业务仅收集软硬件信息、日志等故障信息asys collect业务复跑故障信息收集复跑业务后再收集软硬件信息、日志等asys launch --task...软硬件、Device状态信息展示收集安装包版本、Device 温度、功率等asys info -rstatus/software/hardware健康检查检查所有或指定 Device 的健康状态不健康时展示报错信息asys health -did综合检测压力检测、HBM 硬件检测、CPU 检测、AI Core STL 硬件检测asys diagnose -rstress_detect/hbm_detect/cpu_detect/aicore_stl_detect组件检测当前仅支持 AI Vector 组件检测不支持并行执行asys diagnose -rcomponenttrace/coredump/stackcore/coretrace/UB 文件解析解析各类二进制/明文文件以便定位问题asys analyze -rtrace/coredump/coretrace/stackcore/ub实时堆栈导出适用于业务进程卡住场景导出堆栈定位问题asys collect -rstacktrace --remotepid环境配置获取或恢复指定配置asys config --get/--restore --stress_detectAI Core Error 故障信息解析业务日志含 aivec/aicore error exception 报错时快速定位原因asys analyze -raicore_error --path...性能数据采集采集 aicore、dvpp、memory、link、os、power 等关键性能数据asys profiling -raicore,... -p秒这些功能在源码中均有对应实现模块仓库 src/asys 下的collect/、launch/、info/、health/、diagnose/、analyze/、config_cmd/、profiling/目录与之一一对应可结合具体源码深入研读。三、命令框架从命令行参数到功能分发的源码链路asys 的命令与参数体系统一由 src/asys/cmdline/cmd_parser.py 定义其中Command枚举src/asys/cmdline/cmd_parser.py声明了 8 个命令及其支持的参数集合Arg枚举则声明了每个参数的名称、类型、取值约束与帮助信息。核心规则如下短参数-ddeviceId、-r模式、-p采集周期使用单横线长参数--output、--tar、--task、--path、--file、--timeout等使用双横线互斥与联动analyze命令的--file与--path互斥src/asys/cmdline/cmd_parser.pyconfig命令的--get与--restore互斥源码中通过预扫描 argv 手动校验src/asys/cmdline/cmd_parser.py。参数合法性校验由 src/asys/cmdline/arg_checker.py 实现其中比较有代表性的约束包括路径类参数不允许包含空格与非法字符且支持校验目录是否存在/是否可写check_arg_exist_dir、check_arg_create_dir--tar仅接受T/True/F/False不区分大小写check_arg_tar-d取值必须在[0, 63]且小于实际 Device 数量check_arg_device_id下限/上限定义在 src/asys/common/const.pylaunch的--task必须指向可执行脚本sh/bash/python且不支持脚本内部后台执行的方式拉起任务check_arg_executable。四、asys 可收集的信息清单详解下表是 asys 工具支持收集的信息的完整清单继承自原文档表 1其中日志信息与自定义算子配置信息两类对运行权限和环境变量有明确依赖务必对照执行分类描述软件信息涉及软件包版本、环境变量、软件依赖、系统信息。日志信息包括以下信息Host 侧 CANN 软件栈日志Host 侧 message 日志Device 侧固件日志 device-* 日志需 root 权限Device 侧系统日志 message、device-os 日志需 root 权限黑匣子、stackcore 文件、coretrace 文件需 root 权限任务打印日志run 包安装日志需 run 包安装用户与应用程序执行用户一致才可收集。dump 信息包括以下信息GE dump 图TF Adapter dump 图发生 AI Core Error 时生成的 dump 文件。算子编译 *.o、*.json 文件算子编译生成的产物文件。算子编译过程信息文件仅支持在业务复跑launch时收集内容包括编译成功/失败、编译结果是复用缓存/在线编译/二进制等。能否收集取决于是否设置NPU_COLLECT_PATH环境变量设置后系统会在该变量指定目录下新建子目录extra-info/ops/并写入op_compile_stats.logasys 方可收集不设置则不生成该文件asys 也无法收集。自定义算子配置信息*.json 文件取决于两个环境变量设置ASCEND_OPP_PATH算子库安装路径时按${ASCEND_OPP_PATH}/vendors/config.ini的load_priority字段收集${ASCEND_OPP_PATH}/vendors下config/*.json设置ASCEND_CUSTOM_OPP_PATH自定义算子包安装路径时收集该目录下config/*.json两者均未设置则不收集。用户用例执行的命令信息记录用户执行任务的命令。调试版本的二进制信息即${ASCEND_OPP_PATH}/debug_kernel目录下的信息需提前配置ASCEND_OPP_PATH未配置或配置不正确时默认不收集。说明上述NPU_COLLECT_PATH、ASCEND_OPP_PATH、ASCEND_CUSTOM_OPP_PATH等环境变量的详细配置说明请查阅昇腾社区《环境变量参考》手册原文档在说明中给出的官方环境变量参考文档。输出目录结构与典型产物以asys collect为例完整命令与参数见 故障信息收集执行后会在{output}/asys_output_timestamp下生成以下目录结构├── asys_output_timestamp ├── software_info.txt // 安装包版本、环境变量、依赖软件、系统信息 ├── hardware_info.txt // host 与 device 侧硬件信息内核版本、CPU 型号、内存/硬盘使用、设备个数、aicpu 个数等 ├── status_info.txt // device 信息包括芯片型号、CPU 和 AI Core 利用率等 ├── health_result.txt // device 健康信息包括故障码和故障信息 └── dfx ├── bbox // Device 侧的黑匣子信息 ├──>make,make --version cmake,cmake --version unzip,unzip -v zlib1g,dpkg -l zlib1g| grep zlib1g| grep ii zlib1g-dev,dpkg -l zlib1g-dev| grep zlib1g-dev| grep ii libsqlite3-dev,dpkg -l libsqlite3-dev| grep libsqlite3-dev| grep ii openssl,dpkg -l openssl| grep openssl| grep ii libssl-dev,dpkg -l libssl-dev| grep libssl-dev| grep ii libffi-dev,dpkg -l libffi-dev| grep libffi-dev| grep ii五、使用约束与注意事项asys 的使用边界由以下 6 条约束定义违反任意一条都可能导致收集失败或数据失真不支持 Ascend RC 形态仅 EP 形态可用RC 下仅支持collect不带-r与launch命令源码限制见 src/asys/asys.py。相同用户、相同时间段、同机器同时作业时收集到的数据会有交叉多任务并发收集会互相干扰产生归属不清的维测数据。非 root 用户获取到的数据范围受限具体限制参见上文信息清单中的需 root 权限标注如 Device 侧固件日志、系统日志、黑匣子、stackcore、coretrace 文件等。集群、容器、虚拟机、云场景不支持一键式工具收集故障信息asys 面向物理 EP 服务器设计请在符合形态的环境中使用。不建议多进程并行执行asys 涉及大量维测信息收集内存占用较大多进程并行可能导致执行出错或环境异常。trace 日志过多会拖慢执行asys 会检索 trace 日志所在目录若$HOME/ascend/atrace/下 trace 日志文件过多可能导致执行时间长。建议在需要时先清理该目录trace 日志的详细介绍可查阅《日志参考》中的查看 trace 日志章节。六、各功能命令与参数速查以下为各功能的命令格式与关键参数参数默认值、取值范围均以仓库文档与源码为准1. 故障信息收集collectasys collect --task_dirpath1 --tarTrue --outputpath2task_dir可选指定收集算子编译文件*.o、*.json和 dump 文件GE dump 图、TF Adapter dump 图、exception dump的目录未指定或未收集到时工具会按环境变量自动收集。自动收集受环境变量影响执行 asys 命令时环境变量值需与业务运行时的值保持一致涉及ASCEND_PROCESS_LOG_PATH、NPU_COLLECT_PATH、DUMP_GRAPH_PATH、ASCEND_WORK_PATH、ASCEND_CACHE_PATH、ASCEND_CUSTOM_OPP_PATH。tar可选T/True压缩为 *.tar.gz 且不保留原目录F/False不压缩默认。参数值不区分大小写。output可选结果输出目录的前缀路径最终输出目录为{output}/asys_output_timestamp不带该参数时输出到命令行执行目录。若指定值为空、无效字符串、路径无写权限或创建目录失败工具将退出报错。2. 业务复跑故障信息收集launchasys launch --tasksh ../app_run.sh --tarTrue --outputpathtask必选复跑业务的完整执行命令如sh ../app_run.sh。不支持执行脚本内部直接后台执行如脚本里执行python3 test.py 此类任务无法感知结束点暂不支持。注意事项launch 执行时会自动开启NPU_COLLECT_PATH、ASCEND_PROCESS_LOG_PATH、ASCEND_WORK_PATH三个环境变量用于临时存放收集信息结束时会自动关闭若用户手动设置了这些环境变量或任务脚本中覆盖了它们将导致对应信息无法收集。另外若用户主动终止 launch 命令业务子进程可能未退出需要用户自行终止。业务复跑默认开启算子编译文件、GE dump 图、TF Adapter dump 图收集可通过 src/asys/conf/asys.ini 中[launch]段配置开关与级别[launch] graph TRUE // 是否收集 Graph 图信息TRUE/FALSEFALSE 时 dump_ge_graph、dump_graph_level 不生效 ops TRUE // 是否收集算子编译信息TRUE/FALSE dump_ge_graph 2 // dump 图内容多少取 2 表示不含权重等数据的基础版 dump对应环境变量 DUMP_GE_GRAPH dump_graph_level 3 // dump 图数量取 3 表示 dump 最后阶段的生成图对应环境变量 DUMP_GRAPH_LEVEL log_level INFO // 应用类日志全局级别及各模块级别对应环境变量 ASCEND_GLOBAL_LOG_LEVEL log_event_enable TRUE // 是否开启 Event 日志TRUE/FALSE对应 ASCEND_GLOBAL_EVENT_ENABLE log_print_to_stdout FALSE // 是否在终端屏幕打印日志TRUE/FALSE对应 ASCEND_SLOG_PRINT_TO_STDOUT注意asys 启动时环境变量默认使用该文件配置值但若复跑任务脚本中将这些环境变量配置为其它值则会发生覆盖以脚本中的值为准可能造成收集的维测信息不满足定位需求。3. 软硬件、Device 状态信息展示infoasys info -rstatus -ddeviceIdr必选status显示 device 信息芯片型号、温度、健康状态、CPU 和 AI Core 信息等software显示 Host 软件信息系统/内核版本、CANN 包版本等hardware显示 Host 与 Device 硬件信息Host 的 CPU 型号核数、内存/硬盘容量Device 的 NPU 个数型号、AI CPU/AI Core/AI Vector 个数等。d可选指定 deviceId仅-rstatus时有效默认展示 device 0 的信息。各产品型号输出有所不同以实际输出为准。4. 健康检查healthasys health -ddeviceIdd可选不指定时显示所有 device 的健康状态指定时若 device 异常屏幕仅显示前 5 组故障码与故障信息全部故障码与故障信息会写入 health_result.txt 文件在 collect/launch 收集时。故障级别与健康状态对应关系提示-Healthy正常状态也显示 Healthy、次要-Warning、重要-Alarm、紧急-Critical、未知-Unknown。5. 综合检测diagnoseasys diagnose -rstress_detect -ddeviceId --outputpath # AI Core 压力检测耗时可能较长 asys diagnose -rhbm_detect -ddeviceId --timeoutnum --outputpath # HBM 检测 asys diagnose -rcpu_detect -ddeviceId --timeoutnum --outputpath # CPU 检测 asys diagnose -raicore_stl_detect -ddeviceId --outputpath # AI Core STL 硬件检测仅 Ascend 950PR/950DT必须在物理机且 root 用户下执行Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品不支持综合检测功能。r必选检测模式。stress_detect需环境中提前安装算子二进制包Ascend-cann-*-ops-*.run压力检测涉及对 device 侧部分电压调整异常退出时电压可能无法自行恢复可通过环境配置功能手动恢复电压。timeout可选检测时长秒默认 600 秒仅 HBM 检测与 CPU 检测生效HBM 取值范围[0, 604800]0 表示仅执行一轮CPU 取值范围[1, 604800]上限/默认定义见 src/asys/common/const.py。output可选检测结果文件diagnose_result_{time_stamp}.txt的保存目录不带则结果仅在终端屏幕显示。结果判定检测为 Warn 时可查看 Host 侧 plog 日志默认$HOME/ascend/log/run|debug/plog/plog-{pid}_*.log按关键字[ERROR] AML筛选并按错误码前缀定位1 开头为用例/任务下发失败2 开头为精度比对失败3/4 开头为硬件问题。HBM 检测返回数值 0 时该值表示检测后新增 ECC 错误个数用于提前激发风险地址报错并隔离。6. 组件检测componentasys diagnose -rcomponent -ddeviceId --outputpath当前仅支持 AI Vector 组件检测不支持并行执行-d不指定时默认检测所有 devicePass 表示正常Fail 表示异常检测结果为 Fail 时可查看debug_info.txt日志定位问题。7. 文件解析analyzeasys analyze -rtrace --filefilename --outputpath asys analyze -rcoredump --core_filecore --exe_fileapp --symbol0|1 --outputpath asys analyze -rstackcore --pathdir|--filefile --symbol_pathdir1,dir2 --reg0|1|2 --outputpath asys analyze -rub --pathdir --outputpathr必选trace*.bin 文件解析为 .txt、coredump、coretrace、stackcore、ub。使用 asys 工具的环境版本需与产生 trace 日志的环境版本保持一致。--file/--path互斥参数trace、coretrace、stackcore模式二选一coredump模式使用--core_file与--exe_file。--symbol仅 coredump是否在结果中保留解析失败的栈帧以??表示0 不保留默认、1 保留。--symbol_path仅 stackcore可执行文件与依赖动态库路径子目录不检索默认取 stackcore 文件中的动态库路径。--reg仅 stackcore寄存器数据添加模式0 不添加默认、1 仅线程添加、2 所有栈帧添加。8. 实时堆栈导出stacktraceasys collect -rstacktrace --remotepid --all --quiet --timeoutnum --outputpath适用于训练、推理业务进程卡住场景业务未卡死时执行可能遇到信号发送失败、bin 文件生成超时、解析失败等异常不支持对同一个卡住进程并行导出堆栈。remote必选配合-rstacktrace卡住进程的进程 ID要求 ≥ 2进程不存在则报错退出。all必选导出卡住进程中所有线程的堆栈信息。quiet可选关闭导出过程中的用户交互确认默认开启需确认服务器是否打开 trace 处理的信号集。timeout可选导出超时时间取值范围[1, 60]秒默认 10 秒。原理说明导出实时堆栈需向指定进程发送信号 35若通过环境变量ASCEND_COREDUMP_SIGNALnone关闭了信号集则会终止卡住进程无法导出堆栈。建议执行前先清理$HOME/ascend/atrace/下的 trace 日志避免检索耗时过长。9. 环境配置configasys config -ddeviceId --get --stress_detect # 查询压测相关配置 asys config -ddeviceId --restore --stress_detect # 恢复压测相关配置必须在物理机且 root 用户下执行Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品不支持。--get与--restore互斥--stress_detect表示压测相关配置AI Core Voltage、Bus Voltage 等配合--get查询、配合--restore恢复。10. AI Core Error 故障信息解析asys analyze -raicore_error -ddeviceId --path${HOME}/aic_err_info_timestamp适用场景业务日志或屏幕打印包含 there is an aivec error exception 或 there is an aicore error exception 等 AI Core Error 报错时。注意事项为保证解析准确性复现问题前建议先清理日志--output目录不能是--path目录或其子目录避免循环拷贝。path不配置时工具自动收集故障信息同样受ASCEND_PROCESS_LOG_PATH、NPU_COLLECT_PATH、DUMP_GRAPH_PATH、ASCEND_WORK_PATH、ASCEND_CACHE_PATH、ASCEND_CUSTOM_OPP_PATH影响若这些环境变量都不存在则从执行命令的当前目录收集。若收集到多个 AI Core Error 问题按日志时间解析第一次出现的问题。11. 性能数据采集profilingasys profiling -raicore -p10 -d0 --output./ --aic_metricsPipeUtilizationr必选采集类型支持dvpp、aicore、os、memory、link、power可多个以英文逗号分隔。p必选采集间隔秒最小值 1最大值 30*24*3600即 src/asys/common/const.py 中的MAX_PERIOD。d可选deviceId仅支持单个默认 0。aic_metrics可选采集类型含 aicore 时生效AI Core PMU 类型支持PipeUtilization默认计算/搬运单元耗时占比、ArithmeticUtilizationcube/vector 指令耗时占比、Memory、MemoryL0、MemoryUB、ResourceConflictRatio、L2Cache、MemoryAccess这些取值与 src/asys/cmdline/cmd_parser.py 中AIC_METRICS枚举完全一致。输出目录为{output}/asys_profiling_result_{timestamp}执行成功后会调用底层 msprof 完成采集与数据导出见 src/asys/profiling/asys_profiling.py。七、常见问题FAQ业务复跑报错ctrlz 中止后残留进程冲突现象先使用ctrlz中止业务复跑 task再次拉起时屏显出现Segmentation fault (core dumped)、BrokenPipeError: [Errno 32] Broken pipe等错误。原因ctrlz等操作导致任务异常终止但存在任务进程残留且仍在进行重定向写文件等操作与新启动的 asys 复跑任务相互冲突。处理复跑前查询是否存在运行中的推理/训练进程 id手工 kill 相关进程后再重新复跑。实时堆栈导出超时报错现象[ASYS] [ERROR]: Generating the stackcore bin file timeout.该报错可能由以下场景导致实时堆栈导出功能还未初始化完成需等待初始化完成可根据 plog 日志默认$HOME/ascend/log/run|debug/plog/plog-{pid}_*.log中的attr init success关键字判断。ASCEND_COREDUMP_SIGNAL被设置为 none关闭了部分信号集根据 plog 日志中的close the signal capture function关键字判断需重新设置该环境变量打开信号集。用户业务已执行完成相关资源已释放根据 plog 日志中的unregister all signal handlers, can not capture signal关键字判断需再次执行业务才能导出。功能本身异常在 plog 日志中搜索ERROR关键字查看具体报错联系技术支持。八、总结asys 将故障定位中最繁琐的信息收集环节收敛为一条命令覆盖了从常规信息收集collect、业务复跑launch、状态展示info、健康检查health、硬件检测diagnose、文件解析analyze、实时堆栈导出stacktrace到环境配置config、性能采集profiling的完整维测链路。使用时的三条关键纪律是确认 Ascend EP 形态RC 下功能受限、确保环境变量与业务运行时一致否则收集的信息不准确、遵守权限与并行约束root 权限要求、勿多进程并行。在此基础上结合 src/asys 源码、src/asys/conf/asys.ini 与 src/asys/conf/dependent_package.csv 等配置文件按需定制即可形成一套高效、可复用的昇腾故障现场采集与定位流程。【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考