# DCSM 用户手册

介绍 DCSM 提供的命令功能、参数及使用过程中的注意事项。

## 前提条件

已安装 DCSM，具体请参见 [DCSM 安装指南](./install_dcsm)。安装完成后，`mx-hostengine` 和 `dcsmi` 二进制文件将位于 `/usr/bin` 目录。

## 使用 mx-hostengine

`mx-hostengine` 是设备监控的核心进程，以单实例守护进程方式运行，常驻系统中。可通过以下任一方式部署：

| **部署方式**                | **启动命令**                     | **停止命令**                      | **说明**                                              |
| --------------------------- | -------------------------------- | --------------------------------- | ----------------------------------------------------- |
| systemd service（推荐）     | sudo systemctl --now enable dcsm | sudo systemctl --now disable dcsm | 注册为 systemd 服务并启动，在服务器重启后会自动重启。 |
| daemon mode                 | sudo mx-hostengine               | sudo mx-hostengine -t             | 以守护进程方式启动。                                  |

 **命令格式：mx-hostengine [选项]**，支持的选项如下表所示：
 
| **选项**                         | **说明**                                                     | **示例**                                                     |
| -------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| -h,--help                        | 查看帮助信息。                                               | mx-hostengine --help                                         |
| --version                        | 查看 mx-hostengine 的版本信息。                              | mx-hostengine --version                                      |
| -t,--term                        | 终止作为守护进程运行的 mx-hostengine 进程。执行相应命令时需要 root 权限读取守护进程的 pidfile，而不会对非守护进程的 mx-hostengine 进行修改。 | sudo mx-hostengine --term    |
| -p,--port `<PORT>`                 | 指定监听的 TCP 端口，默认值为 9494。   | sudo mx-hostengine --port 6666                               |
| -d,--domain-socket `<SOCKET_PATH>` | mx-hostengine 用于 Unix socket 通信的路径，默认路径为`/tmp/mx-hostengine`。与 TCP 通信方式互斥，默认不使用 Unix socket 通信方式。 | sudo mx-hostengine --domain-socket<br />sudo mx-hostengine -d /tmp/mysocket |
| -n,--no-daemon                   | 不以守护进程的形式启动 mx-hostengine 进程，以这种方式启动的进程需要用户手动管理退出。 | mx-hostengine --no-daemon                                    |
| -b,--bind-interface `<IP_ADDRESS>` | 指定监听的 IP 地址，默认地址为 127.0.0.1。默认情况下仅允许本地连接进行通信，如需绑定所有可用的 IP 地址，可设置该参数为 `ALL`。 | sudo mx-hostengine --bind-interface 127.0.0.1 <br />sudo mx-hostengine --bind-interface ALL |
| --log-level                      | 日志级别：<br /> - NONE：不记录日志<br /> - FATAL：只打印致命错误日志<br /> - ERROR（默认值）：打印错误及更高级别错误日志<br /> - WARN：打印警告及更高级别错误日志<br /> - INFO：打印信息及更高级别错误日志<br /> - DEBUG：打印调试信息及更高级别错误日志 | sudo mx-hostengine --log-level FATAL                         |
| -f,--log-filename `<FILENAME>`     | 指定日志保存的路径，默认路径为 `/var/log/dcsm/mx-hostengine.log`。 | sudo mx-hostengine --log-filename mx-hostengine.log          |

## 使用 dcsmi

`dcsmi` 是 DCSM 的命令行工具，用来连接访问 `mx-hostengine`，并返回调用结果。通过 `dcsmi`，可以简便地使用 `mx-hostengine`（本地或远端）的各项功能。

**命令格式：dcsmi [选项] 子命令**
- `-h,--help`：显示帮助信息。
- `--version`：显示工具的版本信息。

### 子命令 discovery

显示 SPU 设备信息。

**命令格式：dcsmi discovery [选项]**

| **选项**                | **说明**                                                     | **示例**                                                     |
| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| --host `<IP/FQDN>`        | 指定要连接访问的 mx-hostengine 的 IP 地址 或 Unix 域套接字路径，默认访问本地地址（localhost）。<br />需和其他参数一起使用。 | dcsmi discovery -l --host 127.0.0.1:9494<br />dcsmi discovery -l --host unix:///tmp/mx-hostengine |
| -d,--device <device id> | 指定要查询的设备 ID，需和 `--info` 一起使用。                | dcsmi discovery --info --device 0                            |
| -g,--group `<group_id>`   | 指定要查询的设备组 ID，需和 `--info` 一起使用。<br />DCSM 初始化时会创建默认组（group 0），包含在宿主机中检测到的墨芯 SPU 设备。<br />单个设备可加入不同的设备组。 | dcsmi discovery --info --group 0                             |
| -l,--list               | 列出识别到的墨芯 SPU 设备。                                  | dcsmi discovery -l <br />dcsmi discovery --list              |
| -i,--info               | 查询指定设备或设备组的信息，和 `--device` 或 `--group` 搭配使用。 | dcsmi discovery --info --device 0<br />dcsmi discovery --info --group 0 |

### 子命令 group

以设备组的形式管理墨芯 SPU 设备。

