# DCSM 用户手册

MOFFETT Data Center SPU Manager（DCSM）是用于管理和监控墨芯 SPU 设备的工具，方便在集群和数据中心环境中对设备的管理操作。DCSM 提供以下两种交互接口：

- `dcsmi`：用于管理和监控 SPU 性能与健康状态的命令行工具。
- DCSM Exporter：用于单机或 Kubernetes 环境下的集群级监控。它可导出 SPU 的指标和健康数据，用于实时监控与告警，具体请参见 [DCSM Exporter 用户手册](dcsm-exporter.md)。

## 部署 DCSM

### 前提条件

安装 SOLA Toolkit，具体请参见 [SOLA Toolkit 安装指南](../../installation/sola-toolkit-installation-guide.md)。

### 操作步骤

1. 获取 DCSM 安装包。

   ````{tabs}

   ```{tab} Ubuntu/Debian
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/dcsm/dcsm_1.2.0_amd64.deb
   ```
   ```{tab} RHEL/AliOS/KylinOS V10/Rocky Linux/openEuler
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/dcsm/dcsm-1.2.0-1.x86_64.rpm
   ```

2. 安装 DCSM。

   ```{admonition} 注意
   :class: caution

   使用 RPM 包安装 DCSM 时，确保 SOLA Toolkit 也使用 RPM 包安装，否则系统提示无法找到依赖的 `libsola.so` 包，导致安装失败。
   ```

   ````{tabs}
   ```{tab} Ubuntu/Debian
   ```bash
   sudo dpkg -i dcsm_1.2.0_amd64.deb
   ```

   ```{tab} RHEL/AliOS/KylinOS V10/Rocky Linux/openEuler
   ```bash
   sudo rpm -U dcsm-1.2.0-1.x86_64.rpm
   ```
   ````

3. 通过 systemd 启动 DCSM 服务，即启动 `mx-hostengine`。

   ```bash
   sudo systemctl --now enable dcsm
   ```

4. 安装后验证。
   
   a. 查看 DCSM 服务状态。如果服务正在运行，`dcsm.service` 状态显示为 `active (running)`。

      ```bash
      systemctl status dcsm
      ```

      ```bash
      # 以下为 Ubuntu 系统返回的 DCSM 服务状态示例
      ● dcsm.service - MOFFETT DCSM service
           Loaded: loaded (/lib/systemd/system/dcsm.service; enabled; vendor preset: enabled)
           Active: active (running) since Thu 2025-06-26 11:41:06 CST; 2s ago
         Main PID: 2043982 (mx-hostengine)
            Tasks: 5 (limit: 154137)
           Memory: 1.5M
              CPU: 46ms
           CGroup: /system.slice/dcsm.service
                   └─2043982 /usr/bin/mx-hostengine -n
      ```

   b. 通过 `dcsmi` 工具查询墨芯设备信息。如返回设备信息，表示 DCSM 安装成功。

      ```bash
      dcsmi discovery -l
      ```

## DCSM 主机引擎

DCSM 主机引擎（`mx-hostengine`）是设备监控的核心进程。在主机上安装 DCSM 后，其二进制文件位于 `/usr/bin` 目录。执行以下命令，将 `mx-hostengine` 注册为 systemd 服务，随 DCSM 服务启动，主机重启后会自动重启。

```bash
sudo systemctl --now enable dcsm
```

通过 systemd 方式启动 `mx-hostengine` 的相关配置由 `/usr/lib/systemd/system/dcsm.service` 文件指定，可根据实际情况需要修改，步骤如下：

