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

前提条件

已在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 | False"] [--output="path2"]

• 参数说明：
  • task_dir：可选参数，用于指定收集算子编译文件和dump图的目录，若不指定task_dir参数，则不收集算子编译文件、GE dump图和TF Adapter dump图。

    若收集L0 exception dump信息时，则不需要配置该参数，工具默认从${ASCEND_WORK_PATH}和${ASCEND_CACHE_PATH}环境变量下收集dump文件和算子编译文件。同时需确保未配置${NPU_COLLECT_PATH}环境变量，否则只会收集L1 exception dump信息，不会收集L0 exception dump信息。

  • 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_timestap         
       ├── 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图收集功能。本工具内部会通过环境变量NPU_COLLECT_PATH指定的路径来收集dump图及算子编译.o文件，不需要用户指定NPU_COLLECT_PATH环境变量值，该场景下，收集的是L1 exception dump信息。

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

  默认配置如下，可通过修改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 | False"] [--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}/asys_output_timestamp。命令行中不带output参数时，输出结果存放在命令行执行目录下；若output指定值为空、无效字符串、或指定路径目录无写权限、或创建目录失败，则asys工具退出执行并报错。

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

    ├── asys_output_timestap         
       ├── 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        // 用户执行任务的命令

    其中，用户可根据需求自行定义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

软硬件、Device状态信息展示

• 命令：

  asys info -r="status | software | hardware" [-d=device_id]

• 参数说明：
  • 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=device_id]

• 参数说明：
  • 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               |
     +-------------------+------------------------------+

    您可以单击Link查找对应产品的《黑匣子异常错误码列表》和《健康管理故障定义》，查阅故障码的详细描述。

综合诊断

综合检测相关命令必须在物理机且root用户下执行，且该功能涉及执行算子，因此环境中需提前安装算子二进制文件包（包名为Ascend-cann-kernels-*_linux.run）。

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

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

• 命令：

  # 该命令涉及AI Core压力测试，可能需要时间较长
  asys diagnose -r=stress_detect [-d=device_id] [--output="path"]
  
  # 该命令为hbm硬件巡检，可能需要时间较长
  asys diagnose -r=hbm [-d=device_id] [--output="path"]

• 参数说明：
  • r：必选参数，诊断模式，当前支持设置为stress_detect，即AI Core压力测试；支持设置为hbm，即hbm巡检。
  • d：可选参数，指定待诊断的device_id，不设置该参数，默认显示所有device的诊断结果。Pass表示正常，Warn表示异常。
  • output：可选参数，其值作为诊断结果文件diagnose_result.txt的保存目录。命令行中不带output参数时，输出结果不落盘仅打屏显示；若output指定值为空、无效字符串、或指定路径目录无写权限、或创建目录失败，则asys工具退出执行并报错。
• 效果展示：
  显示所有device的诊断结果时，若所有device的状态都为Pass或都为Warn时，则直接显示Pass - All或Warn - All；若一个或多个device状态不一致时，则依次显示每个device的状态，例如4个device时，显示Pass, Warn, Warn, Warn。若诊断结果为Warn，表示压测或巡检失败，可查看Host侧plog日志，并根据日志文件中的错误码定位并排除问题：1开头的错误码表示用例执行失败；2开头的错误码表示精度比对失败；3开头的错误码表示硬件问题。若诊断结果为Pass，表示压测或巡检成功，另外，针对hbm巡检，若返回的数值>0，该数值表示巡检后新增ECC错误的个数，用于提前激发风险地址报错并隔离，保证后续业务正常运行。

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

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

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

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

  • 指定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
     +------------------------+------------------------+
     | Device ID: 0           | Diagnostic Result      |
     +========================+========================+
     +--- Hardware -----------+------------------------+
     | HBM                    | Pass(9)                |
     +------------------------+------------------------+

trace/coredump/stackcore文件解析

• 命令：

  # 解析trace文件
  asys analyze -r=trace --[file|path]={name} --output={dir}
  
  # 解析coredump文件
  asys analyze -r=coredump --exe_file={name} --core_file={name} --reg={0|1|2} --symbol={0|1} --output={dir}
  
  # 解析stackcore文件
  asys analyze -r=stackcore --file={name} --symbol_path={dir,dir} --output={dir}

FAQ

• 问题现象

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

  图1 业务复跑报task occurred error
  
• 可能原因

  执行ctrl+z操作等导致任务异常终止，但还存在任务进程残留（且还进行重定向写文件操作等操作），与后面新启动的asys复跑任务相互冲突，导致复跑异常。

• 处理方法

  在asys复跑前查询是否存在运行中的推理/训练进程id，需要手工kill相关进程，然后再重新asys复跑。