4. 工具

4.1. mx-smi工具

mx-smi工具的详细介绍，请参见《曦云^® 系列通用计算GPU mx-smi使用手册》。

4.2. mx-report工具

mx-report是曦云系列GPU的日志管理工具，负责收集KMD、UMD和Firmware模块的日志，并提供对KMD、UMD和Firmware模块的日志级别进行查询和设置的功能。

4.2.1. mx-report工具安装

曦云系列GPU软件包安装过程中会默认安装mx-report工具。软件包安装完成后，mx-report工具放置在/opt/maca/bin/目录下。

4.2.2. mx-report工具使用方法

mx-report是一个Linux命令行工具，其调用遵守如下格式。

mx-report [选项1 [参数1]] [参数2] …

4.2.3. mx-report在容器中使用

若需在容器中使用mx-report收集日志及环境信息，可在运行容器时传入以下参数：

docker run -it -d --device=/dev/dri --device=/dev/mxcd -v /sys/devices:/sys/devices -v /sys/kernel:/sys/kernel -v /opt/maca:/opt/maca -v /var/log:/var/log -v /usr/bin/kmd_diagnostic.sh:/usr/bin/kmd_diagnostic.sh -p 0.0.0.0:<hostPort>:<container_port> --hostname <host_name> --privileged=true <image ID> -p <container_port>

其中：

指定 -v /sys/kernel:/sys/kernel 及 --privileged=true 用于收集 xcore_config_id
指定 -v /var/log:/var/log 可在容器中收集日志
推荐使用 <container_ID>-主机名 指定 <hostname>，便于后期区分设备
指定 -v /usr/bin/kmd_diagnostic.sh:/usr/bin/kmd_diagnostic.sh 可收集KMD诊断相关信息

4.2.4. mx-report命令介绍

mx-report命令说明，可以通过在工作环境中执行 man mx-report 获取。

4.2.4.1. 通用选项

-h, --help

打印使用帮助信息。

-v, --version

打印mx-report的版本信息。

4.2.4.2. 日志导出选项

mx-report

导出当前GPU所有模块日志及收集的环境信息，若不指定 --path，默认存放在当前目录下以“主机名_时间戳”命名的文件夹中。

--path <target_path>

将导出的日志存放在指定目录，在收集完成后也会打印日志存放的地址。

--logmodule <umd|firmware|kmd>

导出指定模块的日志。若未指定，默认导出KMD、UMD、Firmware所有日志。

-c/--continue

持续导出KMD、UMD、Firmware的日志及收集的环境信息，可配合 --logmodule 持续导出指定模块的日志。收集后的信息存放在当前目录下以“主机名_时间戳”命名的文件夹中。

由于环境信息是一次性收集完毕，请勿较早地使用Ctrl+C停止以免信息收集不全。

--set-fwlog-capacity <log file size, log files number>

持续导出日志时，设置Firmware单个日志文件的大小和日志文件的数量。若未设置，默认为20Mb，4个文件。

-p/--pack <target file folder>

将导出的日志文件夹打包。

备注

非持续导出时KMD日志文件是软链接。为保证打包的文件是软链接指向的源文件，推荐使用 mx-report -p 进行打包。
对于容器场景，一般不建议获取KMD日志，需要去对应物理机上获取。若确实需要在容器内获取KMD日志，需要在容器启动时将 /var/log 和 /proc 挂载到容器内部。

--dump-queue --pid xxx

当进程发生异常Hang住时，可导出异常进程的数据到当前目录下以pid命名的json文件中，以进一步分析。其中 pid 可通过 mx-smi --show-process 获取，可用 -i 指定设备，默认收集所有设备信息。

4.2.4.3. 日志级别操作选项

--show-loglevel

显示KMD、UMD所有运行中进程（ip: app, mcc, mcr, mxc, mctx, pti, prf, mxkw, mxs, mxvpu），Firmware（ip: smp0, smp1, ccx0, ccx1, ccx2及xcore）的日志级别。

--set-loglevel <moduleName,ipName,loglevel>

指定模块名和ip设置日志级别，其中ip可以设置为all，表示全部生效。

