前提条件

已在CANN运行环境上安装toolkit包。详细安装请参见《CANN 软件安装指南》。

在使用asys工具前，需要以安装时的运行用户登录环境，执行source ${install_path}/latest/bin/setenv.bash命令设置环境变量，然后直接输入asys命令符，不用带asys工具完整路径的命令方式（即python3 ${install_path}/latest/toolkit/tools/ascend_system_advisor/asys/asys.py）。其中${install_path}为软件包的安装目录，例如：/usr/local/Ascend/ascend-toolkit。

故障信息收集

命令：

asys collect --task_dir=path1 --tar="True" --output=path2

参数说明：

task_dir：可选参数，用于指定收集算子编译文件（包括.o、.json等文件）和dump文件（包括GE dump图、TF Adapter dump图、exception dump等文件）的目录。
对于算子编译文件和exception dump文件，asys工具优先从环境上查找并收集exception dump文件、算子编译文件，查找不到exception dump文件时，asys工具则不收集exception dump文件。若指定task_dir参数，asys工具会从该参数指定的路径下查找并收集算子编译文件，若未指定task_dir参数，则不收集算子编译文件。

对于GE dump图、TF Adapter dump图，asys工具从task_dir参数指定的路径下收集，若未指定task_dir参数，则不收集。

若业务执行前配置了${NPU_COLLECT_PATH}环境变量，执行业务只会导出L1 exception dump信息，这时asys工具无法收集L0 exception dump信息。L1 exception dump是普通exception dump，L0 exception dump是Lite exception dump（即轻量化的exception dump），两者都会导出算子输入、算子数据、workspace数据等信息，但相比L0 exception dump，L1 exception dump的信息更多，开启L1 exception dump时，会在Host应用类日志文件（即plog日志）中打印出来各tensor的dtype等信息，还会把算子相关的算子名、kernel都打印出来。
tar：可选参数，是否将asys工具的结果输出目录压缩为*.tar.gz文件，默认不压缩，该参数值为T或True时，压缩为*.tar.gz文件且不保留原目录；参数值为F或False时，不压缩为*.tar.gz文件。参数值不区分大小写。

output：可选参数，其值作为asys工具的结果输出目录的路径前缀，即最终输出目录为{output}/asys_output_timestamp。命令行中不带output参数时，输出结果存放在命令行执行目录下；若output指定值为空、无效字符串、或指定路径目录无写权限、或创建目录失败，则asys工具退出执行并报错。

执行完命令后，在{output}/asys_output_timestamp路径下的故障信息文件目录如下所示：

├── asys_output_timestamp         
   ├── software_info.txt            // 安装包版本、环境变量、依赖软件、系统信息
   ├── hardware_info.txt            // 收集了host和device侧硬件信息，host信息包括内核版本信息、CPU型号、内存和硬盘使用情况等， device信息包括设备个数、aicpu个数等
   ├── status_info.txt              // 收集device的信息，包含芯片型号、CPU和AI Core利用率等
   ├── health_result.txt            // 收集device健康信息，包括故障码和故障信息
   └── dfx              
       ├── bbox                     // Device侧的黑匣子信息       
       ├── data-dump                // L0发生AI Core Error时，生成L0 exception dump文件
       ├── graph                    // dump图信息，包含GE与TF Adapter的dump图，L0 exception dump不收集该信息
       ├── ops                      // 算子编译信息，包括算子编译*.o和*.json文件、自定义算子配置信息等                    
       ├── stackcore                // 报错触发coredump时的core文件信息
       ├── atrace                   // trace落盘信息，包括trace二进制文件解析的明文文件
       └── log          
           ├── device       
           │     ├──dev-os-{id}
           │           ├── firmware      // 固件生成的日志
           │           ├── slogd         // 日志相关进程的维测日志
           │           ├── application   // 业务进程产生的非EVENT级别应用日志
           │           └── system        // 常驻进程生成的日志
           └── host     
                ├── message         // message/syslog日志
                ├── install         // 包历史安装情况的日志
                ├── cann            // Host侧应用类日志
                └── driver          // Host侧驱动日志

其中，用户可根据需求自行定义software_info.txt文件中收集的第三方依赖软件的版本信息。在asys工具目录下的“ascend_system_advisor/conf/dependent_package.csv”文件中，增加或删除配置项，每行对应一个配置项，逗号分割依赖项名字和查询指令，逗号后无空格。示例片段如下：

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

