# DCSM Exporter 用户手册

## 概述

DCSM Exporter 是基于 DCSM （MOFFETT Data Center SPU Manager） 实现的工具，它使用户能够采集并导出墨芯 AI 计算卡的指标数据，这些数据遵循 Prometheus 兼容的格式。该工具支持在单机或集群环境中对墨芯 AI 计算卡的工作负载和健康状态进行实时监控，从而提升了系统的可观测性。

## 前提条件

在使用 DCSM Exporter 前，需满足以下前提条件：

- 服务器已安装墨芯 AI 计算卡（例如 S30）， 能被系统正确识别。
- 服务器已安装 SOLA ToolKit，且安装的 SOLA ToolKit 的版本>= 3.11.0。
- 产测环境已部署 Prometheus 和 Grafana。
- 服务器已部署 Kubernetes 集群， Prometheus/Grafana 接入集群。

## 部署 DCSM Exporter

您可以将 DCSM Exporter 作为独立容器运行，也可通过 Daemonset 部署在 Kubernetes 集群中的墨芯设备节点。

### 获取 DCSM Exporter 镜像

我们提供了 DCSM Exporter 在线镜像和离线镜像，您可以按需取用。

- 在线版镜像

  ```Bash
  $ docker pull moffett/dcsm-exporter:1.1.0-1.0.0
  $ docker images | grep dcsm-exporter
  ```

- 离线版镜像

  ```Bash
  $ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/images/Ubuntu/business/dcsm/dcsm-exporter_1.1.0-1.0.0.tar
  $ docker load -i dcsm-exporter_1.1.0-1.0.0.tar
  $ docker images | grep dcsm-exporter
  ```

### 部署 DCSM Exporter

#### 单机容器化部署

执行以下命令，创建容器，完成镜像单机容器化部署。

```Bash
#sample:默认参数容器示例
$ docker run -d \
       --privileged \
       --net=host \
       --name=dcsm-exporter \
       moffett/dcsm-exporter:1.1.0-1.0.0 

#sample：自定义参数容器示例。
# -f 参数指定默认配置文件 /etc/dcsm-exporter/default-counters.csv
$ docker run -d \
       --privileged \
       --net=host \
       --name=dcsm-exporter \
       moffett/dcsm-exporter:1.1.0-1.0.0 \
       -f /etc/dcsm-exporter/default-counters.csv \
       -c 15000 -a :7788 -d all
```

- 命令行参数解析：
  在容器创建并启动时，既可按默认值来设定参数项；也可通过传入命令行参数或环境变量来自定义所需的功能 项。您可以根据实际需要自定义指定参数项或环境变量。命令行参数和环境变量说明详见下表：

  | **命令行参数**                 | **环境变量**                      | **说明**                                                     | **默认值**                                          |
  | ------------------------------ | --------------------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
  | --collectors -f                | DCSM_EXPORTER_COLLECTORS          | 包含要收集的 DCSM 字段的文件的路径                           | /etc/dcsm-exporter/default-counters.csv             |
  | --collect-interval  -c         | DCSM_EXPORTER_INTERVAL            | 收集指标的时间间隔，单位：毫秒（ms）                         | 30000                                               |
  | --address value  -a            | DCSM_EXPORTER_LISTEN              | http 服务的监听地址                                          | 7788                                                |
  | --remote-hostengine-info  -r   | DCSM_REMOTE_HOSTENGINE_INFO       | 以 Host:Port 的格式指定要连接的 mx-hostengine 使用此参数，<br />dcsm-exporter 将通过指定的 mx-hostengine 进行指标收集 | 无，需显式指定，未指定则 dcsm-exporter 自行收集指标 |
  | --devices -d                   | DCSM_EXPORTER_DEVICES_STR         | 指定要监控的 device，支持语法示例如下：<br /> all<br /> 0,1<br /> 2-4 <br />0,2-4 | all                                                 |
  | --kubernetes -k                | DCSM_EXPORTER_KUBERNETES          | 将设备对应的 kubernetes pod 信息加入指标标签                 | FALSE                                               |
  | --pod-resources-kubelet-socket | DCSM_POD_RESOURCES_KUBELET_SOCKET | kubelet pod-resources 套接字文件的路径                       | /var/lib/kubelet/pod-resources/kubelet.sock         |

