使用 atlctl 进行原地调试

AIStudio 任务功能提供 atlctl 命令行调试工具，您可以从 Web Terminal 登录任意的任务 Worker，执行停止任务、统一下发测试命令等调试工作。

了解调试状态

atlctl 命令行调试工具可手动控制任务的生命周期。运行中的任务在生命周期中的部分状态下，可被手动设置为调试（Debug）状态。在调试状态下，允许用户对所有任务 Worker 统一发起检测，或下发测试命令等。调试结束后，可恢复任务执行。

进入调试状态

必须从网页端登录任务 Worker。打开 Web Terminal 后，可直接使用 atlctl 工具。

Worker 登录入口在任务详情页 Worker 信息中，点击登录后可打开 Web Terminal。

注意

仅在任务运行中时可登录 Worker。

使用流程

以下提供两个使用流程范例：

• 执行 atlctl 工具内置检测
• 执行用户自定义检测脚本

执行内置检测脚本

atlctl 工具内置了 GPU 与通信检测脚本，默认可对任务中的全部 Worker 进行检测 GPU 和通讯检测。支持通过添加参数检测具体项目和自定义的临时环境变量。

登录任务的任意一个 Worker，按下方步骤操作：

1. 查看训练任务状态。如果输出 Job status 为 command，表示当前仍在执行任务中的用户代码。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
   Job status:  command

2. 为了执行检测，需要先停止当前训练任务，将任务置于 Debug 状态。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
   Stopping task in all workers...
   Stop job task success.

3. 建议检查当前任务是否有 python 进程残留，如有则清理。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl run "ps -ef |grep python |grep -v grep |grep -v tini |awk '{print \$2}'|xargs kill -9"
   Send command to all workers success.

   每次执行 atlctl run 后，必须执行 atlctl stop，否则无法再次下发其他 atlctl 命令。

   atlctl stop

4. 执行 atlctl 工具内置检测脚本。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl check
   All workers will be checked.
   Check finished.
   Check Quit.

   检查结束，未发现问题，可终止检测。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
   Stopping task in all workers...
   Stop job task success.

5. 如需恢复任务运行，请先查看训练任务是否处于 debugStop 状态。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
   Job status:  debugStop

6. 如果任务状态已处于 debugStop 状态，可恢复训练任务：

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
   Job status:  debugStop
   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl recover
   Task recovering...
   Task recover success.

执行自定义调试命令

自定义的流程与执行内置检测主流程类似，区别仅在于使用 atlctl run 下发自定义检测命令。

登录任务的任意一个 Worker，按下方步骤操作：

1. 查看训练任务状态。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
   Job status:  command

   输出 Job status 为 command 表示正在执行任务中的启动命令。

2. 停止当前训练任务，将任务置于 Debug 状态。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
   Stopping task in all workers...
   Stop job task success.

3. 建议检查当前任务是否有 python 进程残留，如有则清理。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl run "ps -ef |grep python |grep -v grep |grep -v tini |awk '{print \$2}'|xargs kill -9"
   Send command to all workers success.

   每次执行 atlctl run 后，必须执行 atlctl stop，否则无法再次下发其他 atlctl 命令。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
   Stopping task in all workers...
   Stop job task success.

4. 执行自定义测试命令。如有多个命令需要连续运行，建议封装为 Shell 脚本。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl run "/mnt/public/debug/test-comms.sh"

   调试结束，终止测试任务：

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
   Stopping task in all workers...
   Stop job task success.

5. 如需恢复任务运行，请先查看训练任务是否处于 debugStop 状态。

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
   Job status:  debugStop

6. 如果任务状态已处于 debugStop 状态，可恢复训练任务：

   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
   Job status:  debugStop
   root@jo-daxbirgzm6e727pd-worker-0:~# atlctl recover
   Task recovering...
   Task recover success.

命令说明

atlctl 工具提供以下命令：

status

atlctl status 用于查看当前任务的生命周期的状态。仅当任务处于 debugStop 状态下才能执行其他调试命令。

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  debugStop

stop

atlctl stop 停止执行训练任务代码，将任务置于 Debug 状态，可通过 atlctl status 确认执行结果。

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

重要

每次执行 atlctl run/atlctl check 命令后，也必须执行 atlctl stop 终止调试任务，否则无法再次下发检测命令。

check

atlctl run check 运行内置检测，作用于任务所有 Worker。内置检测脚本默认将对任务中的全部 Worker 进行检测 GPU 和通讯检测。

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl check
All workers will be checked.
Check finished.
Check Quit.

如需控制检测范围，可参考以下参数。

选项：

• -t, --checkType string：自定义检测范围。默认全部检测（gpu/通讯）。选项：

  • gpu: 执行与 GPU 相关的检查。
  • allreduce: 执行与 allreduce 操作相关的检查。
  • all: 执行所有可用的检查。（默认值："all"）

• -e, --envs string：添加自定义环境变量。默认为空。输入格式如下：

  • key1=value1：设置单个环境变量
  • "key2=value2;key1=value1a,value1b;..."：键值对用 ; 分隔。一个键如果有多个值，用 , 分割。

  # 设置单个环境变量
  atlctl check -t gpu -e tt123=123
  # 设置多个环境变量
  atlctl check -t gpu -e "tt123=123;tt456=456,457"

• -h, --help：显示 check 命令的帮助信息。

• -w, --workerList string：自定义参与检测的 worker 范围。默认为全部。选项：

  • all: 检查所有可用的工作节点。
  • jo-xxx-worker1,jo-xxx-worker2: 通过提供逗号分隔的工作节点名称列表来检查特定的工作节点。（默认值："all"）

run

atlctl run "<command>" 下发并运行自定义调试命令，该调试命令将在任务所有 Worker 上运行。由于 atlctl run 不支持连续执行，建议在 <command> 中拼接多个 Shell 命令。推荐使用 Shell 脚本封装复杂调试命令。例如：

atlctl run "/mnt/public/debug/test-comms.sh"

recover

atlctl recover： 在调试结束后，恢复执行训练任务的用户代码。

注意

以上命令不会占用任务的容错次数。