业务复跑+故障信息收集

业务复跑默认开启算子编译文件、GE dump图和TF Adapter dump图收集功能。

asys launch命令执行时会自动开启以下环境变量临时存放收集到的信息，asys launch命令执行结束时会自动关闭以下环境变量，若用户在执行asys launch命令前手动设置了这些环境变量，则用户设置的这部分环境变量会被覆盖、不生效；若复跑的用户任务脚本中涉及这些环境变量，则可能导致asys工具设置的环境变量被覆盖、不生效，进而导致无法收集对应的信息。
- NPU_COLLECT_PATH：指定存放dump图及算子编译.o文件的路径，此处仅收集L1 exception dump相关信息。详细说明及约束，请参见《环境变量参考》中的“NPU_COLLECT_PATH”。
- ASCEND_PROCESS_LOG_PATH：指定存放Host应用类日志的路径。详细说明及约束，请参见《环境变量参考》中的“ASCEND_PROCESS_LOG_PATH”。
- ASCEND_HOST_LOG_FILE_NUM：指定Host应用类日志目录下每个进程日志文件的数量，当前为1000。详细说明及约束，请参见《环境变量参考》中的“ASCEND_HOST_LOG_FILE_NUM”。
- ASCEND_WORK_PATH：指定存放trace日志的路径。详细说明及约束，请参见《环境变量参考》中的“ASCEND_WORK_PATH”。
asys launch命令会拉起子进程执行业务命令，若用户主动终止launch命令，业务子进程可能未退出，这时需要用户自行终止业务子进程。

（可选）修改业务复跑相关的配置项：

默认配置如下，可通过修改asys工具目录下的“ascend_system_advisor/conf/asys.ini”文件中的参数，从而打开或关闭开启算子编译文件和dump图收集等功能：

[launch]
graph = TRUE                    // 控制是否收集Graph图信息，取值范围：TURE收集、FALSE不收集，若设置为FALSE，则dump_ge_graph、dump_graph_level配置不生效
ops = TRUE                      // 控制是否收集算子编译信息，取值范围：TURE收集、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日志，取值范围：TURE开启、FALSE不开启，对应环境变量ASCEND_GLOBAL_EVENT_ENABLE
log_print_to_stdout = FALSE     // 是否开启日志打屏，取值范围：TURE开启、FALSE不开启，对应环境变量ASCEND_SLOG_PRINT_TO_STDOUT

asys工具启动时，环境变量默认使用该文件里的配置值，但如果复跑任务脚本中将这些环境变量配置为其它值，则会发生环境变量覆盖，以复跑任务脚本中设置的值为准。因此，可能造成收集到的维测信息不满足定位需求。

命令：

asys launch --task="sh ../app_run.sh" --tar="True" --output=path

参数说明：

task：必须参数，为复跑业务的执行命令，需要填写完整的命令，例如"sh ../app_run.sh", sh为执行任务的命令，../app_run.sh为要执行的任务脚本。
不支持原有执行脚本内部直接后台执行的方式。例如：原有用例通过命令行执行 sh cmd.sh来拉起用例，而cmd.sh的实现里执行python3 test.py &，用后台的方式执行，此种任务由于无法感知结束点，暂不支持使用。
tar：可选参数，是否将asys工具的结果输出目录压缩为*.tar.gz文件，默认不压缩，该参数值为T或True时，压缩为*.tar.gz文件且不保留原目录；参数值为F或False时，不压缩为*.tar.gz文件。参数值不区分大小写。

执行完命令后，在{output}/asys_output_timestamp路径下的故障信息文件目录如下所示：