设备组是用户自定义的设备集合，是 DCSM 多数操作的作用对象。通常用户可为每个任务作业创建对应的设备组，以便统一管理和监控相关设备。DCSM 初始化时会自动创建默认设备组（group 0），包含主机上检测到的所有 SPU 设备。单个设备可同时加入多个设备组。

**命令格式：dcsmi group [选项]**

| **参数**                   | **说明**                                                     | **示例**                                                     |
| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| --host `<IP/FQDN>`        | 指定要连接访问的 mx-hostengine 的 IP 地址 或 Unix 域套接字路径，默认访问本地地址（localhost）。<br />需和其他参数一起使用。 | dcsmi group -l --host 127.0.0.1:9494<br />dcsmi group -l --host unix:///tmp/mx-hostengine |
| -g,--group `<group_id>`      | 指定设备组 ID，和 `--info`、`--add`、`--remove` 一起使用。 | dcsmi group --group 0 --add 0 1 2 3                          |
| -l,--list                  | 列出当前所有的设备组。                                       | dcsmi group --list                                           |
| -i,--info                  | 显示指定设备组的信息。                                       | dcsmi group --info --group 0                                 |
| -c,--create `<group_name>`   | 创建一个空设备组，并返回其 `<group_id>`。    | dcsmi group --create test_group                              |
| -d,--delete `<group_id>`     | 删除指定的设备组。                              | dcsmi group --delete 1                                       |
| -a,--add `<device id>`...    | 为指定的设备组添加设备，可添加单个或多个设备。               | dcsmi group --group 1 --add 0 1 2 3                          |
| -r,--remove `<device id>`... | 从指定的设备组移除设备，一次可移除单个或多个设备。           | dcsmi group --group 1 --remove 1 3                           |

### 子命令 stats

对设备组中的设备进行后台数据监控及数据统计，步骤如下：

1. 为指定的设备组启用统计功能（仅需在设备组初始化时执行一次）。

   ```Bash
   dcsmi stats --enable --group <group_id>
   ```

2. 启动统计任务。

   ```Bash
   dcsmi stats --jstart <job_name> --group <group_id>
   ```

3. 停止统计任务。

   ```Bash
   dcsmi stats --jstop <job_name>
   ```

4. 查看统计结果。

   ```Bash
   dcsmi stats --job <job_name>
   ```

```{admonition} 须知
:class: note

任务执行期间，DCSM 会持续收集默认统计指标。若需重复使用相同的 `<job_name>`，请先通过 `dcsmi stats -r <job_name>` 命令移除旧任务记录。
```

**命令格式：dcsmi stats [选项]**

| **参数**                     | **说明**                                                     | **示例**                                                     |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| --host `<IP/FQDN>`             | 指定要连接访问的 mx-hostengine 的 IP 地址 或 Unix 域套接字路径，默认访问本地（localhost）。<br />需和其他参数一起使用。 | dcsmi stats --job job1 --host 127.0.0.1:9494<br />dcsmi stats --job job1 --host unix:///tmp/mx-hostengine |
| -g,--group `<group_id>`        | 指定设备组 ID，用于启动、停止、查看统计记录，和 `--enable`、`--jstart` 一起使用。 |        参见 `--enable` 的示例                          |
| -i,--interval `<interval>`     | 指定统计指标（字段）采样间隔 (单位：ms)，和 `--enable` 一起使用。 |      参见 `--enable` 的示例                                                  |
| -m,--max-keep-age `<duration>` | 指定统计指标（字段）最大保存时间（单位：s），和 `--enable` 一起使用。 |    参见 `--enable` 的示例                                     |
| -e,--enable                  | 启动目标组的统计记录。                                       | dcsmi stats --enable --group 0 --interval 30000 --max-keep-age 3600 |
| -s,--jstart `<job_name>`         | 为指定设备组创建并开始一个监控统计任务。 | dcsmi stats --jstart job1 --group 0                          |
| -x,--jstop `<job_name>`          | 停止指定任务的监控统计任务。                                         | dcsmi stats --jstop job1                                     |
| -j,--job `<job_name>`            | 查看的监控统计任务信息。                                     | dcsmi stats --job job1                                       |
| -r,--jremove `<job_name>`        | 删除监控统计任务。                                           | dcsmi stats --jremove job1                                   |
| --jremoveall                 | 删除全部统监控统计任务。                                     | dcsmi stats --jremoveall                                     |

### 子命令 diag

执行环境诊断任务。目前仅支持本地检测 SOLA 环境是否就绪。

**命令格式：dcsmi diag [选项]**
- `-h,--help`：显示帮助信息。
- `-r,--run`：执行指定等级的环境诊断任务。目前仅支持等级 1，即检测 SOLA 环境是否就绪。

```Bash
dcsmi diag --run 1
```
```
MOFFETT Validation Suite (version 1.2.0)

    Software
        DenyList .......................................... PASS
        SOLA Library ...................................... PASS
        MXML Library ...................................... PASS
        Driver ............................................ PASS
        Permissions and OS-related Blocks ................. PASS
        Persistence Mode .................................. PASS
        Environmental Variables ........................... PASS
```