1. 打开并修改 `dscm.service`。

   ```
   sudo vim /usr/lib/systemd/system/dcsm.service
   ```

   ```
   [Unit]
   Description=MOFFETT DCSM service

   [Service]
   User=root
   PrivateTmp=false

   ExecStart=/usr/bin/mx-hostengine -n # 启动 mx-hostengine 的命令，可选择配置下表所示的选项

   Restart=on-abort

   [Install]
   WantedBy=multi-user.target
   ```

   `mx-hostengine` 命令支持设置以下选项：

   :::nest-table
   | **选项**               | **说明**               |
   | --------------------- | ---------------------- |
   | -h,--help             | 显示帮助信息。   |
   | --version             | 显示 `mx-hostengine` 的版本信息。 |
   | -t,--term              | 尝试终止 `mx-hostengine` 守护进程（Best Effort）。      |
   | -p,--port *<port_number>*   | 指定监听的 TCP 端口号，默认值为 9494。用于客户端通过该端口访问 `mx-hostengine`。 |
   | -d,--domain-socket *<socket_path>*   | 指定 Unix 域套接字（Unix Domain Socket）路径作为通信通道，指定后不再启用 TCP 端口监听。默认路径为 `/tmp/mx-hostengine`。               |
   | -n,--no-daemon           | 不以守护进程方式启动 `mx-hostengine`。 |
   | -b,--bind-interface *<ip_address>*    |  指定监听的网络接口 IP 地址，默认为 localhost 或 127.0.0.1。如需实现被其他主机连接访问，设置为 all 或 0.0.0.0，即主机所有 IP 地址可被监听。|
   | --log-level                           |  指定日志级别，具体如下：<br />- NONE：关闭日志<br />- FATAL：仅记录致命错误<br />- ERROR（默认值）：记录错误及更高级别信息<br />- WARN：记录警告及更高级别信息<br />- INFO：记录一般信息、警告和错误<br />- DEBUG：记录所有调试信息 |
   | -f,--log-filename *<file_path>*       | 指定日志文件的输出路径，默认值 `/var/log/dcsm/mx-hostengine.log`。 |
   :::

2. 重新加载配置。

   ```
   sudo systemctl daemon-reload
   ```
   
3. 重启 DCSM 服务。

   ```
   sudo systemctl restart dcsm.service
   ```

另外，也可通过执行 `sudo mx-hostengine` 命令以守护进程方式手动启动 `mx-hostengine`。

## 使用 dcsmi 工具

`dcsmi` 是连接访问 `mx-hostengine` 的命令行工具，`dcsmi` 二进制文件位于 `/usr/bin` 目录。

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

-h,--help
: 显示帮助信息。

--version
: 显示工具的版本信息。

### 子命令 discovery

显示 SPU 设备信息。

**dcsmi discovery [选项]**

--host *<IP/FQDN>*
: 指定连接的主机 IP 地址或域名（Fully Qualified Domain Name，FQDN），默认值为 localhost。

  - 如需连接的主机可被访问，建议在启动 DCSM 服务时通过 -b 选项指定监听所有 IP 地址。
  - 如果连接的主机使用 `-d` 参数启动 `mx-hostengine`，需给套接字文件路径加上前缀 `unix://`。

-d,--device *<device_id>*
: 指定要查询的设备 ID，需和 `--info` 一起使用。

-g,--group *<group_id>*
: 指定要查询的设备组 ID，需和 `--info` 一起使用。关于设备组的详细说明请参见子命令 group。

-l,--list
: 列出所有墨芯 SPU 设备。

-i,--info
: 查询指定设备或设备组的信息，和 `--device` 或 `--group` 搭配使用。

**示例**

```
dcsmi discovery -l --host <ip_address>:<port_number> # 查询指定 IP 主机的设备信息
dcsmi discovery -l --host unix:///tmp/mx-hostengine
```

```
dcsmi discovery -i -d 0 # 查询 ID 为 0 的设备信息
dcsmi discovery -i -g 0 # 查询 ID 为 0 的组信息
```

### 子命令 group

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

**dcsmi group [选项]**

**通用选项**

-h,--help
: 显示帮助信息。

--host *<IP/FQDN>*
: 指定连接的主机 IP 地址或域名（Fully Qualified Domain Name，FQDN），默认值为 localhost。

  - 如需连接的主机可被访问，建议在启动 DCSM 服务时通过 -b 选项指定监听所有 IP 地址。
  - 如果连接的主机使用 `-d` 参数启动 mx-hostengine，需给套接字文件路径加上前缀 `unix://`。

-g,--group *<group_id>*
: 指定设备组 ID，和 `-i`、`-a`、`-r` 一起使用。

**功能选项（必选其一）**