├── asys_output_timestamp         
   ├── software_info.txt            // 安装包版本、环境变量、依赖软件、系统信息
   ├── hardware_info.txt            // 收集了host和device侧硬件信息，host信息包括内核版本信息、CPU型号、内存和硬盘使用情况等， device信息包括设备个数、aicpu个数等
   ├── status_info.txt              // 收集device的信息，包含芯片型号、CPU和AI Core利用率等
   ├── health_result.txt            // 收集device健康信息，包括故障码和故障信息
   └── dfx              
       ├── bbox                     // Device侧的黑匣子信息       
       ├── data-dump                // 发生Aicore err时，生成的dump文件
       ├── graph                    // dump图信息，包含GE与TF Adapter的dump图
       ├── ops                      // 算子编译信息，包括算子编译*.o和*.json文件、算子编译过程信息、自定义算子配置信息等 
       ├── stackcore                // 报错触发coredump时的core文件信息
       ├── atrace                   // trace落盘信息，包括trace二进制文件解析的明文文件
       └── log          
           ├── device       
           │     ├──dev-os-{id}
           │           ├── firmware      // 固件生成的日志
           │           ├── slogd         // 日志相关进程的维测日志
           │           ├── application   // 业务进程产生的非EVENT级别应用日志
           │           └── system        // 常驻进程生成的日志
           └── host     
                ├── message         // message/syslog日志
                ├── install         // 包历史安装情况的日志
                ├── cann            // Host侧应用类日志
                ├── driver          // Host侧驱动日志
                ├── screen.txt      // 打屏日志（如果内容为空，则可能应用任务中设置了重定向。）
                └── user_cmd        // 用户执行任务的命令

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

软硬件、Device状态信息展示

命令：
```
asys info -r="status" -d=deviceId
```
参数说明：
- r：必选参数，指定需展示的信息类型，支持如下取值：
  - status：显示device的信息，包含芯片型号、温度、健康状态、CPU和AI Core信息等。
  - software：显示Host的软件信息，包含系统和内核版本、CANN包版本等信息。
  - hardware：显示Host和Device的硬件信息，包括Host的CPU型号&核数、内存容量和硬盘容量，Device的NPU个数&型号，AI CPU/AI Core/AI Vector个数等信息。
- d：可选参数，指定需要展示信息的device_id，不设置该参数，默认展示device 0的信息；仅-r=status时有效。

健康检查

命令：
```
asys health -d=deviceId
```
参数说明：
- d：可选参数，指定需要显示健康状态的device_id。不指定device时，显示所有device的健康状态；指定device时，若device有异常，则在终端屏幕上显示故障码和故障信息，仅显示前5组故障，在故障信息收集和业务复跑+故障信息收集时会将所有故障码和故障信息写入health_result.txt文件。

效果展示：

不指定device，所有device都正常，此处以双卡为例：

asys health
 +------------------------+------------------------------+
 | Group of 2 Device      | Overall Health: Healthy      |
 +========================+==============================+
 | Device ID: 0           | Healthy                      |
 +------------------------+------------------------------+
 | Device ID: 1           | Healthy                      |
 +------------------------+------------------------------+

指定device，device正常，此处以device 0为例：

asys health -d=0
 +-------------------+------------------------------+
 | Device ID: 0      | Overall Health: Healthy      |
 |                   | ErrorCode Num: 0             |
 +===================+==============================+

指定device，device异常，此处以device 0为例：

asys health -d=0
 +-------------------+------------------------------+
 | Device ID: 0      | Overall Health: Warning      |
 |                   | ErrorCode Num: 1             |
 +===================+==============================+
 | 0xa419321c‬        | lp pmbus error               |
 +-------------------+------------------------------+

您可以单击《黑匣子异常错误码信息列表》和《健康管理故障定义》获取对应版本的手册，查阅故障码的详细描述。

综合检测

综合检测相关命令必须在物理机且root用户下执行。

同时仅以下产品支持使用综合检测功能：

Atlas A2 训练系列产品/Atlas 800I A2 推理产品

命令：

# AI Core压力检测，可能需要时间较长
asys diagnose -r=stress_detect -d=deviceId --output=path

# HBM检测
asys diagnose -r=hbm_detect -d=deviceId --timeout=num --output=path

# CPU检测
asys diagnose -r=cpu_detect -d=deviceId --timeout=num --output=path

