From 383ff0354a201ae7738f4419483487f0321f7d52 Mon Sep 17 00:00:00 2001 From: huangbin Date: Tue, 1 Jul 2025 21:05:15 +0800 Subject: [PATCH] docs: update quick start docs. --- docs/0.quickstart.md | 147 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/0.quickstart.md diff --git a/docs/0.quickstart.md b/docs/0.quickstart.md new file mode 100644 index 0000000..187a870 --- /dev/null +++ b/docs/0.quickstart.md @@ -0,0 +1,147 @@ +## 简介 + +sysTrace是一款运用于在AI训练任务中的软件，在AI训练中，常常出现训练任务故障导致训练成本浪费，业务痛点如下： + +- AI训练性能故障缺乏常态化监控、检测能力 +- Host bound引发的AI任务慢，卡故障缺乏全栈跟踪能力 + +sysTrace工具支持如下功能： + +- 采集torch_npu层的python函数的调用栈 +- 采集cann层的内存持有情况，判断是否发生HBM OOM故障 +- 采集mspti的通信算子下发/执行，判断是否发生算子慢的情况，从而定位到慢卡 +- 采集oncpu/offcpu事件，判断AI训练中是否存在其他进程抢占cpu导致训练慢的问题 + +### 环境 + +l**OS**： openEuler 22.03 (LTS-SP4) --5.10.0-60.18.0.50.oe2203.aarch64 + +l**软件版本**：CANN 8.0RC3, torch 2.1.0, torch_npu 2.1.0.post10 + +## 编译 + +- 下载源码： + +- systrace编译源码： + + ```shell + ## 安装依赖包 + [root@localhost sysTrace] yum install gcc g++ cmake make python3-devel protobuf-compiler protobuf-devel protobuf-c-devel libbpf clang libbpf-devel bpftool + [root@localhost sysTrace] cd sysTrace + [root@localhost sysTrace] bash build.sh + ## 编译产物均在build目录下，会用到libsysTrace.so和sysTrace_cli + [root@localhost build]# ll + total 1776 + -rw-r--r--. 1 root root 17000 Jun 12 16:58 CMakeCache.txt + drwxr-xr-x. 7 root root 4096 Jun 12 17:10 CMakeFiles + -rw-r--r--. 1 root root 1798 Jun 12 16:58 cmake_install.cmake + -rw-r--r--. 1 root root 534270 Jun 12 17:10 libcommon.a + -rwxr-xr-x. 1 root root 1209296 Jun 12 17:10 libsysTrace.so + -rw-r--r--. 1 root root 20479 Jun 12 17:10 Makefile + drwxr-xr-x. 3 root root 4096 Jun 12 17:10 protos + -rwxr-xr-x. 1 root root 76736 Jun 12 17:10 sysTrace_cli + ``` + +## 使用 + +### 数据采集 + +修改AI训练任务脚本，使用LD_PRELAOD的方式将动态库加载到AI训练任务中 + +```shell +LD_PRELOAD=/usr/local/lib/libunwind.so.8.2.0:/usr/local/lib/libunwind-aarch64.so.8.2.0:/home/ascend-toolkit-bak/ascend-toolkit/8.0.RC3.10/tools/mspti/lib64/libmspti.so:/systrace/build/libsysTrace.so python ... +``` + +**注意：以LD_PRELOAD的方式加载了/usr/local/lib/libunwind.so.8.2.0:/usr/local/lib/libunwind-aarch64.so.8.2.0的原因是因为低于1.7版本的libunwind有bug，需要手动下载最新版本的libunwind，如果环境中的libunwind版本大于等于1.7，则使用以下命令** + +```shell +LD_PRELOAD=/home/ascend-toolkit-bak/ascend-toolkit/8.0.RC3.10/tools/mspti/lib64/libmspti.so:/systrace/build/libsysTrace.so python ... +``` + +### 动态开关 + +sysTrace支持动态开启采集数据，采集数据类型支持动态开启，sysTrace提供二进制工具sysTrace_cli，当前L0数据是常态开启，L1/2/3类型数据可自行决定是否开启，使用命令如下： + +```shell +[root@localhost ~]# sysTrace_cli help +Usage: sysTrace_client [args] +Commands: + set = - Enable/disable dump level + (levels: L0, L1, L2, L3) + interval = - Set dump interval in minutes + (levels: L1, L2, L3) + print [level|all] - Print current settings + (levels: L0, L1, L2, L3, all) + +Examples: + sysTrace_cli set L1=true + sysTrace_cli interval L1=10 + sysTrace_cli print all +``` + +### 数据落盘 + +所有采集的数据当前存放在`/home/sysTrace`目录下，每张卡上的数据以独立一个文件保存，集群多节点环境，建议将保存目录`/home/sysTrace`映射到共享目录，否则需要手动将每台节点上的数据手动拷贝，如下： + +```shell +[root@localhost sysTrace]# ll +drwxr-xr-x. 2 root root 4096 Jun 12 17:01 cann ##内存数据 +drwxr-xr-x. 2 root root 4096 Jun 12 17:01 mspti ##通信算子数据 +drwxr-xr-x. 2 root root 4096 Jun 12 17:01 timeline ##torch_npu层数据 +drwxr-xr-x. 2 root root 4096 Jun 12 17:01 osprobe ##offcpu/cpu事件 +``` + +### 数据转换 + +```shell +##转换内存oom数据 +#拷贝sysTrace_pb2.py到convert目录下，确保该文件和转化脚本在一个目录下 +cp /sysTrace/protos/sysTrace_pb2.py /sysTrace/convert +python /sysTrace/convert/convert_mem_to_flamegraph_for_cur.py + +##转换torch_npu数据 +cd /home/sysTrace/timeline +python /sysTrace/convert/convert_pytorch_to_timeline.py --output + +##转换通信算子数据 +python /sysTrace/convert/convert_mspti_timeline.py + +##转换offcpu/oncpu事件 +cd /home/sysTrace/osprobe +python /sysTrace/convert/convert_osprobe_to_timeline.py --output + +``` + +### 数据展示 + +将最终的json数据上传到并展示, 通过**Open trace file**加载数据。 + +### 数据分析 + +failslow算法包安装： + +```shell +##安装 +python setup.py install +``` + +性能劣化感知算法执行： + +```shell +## L0感知 +python failslow/fail_slow_detection.py +``` + +慢卡定界算法执行： + +```shell +## L1定界 +systrace-failslow +## 或者 +python failslow/main.py +``` + +**注意：算法执行前，需[参考文档](https://gitee.com/openeuler/sysTrace/blob/master/failslow/docs/conf_introduction.md)配置对应的数据路径** + +## + -- Gitee