-l,--list
: 列出当前所有的设备组。

-i,--info
: 显示指定设备组的信息。

-c,--create *<group_name>*
: 创建一个空设备组，并返回其 ID。组 ID 取决于先前创建的设备组，因此其值可能会有所不同。

-d,--delete *<group_id>*
: 删除指定的设备组。

-a,--add *<device_id1> [<device_id2> ...]*
: 为指定的设备组添加设备，可添加单个或多个设备。

-r,--remove *<device_id1> [<device_id2> ...]*
: 从指定的设备组移除设备，一次可移除单个或多个设备。

**示例**

```
dcsmi group -l --host 127.0.0.1:9494
dcsmi group -l --host unix:///tmp/mx-hostengine
```

```
dcsmi group -c test_group # 创建名为 test_group 的组，返回组 ID 为 1
dcsmi group -l
dcsmi group -g 1 -a 0 1 2 3
dcsmi group -g 1 -i 
dcsmi group -g 1 -r 1 3
dcsmi group -d 1
```

### 子命令 stats

对设备组中的设备进行后台数据监控及统计。

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

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

**dcsmi stats [选项]**

**通用选项**

-h,--help
: 显示帮助信息。

--host *<IP/FQDN>*
: 指定连接的主机 IP 地址或域名（Fully Qualified Domain Name，FQDN），默认值为 localhost。

  - 如需连接的主机可被访问，建议在启动 DCSM 服务时通过 -b 选项指定监听所有 IP 地址。
  - 如果连接的主机使用 `-d` 参数启动 `mx-hostengine`，需给套接字文件路径加上前缀 `unix://`。

-g,--group *<group_id>*
: 指定设备组 ID，用于启动、停止、查看统计记录，和 `-e`、`-s` 一起使用。

-i,--interval *<interval>*
: 指定统计指标（字段）采样间隔 (单位：ms)，和 `-e` 一起使用。

-m,--max-keep-age *<duration>*
: 指定统计指标（字段）最大保存时间（单位：s），和 `-e` 一起使用。

**功能选项（必选其一）**

-e,--enable
: 启动目标组的统计记录。。

-s,--jstart *<job_name>*
: 为指定设备组创建并开始一个监控统计任务。

-x,--jstop *<job_name>*
: 停止指定任务的监控统计任务。

-j,--job *<job_name>*
: 查看的监控统计任务信息。

-r,--jremove *<job_name>*
: 删除监控统计任务。

--jremoveall
: 删除全部统监控统计任务。

**示例**

```bash
dcsmi stats -e -g 1 # 为指定的设备（group 1）组启用统计功能
dcsmi stats -s test_job -g 1 # 启动统计任务
dcsmi stats -x test_job # 停止统计任务
dcsmi stats -j test_job #查看统计结果
```

### 子命令 diag

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

**dcsmi diag [选项]**

-h,--help
: 显示帮助信息。

-r,--run
: 指定环境诊断任务的等级。目前仅支持等级 1，即检测 SOLA 环境是否就绪。

**示例**

```bash
dcsmi diag -r 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
```

## 停用 DCSM

当更新 SOLA Toolkit 时，DCSM 服务会影响 SOLA Toolkit 卸载，根据 DCSM 服务启用的方式选择停用的命令：

- 当以系统服务方式启动 DCSM 服务时，执行以下命令：

  ```
  sudo systemctl --now disable dcsm
  ```

- 当以守护进程方式启动 `mx-hostengine` 时，执行以下命令：

  ```
  sudo mx-hostengine -t
  ```

## 卸载 DCSM

1. 暂停并禁用 DCSM 服务。

   ```bash
   sudo systemctl --now disable dcsm
   ```

2. 卸载 DCSM。

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

   执行卸载操作会移除 DCSM 软件包提供的所有文件，包括二进制可执行文件和库文件。
   ```

   ````{tabs}

   ```{tab} Ubuntu/Debian
   ```bash
   sudo dpkg -r dcsm
   ```
   ```{tab} RHEL/AliOS/KylinOS V10/Rocky Linux/openEuler
   ```bash
   sudo rpm -e dcsm
   ```