参数说明：
- r：必选参数，检测模式，取值如下：
  - stress_detect：AI Core压力检测
    该功能涉及执行算子，因此环境中需提前安装算子二进制文件包（包名为Ascend-cann-kernels-*_linux.run）。
    
    AICore压力检测涉及到对device侧部分电压调整，当压力检测正常结束时，可自行恢复；但部分压力检测异常退出时，存在电压不能自行恢复，这时用户可以根据asys环境配置功能手动恢复电压。建议在执行AI Core压力检测前、后，用户可以分别获取电压，用于判断电压是否异常、以及是否需要恢复电压。获取及恢复电压请参见环境配置。
    显示检测结果时：
    - 不指定device但device只有一个时，仅显示这个device的状态。
    - 显示所有device的检测结果时，若所有device的状态都为Pass、Warn，则直接显示Pass - All、Warn - All。
    - 若一个或多个device状态不一致时，则依次显示每个device的状态，例如4个device时，显示Pass, Warn, Warn, Warn。
    - 若检测结果为Warn，表示检测失败，可查看Host侧plog日志，并根据日志文件中的错误码定位并排除问题：1开头的错误码表示用例执行失败、任务下发失败等；2开头的错误码表示精度比对失败；3开头的错误码表示硬件问题。
    - 若检测结果为Pass，表示检测成功。
  - hbm_detect：HBM检测
    显示检测结果时：
    - 不指定device但device只有一个时，仅显示这个device的状态。
    - 显示所有device的检测结果时，若所有device的状态都为Pass、Warn，则直接显示Pass - All、Warn - All。
    - 若一个或多个device状态不一致时，则依次显示每个device的状态，例如4个device时，显示Pass, Warn, Warn, Warn。
    - 若检测结果为Warn，表示检测失败，可查看Host侧plog日志，并根据日志文件中的错误码定位并排除问题：1开头的错误码表示用例执行失败、任务下发失败等；4开头的错误码表示硬件问题。
    - 若检测结果为Pass，表示检测成功。针对hbm检测，若返回的数值>0，该数值表示检测后新增ECC错误的个数，用于提前激发风险地址报错并隔离，保证后续业务正常运行。
  - cpu_detect：CPU检测
    显示检测结果时：
    - 不指定device但device只有一个时，仅显示这个device的状态。
    - 显示所有device的检测结果时，若所有device的状态都为Pass、Warn、Fail，则直接显示Pass - All、Warn - All、Fail - All。
    - 若一个或多个device状态不一致时，则依次显示每个device的状态，例如4个device时，显示Pass, Warn, Warn, Fail。
    - 若检测结果为Fail，表示检测出硬件故障，需联系技术支持。
    - 若检测结果为Warn，表示检测过程中任务调度出现问题。可查看Host侧plog日志中的详细信息定位问题。
    - 若检测结果为Pass，表示检测成功。
- d：可选参数，指定待检测的device_id，不设置该参数，默认显示所有device的检测结果。Pass表示正常，Warn表示异常。
- timeout：可选参数，指定硬件检测时间，单位秒。不传默认检测600秒。仅HBM检测、CPU检测时生效，HBM检测时取值范围：[0, 604800]，设置为0时表示仅执行一轮HBM检测；CPU检测时取值范围：[1, 604800]。
- output：可选参数，其值作为检测结果文件diagnose_result_{time_stamp}.txt的保存目录。命令行中不带output参数时，输出结果不落盘仅打屏显示；若output指定值为空、无效字符串、或指定路径目录无写权限、或创建目录失败，则asys工具退出执行并报错。

效果展示：

不指定device，所有device正常，此处以四卡为例：

asys diagnose -r=stress_detect
 +------------------------+ -----------------------+ 
 | Group of 4 Device      | Diagnostic Result      | 
 +========================+ =======================+ 
 +--- Performance --------+ -----------------------+ 
 | Stress Detect          | Pass - All             | 
 +------------------------+ -----------------------+ 
asys diagnose -r=hbm_detect --timeout=3000
 +------------------------+------------------------+
 | Group of 4 Device      | Diagnostic Result      |
 +========================+========================+
 +--- Hardware -----------+------------------------+
 | HBM                    | Pass - All             |
 |                        | (0, 9, 0, 0)           |
 +------------------------+------------------------+
asys diagnose -r=cpu_detect --timeout=3000
 +------------------------+------------------------+
 | Group of 4 Device      | Diagnostic Result      |
 +========================+========================+
 +--- Hardware -----------+------------------------+
 | CPU Detect             | Pass - All             |
 +------------------------+------------------------+

不指定device，部分device正常，此处以四卡为例：