- 采集指标数据解析：
  DCSM Exporter 采集配置文件 default-counter.csv 中定义的指标数据。
  配置文件 default-counter.csv 下载链接：https://moffett-oss-bucket.tos-cn-shanghai.volces.com/dcsm/default-counters.csv。
  default-counters.csv 文件内容如下所示：
```yaml
# Format
# If line starts with a '#' it is considered a comment
# DCSM FIELD, Prometheus metric type, help message

# Clocks
DCSM_FI_DEV_NNCORE_CLOCK, gauge, NNCORE clock frequency (in MHz).

# Temperature
DCSM_FI_DEV_SPU_TEMP, gauge, SPU temperature (in C).

# Power
DCSM_FI_DEV_POWER_USAGE, gauge, Power draw (in W).

# PCIE
DCSM_FI_DEV_PCIE_TX_THROUGHPUT, counter, Total number of bytes transmitted through PCIe TX (in KB) via MXML.
DCSM_FI_DEV_PCIE_RX_THROUGHPUT, counter, Total number of bytes received through PCIe RX (in KB) via MXML.

# Utilization
DCSM_FI_DEV_SPU_UTIL,      gauge, SPU utilization (in %).
DCSM_FI_DEV_MEM_COPY_UTIL, gauge, Memory utilization (in %).

# Errors and violations
DCSM_FI_DEV_XID_ERRORS, gauge, Value of the last XID error encountered.

# Memory usage
DCSM_FI_DEV_DDR_FREE, gauge, DDR memory free (in MB).
DCSM_FI_DEV_DDR_USED, gauge, DDR memory used (in MB).

# ECC
# DCSM_FI_DEV_ECC_SBE_VOL_TOTAL, counter, Total number of single-bit volatile ECC errors.
# DCSM_FI_DEV_ECC_DBE_VOL_TOTAL, counter, Total number of double-bit volatile ECC errors.
# DCSM_FI_DEV_ECC_SBE_AGG_TOTAL, counter, Total number of single-bit persistent ECC errors.
# DCSM_FI_DEV_ECC_DBE_AGG_TOTAL, counter, Total number of double-bit persistent ECC errors.

# Static configuration information. These appear as labels on the other metrics
DCSM_FI_DEV_SERIAL,     label, Device Serial Number
DCSM_FI_DRIVER_VERSION, label, Driver Version
# DCSM_FI_MXML_VERSION, label, MXML Version
# DCSM_FI_SOLA_VERSION, label, SOLA Verison
```

DCSM Exporter 支持的 metrics 指标数据如下表所示， 您可按需灵活调整 ：         

