# DCSM 用户手册

## 概述

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

## 前提条件

在主机上已安装 DCSM。具体的安装步骤，请参见[ DCSM 安装指南](https://docs.moffettai.com/moffett_docs/macs-1.6/installation/install_dcsm.html)。 安装 DCSM 后，mx-hostengine、dcsmi 的二进制文件位于`/usr/bin` 目录下。

## mx-hostengine 命令说明

提供监控设备的核心功能，以持久化的独立进程存在，并单实例部署在机器上，您可选择以下任一方式部署 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 --help`命令查看帮助信息。

```Bash
$ mx-hostengine --help
MOFFETT Data Center SPU Manager (DCSM)

Usage: mx-hostengine [OPTIONS]

Options:
  -h,--help                   Print this help message and exit
  --version                   Display program version information and exit
  -t,--term                   Terminates Host Engine Daemon [Best Effort]
  -p,--port <PORT>            Specify the port for the Host Engine. Default: 9494.
  -d,--domain-socket <SOCKET_PATH>
                              Specify the Unix domain socket path for host engine.
                              No TCP listening port is opened when this option is specified.
                                Default: /tmp/mx-hostengine
  -n,--no-daemon              Tell the host engine not to daemonize on start-up
  -b,--bind-interface <IP_ADDRESS>
                              Specify the IP address of the network interface that the host engine should listen on.
                                ALL = bind to all interfaces.
                                Default: 127.0.0.1.
  --log-level <LEVEL>         Specify the logging level. Default: ERROR
                                NONE  - Disable logging
                                FATAL - Set log level to FATAL only
                                ERROR - Set log level to ERROR and above
                                WARN  - Set log level to WARNING and above
                                INFO  - Set log level to INFO and above
                                DEBUG - Set log level to DEBUG and above
 -f,--log-filename <FILENAME>
                              Specify the filename mx-hostengine should use to dump logging information.
                              Default: /var/log/dcsm/mx-hostengine.log                              
```

参数说明如下：

| **参数**                         | **说明**                                                     | **示例**                                                     |
| -------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| -h,--help                        | 查看帮助信息。                                               | mx-hostengine --help                                         |
| --version                        | 查看 mx-hostengine 的版本信息。                              | mx-hostengine --version                                      |
| -t,--term                        | 终止作为守护进程 （daemon） 运行的 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                      | mx-hostengine 输出的日志级别：<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 --help`查看帮助信息。

```Bash
$ dcsmi --help
Data Center SPU Manager Interface
Usage: dcsmi [OPTIONS] SUBCOMMAND

Options:
  -h,--help                   Print this help message and exit
  --version                   Display program version information and exit

Subcommands:
  discovery                   Used to discover and identify SPUs and their attributes.
  group                       Used to create and maintain groups of SPUs. Groups of SPUs can then be uniformly controlled through other DCSMI subcommand.
  stats                       Used to view job statistics.
  diag                        Used to run diagnostics on the system. Only localhost is supported now.
```

### **子命令** discovery

用于发现和识别 SPU 设备及其属性信息。

参数说明如下：

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

### **子命令** group

以设备组（group）的形式去管控墨芯 SPU 设备，组中的设备可以通过 dcsmi 子命令的形式有效管控。

**说明**：*设备组作为用户自定义的设备集合，是 DCSM 中大部分操作的直接对象。通常先为任务作业对应的设备创建设备组，然后可以通过该设备组对任务相关的设备进行统一的管理和监控。*

*DCSM 初始化时会创建默认组（group 0），里面包含在宿主机中检测到的墨芯 SPU 设备，同一个设备也可以加入不同的设备组，您可按需配置。*

参数说明如下：

| **参数**                   | **说明**                                                     | **示例**                                                     |
| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| --host                     | 指定要连接访问的 mx-hostengine 的 IP 地址 或 Unix 域套接字路径默认访问本地（localhost），需和其他参数一起使用。 | 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 name>` 为名的空设备组，并返回 `group id`。    | dcsmi group --create test_group                              |
| -d,--delete <group id>     | 根据指定 `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. 执行 `dcsmi stats --enable --group <group id>`命令，为指定的组开启统计记录。您仅需在设备组初始化时执行一次该命令。
2. 执行 `dcsmi stats --jstart <job id> --group <group id>`  命令开始一次统计任务。
3. 执行 `dcsmi stats --jstop <job id>` 命令结束一次统计任务。
4. 任务结束后执行 `dcsmi stats --job <job id>`命令查看统计的聚合数据。

**说明**：

- *任务执行期间，DCSM 会收集默认的统计指标数据。*
- *如要复用 `<job id>`，请先执行 `dcsmi stats -r <job id>`命令，移除老的任务记录。*

参数说明如下：

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

### **子命令** diag

当前仅支持本地检测 SOLA 环境是否就绪。

参数说明如下：

| **参数** | **说明**                                                     | **示例**           |
| -------- | ------------------------------------------------------------ | ------------------ |
| -r,--run | 根据指定等级执行环境诊断任务，当前仅支持等级 1，检测 SOLA 环境是否就绪。 | dcsmi diag --run 1 |