asys diagnose -r=stress_detect
 +------------------------+ -----------------------+ 
 | Group of 4 Device      | Diagnostic Result      | 
 +========================+ =======================+ 
 +--- Performance --------+ -----------------------+ 
 | Stress Detect          | Pass, Warn, Pass, Warn | 
 +------------------------+ -----------------------+ 
asys diagnose -r=hbm_detect
 +------------------------+ -----------------------+ 
 | Group of 4 Device      | Diagnostic Result      | 
 +========================+ =======================+ 
 +--- Hardware -----------+ -----------------------+ 
 | HBM                    | Pass, Warn, Pass, Warn | 
 |                        | (9, 0, 5, 0)           |
 +------------------------+ -----------------------+ 
asys diagnose -r=cpu_detect
 +------------------------+------------------------+
 | Group of 4 Device      | Diagnostic Result      |
 +========================+========================+
 +--- Hardware -----------+------------------------+
 | CPU Detect             | Pass, Warn, Pass, Fail |
 +------------------------+------------------------+

指定device，此处以device 0为例：

asys diagnose -d=0 -r=stress_detect
 +--------------------+------------------------+
 | Device ID: 0       | Diagnostic Result      |
 +====================+========================+
 +--- Performance ----+------------------------+
 | Stress Detect      | Pass                   |
 +--------------------+------------------------+
asys diagnose -d=0 -r=hbm_detect
 +------------------------+------------------------+
 | Device ID: 0           | Diagnostic Result      |
 +========================+========================+
 +--- Hardware -----------+------------------------+
 | HBM                    | Pass(9)                |
 +------------------------+------------------------+
asys diagnose -d=0 -r=cpu_detect
 +------------------------+------------------------+
 | Device ID: 0           | Diagnostic Result      |
 +========================+========================+
 +--- Hardware -----------+------------------------+
 | CPU Detect             | Pass                   |
 +------------------------+------------------------+

trace文件解析

命令：

# 解析trace文件
asys analyze -r=trace --file=filename --output=path

参数说明：
- r ：解析模式，此处设置为trace，用于将trace日志文件（*.bin文件）解析为.txt格式的文件，使用asys工具的环境版本要与产生trace日志的环境版本保持一致。
  解析后的txt文件内容示例：
```
2024-05-09 19:08:12.408.800 demo0: tid0[0], count0[0], tag0[struct0 tag], streamId0[0], deviceIdArray0[0, 1], hostIdArray0[1, 2, 3, 4]
2024-05-09 19:08:12.408.804 demo1: tag1[struct1 tag], streamId1[0], deviceIdArray1[0, 1], hostIdArray1[1, 2, 3, 4]
```
- file：用于解析单个文件，此处设置为包含路径的文件名，trace模式必选。
- output：可选参数，其值作为asys工具的结果输出目录的路径前缀，即最终输出目录为{output}/asys_output_timestamp。命令行中不带output参数时，输出结果存放在命令行执行目录下；若output指定值为空、无效字符串、或指定路径目录无写权限、或创建目录失败，则asys工具退出执行并报错。

coredump文件解析

coredump解析功能依赖gdb，需提前安装gdb，可通过包管理（如apt-get install gdb、yum install gdb）进行安装，详细安装步骤及使用方法请参见GDB官方文档。

命令：

# 解析coredump文件
asys analyze -r=coredump --exe_file=filename --core_file=filename --reg=reglevel --symbol=value --output=path

参数说明：

r ：解析模式，此处设置为coredump。在执行任务过程中进程中断退出，软件在退出时会报Segmentation fault等错误，可以使用该功能解析coredump生成的core文件，获取stackcore格式的堆栈文件（*.txt文件），供后续定位使用。
exe_file：程序coredump时的可执行文件，此处设置为包含路径的文件名，coredump模式必选，需要保证与core_file相匹配，否则解析结果错误。
core_file：程序coredump时生成的core文件，此处设置为包含路径的文件名，coredump模式必选，需要保证与exe_file相匹配，否则解析结果错误。
reg：coredump功能添加寄存器数据的模式，只支持0、1和2，默认为0，coredump模式可选。
- 0：不添加寄存器数据。
- 1：每个线程加一条寄存器数据。
- 2：线程的所有栈都添加寄存器数据（占用Host资源较多，比较耗时）。