| **支持的 DCSM 字段**           | **Prometheus 指标类型**                   | **描述**                                                  |
| ------------------------------ | ----------------------------------------- | --------------------------------------------------------- |
| DCSM_FI_DEV_NNCORE_CLOCK       | gauge                                     | NNCORE 的时钟频率，单位：Mhz                              |
| DCSM_FI_DEV_SPU_TEMP           | gauge                                     | SPU （sprase processing unit，稀疏处理单元）温度，单位：℃ |
| DCSM_FI_DEV_POWER_USAGE        | gauge                                     | 功耗，单位： W                                            |
| DCSM_FI_DEV_PCIE_TX_THROUGHPUT | counter                                   | 通过 MXML 传输的 PCIe TX 总字节数 ，单位： KB             |
| DCSM_FI_DEV_PCIE_RX_THROUGHPUT | counter                                   | 通过 MXML 接收的 PCIe RX 总字节数 ，单位 ：KB             |
| DCSM_FI_DEV_SPU_UTIL           | gauge                                     | SPU 利用率，以百分比格式表示                                  |
| DCSM_FI_DEV_MEM_COPY_UTIL      | gauge                                     | 内存利用率 ，以百分比格式表示                                 |
| DCSM_FI_DEV_XID_ERRORS         | gauge                                     | 最后出现的 XID 错误码                                     |
| DCSM_FI_DEV_DDR_FREE           | gauge                                     | DDR 空闲内存，单位： MB                                   |
| DCSM_FI_DEV_DDR_USED           | gauge                                     | DDR 已用内存，单位： MB                                   |
| DCSM_FI_DEV_ECC_SBE_VOL_TOTAL  | counter                                   | 单比特瞬态 ECC 错误总数                                   |
| DCSM_FI_DEV_ECC_DBE_VOL_TOTAL  | counter                                   | 双比特瞬态 ECC 错误总数                                   |
| DCSM_FI_DEV_ECC_SBE_AGG_TOTAL  | counter                                   | 单比特持久 ECC 错误总数                                   |
| DCSM_FI_DEV_ECC_DBE_AGG_TOTAL  | counter                                   | 双比特持久 ECC 错误总数                                   |
| DCSM_FI_DEV_ECC_SBE_VOL_L1     | counter                                   | L1 缓存单比特瞬态 ECC 错误数                              |
| DCSM_FI_DEV_ECC_SBE_VOL_L2     | counter                                   | L2 缓存单比特瞬态 ECC 错误数                              |
| DCSM_FI_DEV_ECC_SBE_VOL_DEV    | counter                                   | 设备内存单比特瞬态 ECC 错误数                             |
| DCSM_FI_DEV_ECC_SBE_VOL_REG    | counter                                   | 寄存器文件单比特瞬态 ECC 错误数                           |
| DCSM_FI_DEV_ECC_DBE_VOL_L1     | counter                                   | L1 缓存双比特瞬态 ECC 错误数                              |
| DCSM_FI_DEV_ECC_DBE_VOL_L2     | counter                                   | L2 缓存双比特瞬态 ECC 错误数                              |
| DCSM_FI_DEV_ECC_DBE_VOL_DEV    | counter                                   | 设备内存双比特瞬态 ECC 错误数                             |
| DCSM_FI_DEV_ECC_DBE_VOL_REG    | counter                                   | 寄存器文件双比特瞬态 ECC 错误数                           |
| DCSM_FI_DEV_ECC_SBE_AGG_L1     | counter                                   | L1 缓存单比特持久 ECC 错误数                              |
| DCSM_FI_DEV_ECC_SBE_AGG_L2     | counter                                   | L2 缓存单比特持久 ECC 错误数                              |
| DCSM_FI_DEV_ECC_SBE_AGG_DEV    | counter                                   | 设备内存单比特持久 ECC 错误数                             |
| DCSM_FI_DEV_ECC_SBE_AGG_REG    | counter                                   | 寄存器文件单比特持久 ECC 错误数                           |
| DCSM_FI_DEV_ECC_DBE_AGG_L1     | counter                                   | L1 缓存双比特持久 ECC 错误数                              |
| DCSM_FI_DEV_ECC_DBE_AGG_L2     | counter                                   | L2 缓存双比特持久 ECC 错误数                              |
| DCSM_FI_DEV_ECC_DBE_AGG_DEV    | counter                                   | 设备内存双比特持久 ECC 错误数                             |
| DCSM_FI_DEV_ECC_DBE_AGG_REG    | counter                                   | 寄存器文件双比特持久 ECC 错误数                           |
| DCSM_FI_DEV_SERIAL             | label（静态指标，作为标签添加到其他指标） | 设备序列号（Serial Number， SN）                          |
| DCSM_FI_DRIVER_VERSION         | label（静态指标，作为标签添加到其他指标） | 驱动版本                                                  |
| DCSM_FI_MXML_VERSION           | label（静态指标，作为标签添加到其他指标） | MXML 版本                                                 |
| DCSM_FI_SOLA_VERSION           | label（静态指标，作为标签添加到其他指标） | SOLA 版本                                                 |