备注

如要对UMD进程进行日志级别查询和设置操作，需在启动UMD进程前设置环境变量 MACA_PATH 和 MCTX_TARGET_INIT=true （拉起rpc服务）。

4.2.4.4. 日志模块操作选项

--show-logmodule

查询板卡Firmware（ip: smp0, smp1, ccx0, ccx1, ccx2）日志模块的状态，默认为 00000001，即ip第一个模块的日志开关为打开状态。C588支持使用 --die 进行分die显示。

--set-logmodule <ipName,state>

设置指定ip日志模块状态： 1 为打开； 0 为关闭，关闭时不显示该模块日志。若设置 f，即为二进制1111，表示打开4个模块日志开关。C588支持使用 --die 进行分die显示。每个ip共28个日志模块（0~0fffffff）。本设置仅当Firmware该ip日志级别为 5:debug 时生效。

4.2.4.5. 环境信息收集

mx-report --get-envinfo

仅收集当前设备的环境信息，存放在当前目录下以“主机名_时间戳”命名的文件夹中。C588支持使用 --die 进行分die显示。其中：

envinfo.json以json格式存储所有环境信息；
envinfo.xlsx仅存储键值对形式的环境信息；
system_power_supply.txt存储系统电源信息；
topo_info.txt存储设备MetaXLink拓扑信息、PCIe信息以及NUMA信息等。

备注

由于部分信息收集需root权限才能获取，因此需以root权限运行收集命令。

在容器中收集环境信息需在启动时增加参数 --privileged -v /sys/kernel:/sys/kernel；如需同时收集日志信息，增加参数 -v /var/log:/var/log。推荐增加参数 --hostname <hostname>，使用 <container_ID>-主机名 以便知道收集的信息来自于哪个物理机。

4.2.4.6. 环境信息对比

两台服务器之间信息对比

mx-report --compare envinfo1.xlsx envinfo2.xlsx

excel各标签页对比信息如下：

Commoninfo：对比所有指标值存在的差异。
Server_info：对比服务器的指标值存在的差异（mem_used，mem_free，mem_buff，mem_available除外）。
Env_virable_info：根据工具已定义的环境变量列表进行对比：
- 均包含某个环境变量，但值不同。
- 一个服务器包含该环境变量，另外一个服务器不包含。
Pip_info：对所有的python安装包进行对比：
- 均包含某个安装包，但版本不同。
- 一个服务器有该安装包，另外一个服务器没有。
Device_info：对比设备的指标值存在的差异（board_type，board_sn除外）。

同一服务器不同设备之间信息对比

mx-report --compare envinfo.xlsx

服务器上GPU设备数量大于1时，会对比不同GPU设备指标差异。

Device_info：对比设备的指标值存在的差异（board_type，board_sn除外）。

4.2.4.7. 附加选项

-i ID, --index ID

指定板卡进行日志导出或日志级别查询和设置。如果没有指定，默认对全部板卡生效。 ID是从0开始的自然数，可以通过 -L， --list 获取板卡的ID信息。

--die DIE_ID

指定die进行日志导出。如果没有指定，默认对所有die生效。

--pid pid

当设置UMD的日志级别时（ moduleName 为 umd ）需要指定该参数，表示对指定pid进行操作， pid 为 all 时对所有进程生效。

当立即导出或持续导出日志时，添加该参数会同时收集与进程pid相关的内存使用数据，存放在子目录umd下的memInfo.csv文件中。

4.2.5. mx-report工具卸载

曦云系列GPU的驱动卸载后，mx-report工具会自动卸载。驱动卸载，参见《曦云^® 系列通用计算GPU驱动安装指南》中“卸载驱动”章节。

在Root权限环境中，也可以通过执行以下命令直接删除工作目录下的二进制执行文件来卸载mx-report工具。

sudo rm /opt/maca/bin/mx-report

4.3. mx-exporter工具

mx-exporter工具的详细介绍，请参见《曦云^® 系列通用计算GPU mx-exporter使用手册》和《曦云^® 系列通用计算GPU mx-exporter Kubernetes集群监控部署手册》。