symbol：coredump功能解析模式，只支持0和1，默认为0，coredump模式可选，地址不存在或栈溢出可能导致asys工具无法解析。

0：将所有带地址行解析成stackcore格式的文件，其他行显示Ignore，表示跳过不解析。

symbol为0（解析所有地址行），解析后的stackcore格式文件示例：

[process]
crash reason: SIGABRT
crash pid: 37246
crash tid: 37246

[stack]
Thread 1 (37246)
#00 0x00007fbad83792bf 0x00007fbad830b000 /usr/local/python3.7.5/lib/libpython3.7m.so.1.0
#01                                       Ignore
#02 0x00007fbad83d8c22 0x00007fbad830b000 /usr/local/python3.7.5/lib/libpython3.7m.so.1.0
#03 0x00007fbad83e9648 0x00007fbad830b000 /usr/local/python3.7.5/lib/libpython3.7m.so.1.0
......

[maps]
    Start Addr           End Addr       Size     Offset objfile
0x562677ed1000     0x562677ed2000     0x1000        0x0 /usr/local/python3.7.5/bin/python3.7
0x562677ed2000     0x562677ed3000     0x1000     0x1000 /usr/local/python3.7.5/bin/python3.7
0x562677ed3000     0x562677ed4000     0x1000     0x2000 /usr/local/python3.7.5/bin/python3.7
0x562677ed4000     0x562677ed5000     0x1000     0x2000 /usr/local/python3.7.5/bin/python3.7
......

1：只解析in ?? () 行，其他行保留gdb堆栈的原数据

symbol为1（只解析in ?? () 行），解析后的stackcore格式文件示例：

[process]
crash reason: SIGABRT
crash pid: 37246
crash tid: 37246

[stack]
Thread 1 (37246)
#00 0x00007fbad83792bf in lookdict_unicode (value_addr=0x7ffea1e917e8, hash=<optimized out>, key=<optimized out>, mp=0x7fba98907fa0) at Objects/dictobject.c:811
#01 lookdict_unicode (mp=0x7fba98907fa0, key=<optimized out>, hash=<optimized out>, value_addr=0x7ffea1e917e8) at Objects/dictobject.c:783
#02 0x00007fbad83d8c22 in PyDict_GetItem (op=op@entry=0x7fba98907fa0, key=key@entry=0x7fba9a15b570) at Objects/dictobject.c:1327
#03 0x00007fbad83e9648 in _PyObject_GenericGetAttrWithDict (obj=obj@entry=0x7fba989083b0, name=name@entry=0x7fba9a15b570, dict=0x7fba98907fa0, dict@entry=0x0, suppress=suppress@entry=0) at Objects/object.c:1268
......

[maps]
    Start Addr           End Addr       Size     Offset objfile
0x562677ed1000     0x562677ed2000     0x1000        0x0 /usr/local/python3.7.5/bin/python3.7
0x562677ed2000     0x562677ed3000     0x1000     0x1000 /usr/local/python3.7.5/bin/python3.7
0x562677ed3000     0x562677ed4000     0x1000     0x2000 /usr/local/python3.7.5/bin/python3.7
0x562677ed4000     0x562677ed5000     0x1000     0x2000 /usr/local/python3.7.5/bin/python3.7
......

output：可选参数，其值作为asys工具的结果输出目录的路径前缀，即最终输出目录为{output}/asys_output_timestamp。命令行中不带output参数时，输出结果存放在命令行执行目录下；若output指定值为空、无效字符串、或指定路径目录无写权限、或创建目录失败，则asys工具退出执行并报错。

stackcore文件解析

stackcore解析功能依赖readelf进行文件信息的获取、依赖addr2line进行堆栈函数名和行号的解析，两者都是linux系统自带工具，请确保readelf、addr2line已安装且执行该脚本的用户有权限执行。

命令：

# 解析stackcore文件
asys analyze -r=stackcore --file=filename --symbol_path=path1,path2 --output=path3

参数说明：
- r ：解析模式，此处设置为stackcore，用于解析stackcore格式的文件（*.txt文件），供后续定位使用。
  解析后的txt文件示例如下，其中，线程信息以"Thread num (线程id，线程名)"开头，线程名获取失败则显示"unknown"：