#### Kubenetes 集群中部署

DCSM Exporter 通过 YAML 配置文件创建 DaemonSet 和 Service 将其部署到 Kubernetes 集群中。  

1. 创建 namespace。

   ```Bash
   $ kubectl create ns moffett-monitoring
   ```

2. 创建 dcsm-exporter.yaml 部署文件。

   ```YAML
   # dcsm-exporter.yaml
   apiVersion: apps/v1
   kind: DaemonSet
   metadata:
     name: "dcsm-exporter"
     namespace: "moffett-monitoring"
     labels:
       app.kubernetes.io/name: "dcsm-exporter"
       app.kubernetes.io/version: "1.0.0"
   spec:
     updateStrategy:
       type: RollingUpdate
     selector:
       matchLabels:
         app.kubernetes.io/name: "dcsm-exporter"
         app.kubernetes.io/version: "1.0.0"
     template:
       metadata:
         labels:
           app.kubernetes.io/name: "dcsm-exporter"
           app.kubernetes.io/version: "1.0.0"
         name: "dcsm-exporter"
       spec:
         containers:
         - name: "dcsm-exporter"
           image: "moffett/dcsm-exporter:1.1.0-1.0.0"
           env:
           - name: "DCSM_EXPORTER_LISTEN"
             value: ":7788"
           - name: "DCSM_EXPORTER_KUBERNETES"
             value: "true"
           - name: "DCSM_EXPORTER_INTERVAL"
             value: "1000"
           ports:
           - name: "metrics"
             containerPort: 7788
           securityContext:
             privileged: true
           volumeMounts:
           - name: "pod-spu-resources"
             readOnly: true
             mountPath: "/var/lib/kubelet/pod-resources"
           resources:
             requests:
               cpu: "100m"
               memory: "128Mi"
             limits:
               cpu: "500m"
               memory: "256Mi"
         volumes:
         - name: "pod-spu-resources"
           hostPath:
             path: "/var/lib/kubelet/pod-resources"
   
   ---
   
   kind: Service
   apiVersion: v1
   metadata:
     name: "dcsm-exporter"
     namespace: "moffett-monitoring"
     labels:
       app.kubernetes.io/name: "dcsm-exporter"
       app.kubernetes.io/version: "1.0.0"
   spec:
     selector:
       app.kubernetes.io/name: "dcsm-exporter"
       app.kubernetes.io/version: "1.0.0"
     ports:
     - name: "metrics"
       port: 7788
       targetPort: 7788
   ```

3. 部署 DCSM Exporter。

   ```Bash
   $ kubectl create -f dcsm-exporter.yaml
   ```

### 验证部署是否成功

- 如果您是单机容器化部署，可执行以下命令验证是否部署成功：

  - 在终端中验证指标获取情况，请执行以下命令：

    ```Bash
      $ curl http://${your-ip}:7788/metrics
    ```

  - 在浏览器中验证 dcsm-exporter 指标获取情况，打开浏览器在地址栏输入：

        http://${your-ip}:7788/metrics
  
- 如果您是通过集群部署，可在集群节点执行以下命令验证是否部署成功：

  ```Bash
  $ kubectl get pod -n moffett-monitoring -o wide 
  # 查询服务集群IP
  $ kubectl get svc -n moffett-monitoring
  # 查询exporter输出指标数据
  $ curl http://{Cluster-IP}:7788/metrics
  # sample 
  $ curl http://10.233.61.94:7788/metrics
  ```

## 接入 Prometheus 配置

DCSM Exporter 接入 Prometheus， 请根据实际环境选择合适的配置方式。

- **静态配置**：配置 Prometheus.yaml 文件，  适用于独立服务或固定部署的实例数量较少的环境，如单机容器化部署环境。
- **动态服务发现配置**：配置 ServiceMonitor ，在 Kubernetes 集群中，适用于通过 Operator 部署 Prometheus 的场景。