```
[process]
crash reason:6
crash pid:37246
crash tid:37246
crash stack base:0x00007ffea1e96000
crash stack top:0x00007ffea1e91770

[stack]
Thread 1 (37246, python3.7)
#00 0x00007fbad83792bf lookdict_unicode in dictobject.c:811 from libpython3.7m.so.1.0
#01                    lookdict_unicode in dictobject.c:783 from libpython3.7m.so.1.0
#02 0x00007fbad83d8c22 PyDict_GetItem in dictobject.c:1328 from libpython3.7m.so.1.0
#03 0x00007fbad83e9648 _PyObject_GenericGetAttrWithDict in object.c:1269 from libpython3.7m.so.1.0
#04 0x00007fbad83e6729 module_getattro in moduleobject.c:704 from libpython3.7m.so.1.0
#05 0x00007fbad83e937b _PyObject_GetMethod in object.c:1137 from libpython3.7m.so.1.0
......

[maps]
e0000380000-e0000381000 rw-p 00000000 00:00 0 
e00003c0000-e00003c1000 rw-p 00000000 00:00 0 
562677ed1000-562677ed2000 r--p 00000000 fd:00 13113992                   /usr/local/python3.7.5/bin/python3.7
562677ed2000-562677ed3000 r-xp 00001000 fd:00 13113992                   /usr/local/python3.7.5/bin/python3.7
562677ed3000-562677ed4000 r--p 00002000 fd:00 13113992                   /usr/local/python3.7.5/bin/python3.7
......
```
- file：用于解析单个文件，此处设置为包含路径的文件名，stackcore模式必选。
  此处也支持通过path参数指定目录，用于解析指定目录及其子目录下的多个文件，与file参数互斥，stackcore模式必选。
- symbol_path：stackcore模式解析所需要的动态库目录，可传多个目录，用逗号隔开，symbol_path只扫描当前目录下的动态库，先找路径1，再找路径2，不扫描子目录, 为防止误解析建议将相关动态库放在一个路径下。stackcore模式可选，不指定symbol_path参数时从stackcore文件中获取所需要的动态库路径，为防止找不到动态库文件，建议仅在发生coredump错误的环境上使用。
- output：可选参数，其值作为asys工具的结果输出目录的路径前缀，即最终输出目录为{output}/asys_output_timestamp。命令行中不带output参数时，输出结果存放在命令行执行目录下；若output指定值为空、无效字符串、或指定路径目录无写权限、或创建目录失败，则asys工具退出执行并报错。
- 解析后的txt文件如果存在?这个字符，可能存在以下原因：
  - 编译选项：该动态库文件编译时没有使用 -g选项，以在文件中保留调试信息
  - 未添加链接参数：未使用-rdynamic来通知链接器将所有符号添加到动态符号表中
  - 未找到动态库：未找到相匹配的动态库
- stackcore解析函数名和行号时，部分动态库解析出的行号会有少许偏差，原因如下：
  - 编译选项：不同的编译选项，特别是与调试信息相关的选项，可能会造成影响。
  - 优化级别：较高的优化级别可能会导致代码的重组和优化，从而使行号与原始源代码的对应关系发生了偏差。

实时堆栈导出

该功能适用于业务进程卡住场景，以便导出堆栈信息定位问题。在业务未卡死时，执行实时堆栈导出，可能有：信号发送失败、bin文件生成超时、bin文件解析失败等异常，无法正常导出堆栈信息。另外，不支持对同一个卡住进程并行导出堆栈信息，否则可能执行命令失败。

命令：

# 导出堆栈
asys collect -r=stacktrace --remote=pid --all --quiet

参数说明：
- r ：此处设置为stacktrace，用于实时导出堆栈信息，供后续定位使用。若不设置本参数，则表示执行故障信息收集功能，但此时不能与--remote、--all、--quiet参数混用。
  命令执行成功后，根据终端屏幕提示获取导出的bin文件。
- remote：指定卡住进程的进程ID，在-r=stacktrace时必选。ID取值要求大于或等于2，若此处传入的进程ID不存在，asys命令报错退出。
- all：设置该参数表示导出卡住进程中所有线程的堆栈信息，在-r=stacktrace时必选。
- quiet：可选参数，导出堆栈信息过程中，设置该参数关闭与用户交互的开关，不设置该参数则默认开启交互，需用户确认当前服务器上是否打开trace处理的信号集（将ASCEND_COREDUMP_SIGNAL设置为非none的其他值，或未设置该环境变量）。在-r=stacktrace时可选择使用本参数。
  由于导出实时堆栈信息时，需要向指定进程发送信号35，如果关闭trace处理的信号集，则会终止卡住进程，无法导出堆栈信息。
  
  关于ASCEND_COREDUMP_SIGNAL环境变量及trace处理的信号集的详细说明请参见《环境变量参考》。

环境配置

环境配置相关命令必须在物理机且root用户下执行。同时仅以下产品支持使用环境配置功能：

Atlas A2 训练系列产品/Atlas 800I A2 推理产品

命令：

# 查询压测相关配置 
asys config -d=deviceId --get --stress_detect  

# 恢复压测相关配置 
asys config -d=deviceId --restore --stress_detect

参数说明：
- d：可选参数，指定待操作的device_id，不设置该参数，默认获取或恢复device 0的配置。
- get：获取指定配置。
- restore：恢复指定配置。
- stress_detect：表示压测相关配置。get和stress_detect配合使用，用于获取压测相关配置；restore和stress_detect配合使用，用于恢复压测相关配置。

效果展示：

# 获取压测配置
asys config -d=0 --get --stress_detect
+--------------------------------+---------------------------------+
| Device ID: 0                   | CURRENT CONFIGURATION           |
+================================+=================================+
| AI Core Voltage (MV)           | 850                             |
| Bus Voltage (MV)               | 850                             |
+--------------------------------+---------------------------------+

# 恢复压测配置
asys config -d=0 --restore --stress_detect
[ASYS] [INFO]: Configuration successfully restore, on device 0.

业务复跑报错FAQ

问题现象
先使用ctrl+z中止业务复跑task，接着再次拉起业务复跑task，屏显日志显示业务复跑task错误。如图1所示。

图1 业务复跑报task occurred error
可能原因
执行ctrl+z操作等导致任务异常终止，但还存在任务进程残留（且还进行重定向写文件操作等操作），与后面新启动的asys复跑任务相互冲突，导致复跑异常。
处理方法
在asys复跑前查询是否存在运行中的推理/训练进程id，需要手工kill相关进程，然后再重新asys复跑。

asys工具导出实时堆栈超时报错FAQ

问题现象

使用asys工具导出实时堆栈时，存在部分场景下导出超时报错，报错如下：

[ASYS] [ERROR]: Generating the stackcore bin file timeout. For details, see the related description in the document.

可能原因&解决方法
1. 实时堆栈导出功能还未初始化完成。
  这时，需等待初始化完成后，可根据plog日志（默认路径为$HOME/ascend/log/run|debug/plog/plog-pid_*.log）中的attr init success关键字判断初始化已完成，再尝试导出实时堆栈信息。
2. ASCEND_COREDUMP_SIGNAL环境变量被设置为none，关闭了部分信号集，导致实时堆栈导出功能不可用。
  这时，可根据plog日志（默认路径为$HOME/ascend/log/run|debug/plog/plog-pid_*.log）中的close the signal capture function关键字判断信号集被关闭了，需设置ASCEND_COREDUMP_SIGNAL环境变量，打开信号集。关于ASCEND_COREDUMP_SIGNAL环境变量及trace处理的信号集的详细说明请参见《环境变量参考》。
3. 用户业务执行完成，实时堆栈导出功能相关的资源已释放。
  这时，可根据plog日志（默认路径为$HOME/ascend/log/run|debug/plog/plog-pid_*.log）中的unregister all signo sigaction, can not capture signal关键字判断实时堆栈导出功能相关的资源已释放，需再次执行用户业务，才可以导出实时堆栈信息。
4. 实时堆栈导出功能异常。
  这时，可在plog日志（默认路径为$HOME/ascend/log/run|debug/plog/plog-pid_*.log）中搜ERROR关键字，查看具体报错信息，联系技术支持。单击Link联系技术支持。

asys工具使用指导（EP模式）

前提条件

故障信息收集

业务复跑+故障信息收集

软硬件、Device状态信息展示

健康检查

综合检测

trace文件解析

coredump文件解析

stackcore文件解析

实时堆栈导出

环境配置

业务复跑报错FAQ

asys工具导出实时堆栈超时报错FAQ