### 静态配置

#### 添加监控目标

为了让 Prometheus 能够获取到 DCSM Exporter 采集的指标数据（metrics），需要调整 Prometheus 配置文件，在其中添加监控目标。

我们可以利用 Prometheus 的 static_configs 来拉取 DCSM Exporter 的数据。

打开 prometheus.yml 文件，在 scrape_configs 中添加如下配置：

```YAML
scrape_configs:
  - job_name: "spu-metrics"
# DCSM Exporter默认HTTP监听端口是7788
    static_configs:
      - targets: ["0.0.0.0:7788"]
```

#### 重启监控服务

修改 prometheus.yml 完成后，请重启 prometheus 服务以使配置生效。

### 动态服务发现配置

对于 Kubernetes 环境，建议使用 Prometheus Operator 和 ServiceMonitor，可以动态管理监控目标，减少手动维护的成本，来使 Prometheus 自动发现和监控 DCSM Exporter 。ServiceMonitor 配置会通过 Operator 自动同步到 Prometheus 中，无需手动调整 prometheus.yml 文件。

`ServiceMonitor` 建议配置如下：

```YAML
# service-monitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: "dcsm-exporter"
  namespace: "moffett-monitoring"
  labels:
    app.kubernetes.io/name: "dcsm-exporter"
    app.kubernetes.io/version: "1.0.0"
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: "dcsm-exporter"
      app.kubernetes.io/version: "1.0.0"
  namespaceSelector:
    matchNames:
      - "moffett-monitoring"
  endpoints:
  - port: "metrics"
    path: "/metrics"
    interval: "1s"
```

## 数据可视化

使用 Prometheus 自带的 Web console 以及 Grafana 来查询和展现数据。

### Web console 

Prometheus 自带了 Web console， 安装成功后可以访问 `http://${your-IP}}:9090` 页面，用它可以进行任何 PromQL 查询和调试工作。  

- 检查 **Prometheus Web** 界面的 **Targets** 页签，确认目标是否正确地出现在监控列表中。
- 查看 dcsm-exporter 的 **metrics** 数据是否能够被成功抓取。
- metrics 通常以 **DCSM\**\*** 开头 。

示例：点击 **quary**，输入 **DCSM_FI_DEV_SPU_TEMP** ，选择**时间**，点击 **Excute**， 即可查询到监控节点指定时间的墨芯设备温度信息和图表。

### Grafana 

Grafana 是一套开源的分析监视平台，支持多种数据源，其 UI 美观且可高度定制化，这是 Prometheus web console 不具备的 。

我们定制了一个 Dashboard  UI 模板范例，您可通过如下步骤使用：

1. 进入 **Grafana web** 页面（如 http://${your-ip}:3000/dashboards），  上传我们预定义的 json 模板文件。 json 文件下载地址：https://moffett-oss-bucket.tos-cn-shanghai.volces.com/dcsm/dcsm-exporter-dashboard.json。
2. 数据源选择 **Prometheus**。
3. 进入 **Dashboard** 查看。

## 卸载 DCSM Exporter

### 单机版卸载

1. 停止并删除容器。
   ```Bash
   $ docker stop dcsm-exporter && docker rm dcsm-exporter 
   ```
2. 删除镜像。
   ```Bash
   $ docker rmi moffett/dcsm-exporter:1.1.0-1.0.0
   ```
3. 确认是否卸载完成。
   ```Bash
   $ docker ps |grep dcsm-exporter 
   $ docker image |grep dcsm-exporter 
   ```

### 集群版卸载

1. 删除名字空间下的所有资源，如 DaemonSet、Service 等。
   ```Bash
   $ kubectl delete all --all namespace=moffett-monitoring
   ```
2. 删除名字空间。
   ```Bash
   $ kubectl delete ns moffett-monitoring
   ```
3. 确认是否卸载完成。
   ```Bash
   $ kubectl get all -A | grep dcsm-exporter
   $ kubectl get ns | grep moffett-monitoring
   ```