# DCSM Exporter 用户手册

DCSM Exporter 是基于数据中心 SPU 管理器 DCSM（Data Center SPU Manager）构建的指标采集工具，用于在单机或集群环境中实时监控墨芯稀疏处理单元 SPU（Sparse Processing Unit）计算卡的负载与健康状态，并以 Prometheus 格式导出运行数据。

## 选择部署方式

DCSM Exporter 支持以下部署方式：

- 单机容器部署。
- Kubernetes 集群部署。

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

   DCSM Exporter 在 Kubernetes 集群中可单独部署或通过 SPU Operator 统一部署，任选一种方式以避免冲突。通过 SPU Operator 部署的操作，详见 [《MOFFETT SPU Operator 用户手册》](../k8s-spu-operator.md)。
   ```

## 部署前准备

- 安装 SOLA Toolkit，详见[《SOLA Toolkit 安装指南》](../../installation/sola-toolkit-installation-guide.md)。

- 获取容器镜像。

   ````{tabs}
   ```{tab} 在线拉取
   ```bash
   docker pull moffett/dcsm-exporter:1.3.0-1.0.0
   ```

   ```{tab} 离线导入
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.13/dcsm-exporter/dcsm-exporter_1.3.0-1.0.0.tar
   docker load -i dcsm-exporter_1.3.0-1.0.0.tar
   ```
   ````

(deploy-dcsm-exporter)=
## 单机容器环境部署

### 前提条件

安装 MOFFETT Container Toolkit，详见 [《MOFFETT Container Toolkit 用户手册》](../mct.md)。

### 操作步骤

1. 生成容器设备接口（Container Device Interface，CDI）规范文件，详见[《MOFFETT Container Toolkit 用户手册》](../mct.md)。

   ```bash
   sudo moffett-ctk cdi generate --driver-root / --output=/etc/cdi/moffett.yaml
   ```

2. 启动 DCSM Exporter 容器。

   ```bash
   docker run -itd \
          --device moffett.ai/spu=all \
          --net=host \
          --name=dcsm-exporter \
          moffett/dcsm-exporter:1.3.0-1.0.0 \
          -f /etc/dcsm-exporter/default-counters.csv \
          -c 15000 -a :7788 -d all
   ```

   下表列出了启动容器时可指定的参数：

   ::: nested-table
   | 命令行参数                     | 环境变量                          | 说明                                                                                                                                                         | 默认值                                      |
   | ------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
   | -f,--collectors                | DCSM_EXPORTER_COLLECTORS          | 指定包含要收集的 DCSM 字段的文件路径。                                                                                                                       | /etc/dcsm-exporter/default-counters.csv     |
   | -c,--collect-interval          | DCSM_EXPORTER_INTERVAL            | 指定收集指标的时间间隔，单位：毫秒（ms）。                                                                                                                   | 30000                                       |
   | -a,--address                   | DCSM_EXPORTER_LISTEN              | 指定监听 HTTP 服务的地址，格式：:*<port\>*。                                                                                                                | :7788                                       |
   | -r,--remote-hostengine-info    | DCSM_REMOTE_HOSTENGINE_INFO       | 指定 DCSM Exporter 连接特定主机上部署的 `mx-hostengine`，格式：*host_ip*:*port*。                                                                            | DCSM Exporter 容器内部署的 `mx-hostengine`  |
   | -d,--devices                   | DCSM_EXPORTER_DEVICES_STR         | 指定要监控的设备，支持的值：all 或指定设备的 ID，例如：all、0,1、2-4、0,2-4。<br />确保指定监控的设备在启动容器时挂载的设备范围内，否则会导致容器启动失败。 | all                                         |
   | -k,--kubernetes                | 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 |
   :::

### 部署后验证

```bash
curl http://<host_ip>:<port>/metrics # 终端中验证
```

## Kubernetes 集群环境手动单独部署

### 前提条件

搭建 Kubernetes 集群，详见 <a href="https://kubernetes.io/zh-cn/docs/home/" target="_blank">Kubernetes 文档</a>。

### 操作步骤

创建 DCSM Exporter 的 DaemonSet 和 Service，步骤如下：

1. 创建名为 `moffett-monitoring` 的 namespace。

   ```bash
   kubectl create ns moffett-monitoring
   ```

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

   ```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.3.0-1.0.0"
           env:
           - name: "DCSM_EXPORTER_LISTEN"
             value: ":7788"
           - name: "DCSM_EXPORTER_KUBERNETES"
             value: "true"
           - name: "DCSM_EXPORTER_INTERVAL"
             value: "30000"
           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
   ```

(dcsm-exporter-k8s-verification)=
### 部署后验证

在可访问集群 Service 的环境中执行：

```bash
kubectl get pod -n moffett-monitoring -o wide # 查看 NAMESPACE 为 moffett-monitoring 的所有 Pod 的详细信息
kubectl get svc -n moffett-monitoring         # 查询 NAME 为 dcsm-exporter 的 CLUSTER-IP 和 PORT
curl http://<CLUSTER-IP>:<PORT>/metrics       # 查询 DCSM Exporter 输出的指标数据
```

(custom-dcsm-metrics)=
## 自定义 DCSM 指标

DCSM Exporter 支持通过自定义 CSV 文件调整采集字段。建议以默认指标文件为模板生成自定义文件，并通过 `-f` 参数或 `DCSM_EXPORTER_COLLECTORS` 环境变量引用该文件，以便在镜像升级、容器重建或 Helm 更新后继续复用配置。

### 准备自定义指标文件

1. 导出默认指标文件。

   ```bash
   docker create --name dcsm-exporter-tmp moffett/dcsm-exporter:1.3.0-1.0.0
   docker cp dcsm-exporter-tmp:/etc/dcsm-exporter/default-counters.csv ./dcsm-metrics.csv
   docker rm dcsm-exporter-tmp
   ```

2. 修改 `dcsm-metrics.csv`，按需删除或追加字段（参见[可用 DCSM 字段参考](#dcsm-available-fields-reference)）。文件需保持 CSV 格式，每行定义一个字段，以 `#` 开头的行为注释。示例如下：

   ```text
   # DCSM FIELD, Prometheus metric type, help message
   DCSM_FI_DEV_SPU_TEMP, gauge, SPU temperature (in C).
   DCSM_FI_DEV_POWER_USAGE, gauge, Power draw (in W).
   DCSM_FI_DEV_SERIAL, label, Device Serial Number
   ```

### 单机容器环境应用方式

删除旧容器，重新启动并挂载自定义指标文件，步骤如下：

1. 停止并删除旧容器（以 `dcsm-exporter` 为例）。

   ```bash
   docker stop dcsm-exporter
   docker rm dcsm-exporter
   ```

2. 重新启动容器，并通过 `-v` 参数挂载自定义指标文件，`-f` 参数指定使用该文件。示例如下：

   ```bash
   docker run -itd \
          --device moffett.ai/spu=all \
          --net=host \
          --name=dcsm-exporter \
          -v $(pwd)/dcsm-metrics.csv:/etc/dcsm-exporter/dcsm-metrics.csv:ro \
          moffett/dcsm-exporter:1.3.0-1.0.0 \
          -f /etc/dcsm-exporter/dcsm-metrics.csv \
          -c 15000 -a :7788 -d all
   ```

### Kubernetes 集群环境应用方式

1. 创建或更新自定义指标 ConfigMap（自定义字段参见[可用 DCSM 字段参考](#dcsm-available-fields-reference)）。

   ```bash
   kubectl create configmap custom-dcsm-exporter-metrics \
     --from-file=dcsm-metrics.csv \
     -n moffett-monitoring \
     --dry-run=client -o yaml | kubectl apply -f -
   ```

2. 修改 `dcsm-exporter.yaml`，设置 `DCSM_EXPORTER_COLLECTORS` 并挂载 ConfigMap。示例如下：

   ```yaml
   spec:
     template:
       spec:
         containers:
         - name: "dcsm-exporter"
           env:
           - name: "DCSM_EXPORTER_COLLECTORS"
             value: "/etc/dcsm-exporter/dcsm-metrics.csv"
           volumeMounts:
           - name: "dcsm-metrics"
             mountPath: "/etc/dcsm-exporter/dcsm-metrics.csv"
             subPath: "dcsm-metrics.csv"
             readOnly: true
         volumes:
         - name: "dcsm-metrics"
           configMap:
             name: custom-dcsm-exporter-metrics
   ```

3. 应用配置并重启 Pod，加载更新后的指标文件。

   ```bash
   kubectl apply -f dcsm-exporter.yaml
   kubectl rollout restart daemonset/dcsm-exporter -n moffett-monitoring
   kubectl rollout status daemonset/dcsm-exporter -n moffett-monitoring
   ```

按[部署后验证](#dcsm-exporter-k8s-verification)查询 `/metrics`，确认所配置的指标已输出。

### 通过 SPU Operator 部署

详见《MOFFETT SPU Operator 用户手册》中的{ref}`DCSM Exporter 指标 <spu-operator-custom-dcsm-metrics>`。

## 接入 Prometheus 和 Grafana

DCSM Exporter 支持接入 Prometheus 进行指标采集，并使用 Grafana 进行可视化展示。

### 接入 Prometheus

先部署 Prometheus；Kubernetes 环境使用 Prometheus Operator。安装方法分别参见 [Prometheus 文档](https://prometheus.io/docs/prometheus/latest/installation/)和 [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#install-helm-chart)。

#### 单机容器环境

在 `prometheus.yml` 的 `scrape_configs` 中添加 DCSM Exporter 地址，然后重新加载配置：

```yaml
scrape_configs:
  - job_name: "spu-metrics"
    static_configs:
      - targets: ["<host_ip>:7788"]
```

#### Kubernetes 集群环境

先检查 Prometheus 的 `spec.serviceMonitorSelector`（匹配 ServiceMonitor 的标签）和 `spec.serviceMonitorNamespaceSelector`（匹配 ServiceMonitor 所在命名空间的标签）：

```bash
kubectl get prometheus -A
kubectl get prometheus <name> -n <namespace> -o yaml
```

手动部署和 SPU Operator 部署均需在 Prometheus 的部署配置中设置这两个选择器，使其覆盖待采集的 ServiceMonitor。手动部署的示例位于 `moffett-monitoring`，Operator 创建的资源位于 `moffett-spu-operator`；字段含义及空值行为参见 [Prometheus 配置参考](https://prometheus-operator.dev/docs/api-reference/api/#prometheusspec)。

手动部署 DCSM Exporter 时，将以下内容保存为 `service-monitor.yaml`。

```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: "15s"
```

```bash
kubectl apply -f service-monitor.yaml
```

通过 SPU Operator 部署时，设置 `dcsmExporter.serviceMonitor.enabled=true`，由 Operator 创建 ServiceMonitor，配置方法参见{ref}`更新配置 <spu-operator-update-config>`。

在 Prometheus 的 Targets 页面确认 DCSM Exporter 抓取状态为 UP，并查询已配置的设备指标。

### 使用 Grafana

部署 Grafana 并配置 [Prometheus 数据源](https://grafana.com/docs/grafana/latest/datasources/prometheus/configure/)，然后按[导入仪表盘](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/)中的步骤，导入墨芯提供的 [DCSM Exporter Dashboard](https://moffett-oss-bucket.tos-cn-shanghai.volces.com/dcsm/dcsm-exporter-dashboard-v3.json)。确认仪表盘能够显示目标设备的指标。

(disable-dcsm-exporter)=
## 停用与卸载

本节介绍停用和卸载 DCSM Exporter 的操作。

### 停用 DCSM Exporter

当更新 SOLA Toolkit 时，DCSM Exporter 组件会影响 SOLA Toolkit 卸载，可按以下步骤在指定环境中先停用 DCSM Exporter。

#### 单机容器环境

1. 检查容器环境的 DCSM Exporter。

   ```bash
   docker ps | grep dcsm-exporter
   ```

2. 停止 DCSM Exporter 容器。

   ```bash
   docker stop <container-name> # 或使用 container ID
   ```

#### Kubernetes 集群环境

在 Kubernetes 集群环境中可选择以下任一方式停用 DCSM Exporter。

##### 通过节点 Taint 停止指定节点调度

该方式适合临时在指定节点停用 DCSM Exporter，步骤如下：

1. 查询集群中部署的 DCSM Exporter 所有 Pod 的详细信息。

   ```bash
   kubectl get pod -l app.kubernetes.io/name=dcsm-exporter -n moffett-monitoring -o wide
   ```

2. 为集群的指定节点添加污点（Taint）并删除该节点上 DCSM Exporter 相关 Pod。

   ```bash
   kubectl get nodes                                                                                                           # 查询集群的所有节点
   kubectl taint nodes <node_name> NeedFix=true:NoSchedule                                                                     # 为指定节点添加 Taint，标记为不可调度
   kubectl describe node <node_name> | grep Taints                                                                             # 验证节点 Taint 是否生效
   kubectl delete pod -l app.kubernetes.io/name=dcsm-exporter -n moffett-monitoring --field-selector spec.nodeName=<node_name> # 删除指定节点上 DCSM Exporter 的 Pod
   kubectl get pod -n moffett-monitoring -o wide                                                                               # 验证 Pod 状态
   ```

   如需恢复指定节点上的 DCSM Exporter 相关 Pod，移除该节点上的 Taint。

   ```bash
   kubectl taint nodes <node_name> NeedFix=true:NoSchedule-
   ```

##### 通过节点亲和性排除指定节点

该方式通过修改 DaemonSet 配置长期控制指定节点是否运行 DCSM Exporter，步骤如下：

1. 给需要停用 DCSM Exporter 组件的节点添加 `dcsm-exporter-disabled=true` 标签。

   ```bash
   kubectl label node <node_name> dcsm-exporter-disabled=true # 添加标签
   kubectl get nodes --show-labels | grep <node_name>         # 验证标签
   ```

2. 添加亲和性配置。

   在 `dcsm-exporter.yaml` 文件的 `spec.template.spec` 字段添加 `requiredDuringSchedulingIgnoredDuringExecution` 配置，指定有 `dcsm-exporter-disabled=true` 标签的节点不运行 DCSM Exporter 组件的 Pod。

   ```yaml
   affinity:
     nodeAffinity:
       requiredDuringSchedulingIgnoredDuringExecution:
         nodeSelectorTerms:
         - matchExpressions:
           - key: dcsm-exporter-disabled
             operator: NotIn
             values:
             - "true"
   ```

3. 应用更新的 DCSM Exporter 的 DaemonSet 配置。

   ```bash
   kubectl apply -f dcsm-exporter.yaml
   ```

4. 验证 DCSM Exporter 组件的 Pod 在指定节点上停用。

   ```bash
   kubectl get pod -o wide -n moffett-monitoring
   ```

   如需在指定节点上恢复 DCSM Exporter 组件，删除标签。

   ```bash
   kubectl label node <node_name> dcsm-exporter-disabled-
   ```

### 卸载 DCSM Exporter

#### 单机容器环境

1. 停用并删除容器。

   ```bash
   docker stop dcsm-exporter && docker rm dcsm-exporter
   ```

2. 删除镜像。

   ```bash
   docker rmi moffett/dcsm-exporter:1.3.0-1.0.0
   ```

3. 验证卸载是否完成。

   ```bash
   docker ps | grep dcsm-exporter
   docker images | grep dcsm-exporter
   ```

#### Kubernetes 集群环境

1. 删除通过本文部署的 DCSM Exporter 及其 Service。

   ```bash
   kubectl delete -f dcsm-exporter.yaml
   ```

2. 如果创建了本文示例中的监控或自定义指标资源，删除对应资源。

   ```bash
   kubectl delete servicemonitor dcsm-exporter -n moffett-monitoring --ignore-not-found
   kubectl delete configmap custom-dcsm-exporter-metrics -n moffett-monitoring --ignore-not-found
   ```

3. 确认 DCSM Exporter 资源已移除。

   ```bash
   kubectl get daemonset,pod,service -n moffett-monitoring -l app.kubernetes.io/name=dcsm-exporter
   ```

4. （可选）如果 `moffett-monitoring` 命名空间仅用于本次部署，删除该命名空间。

   ```bash
   kubectl delete ns moffett-monitoring
   ```

(dcsm-available-fields-reference)=
## 可用 DCSM 字段参考

DCSM Exporter 支持指标和标签两类字段。如需裁剪或扩展采集项，可选择对应字段并写入自定义 CSV 文件。

### 指标字段

用于实时采集和反映设备的运行状态与性能数据，如下表所示。关于 Prometheus 指标类型的详细信息，参见 <a href="https://prometheus.io/docs/tutorials/understanding_metric_types/" target="_blank">Understanding metric types</a>。

::: nested-table
| 指标名称                       | Prometheus 指标类型 | 描述                                        |
| ------------------------------ | ------------------- | ------------------------------------------- |
| DCSM_FI_DEV_NNCORE_CLOCK       | gauge               | NNCORE 的时钟频率，单位：MHz                |
| DCSM_FI_DEV_SPU_TEMP           | gauge               | SPU 温度，单位：℃                           |
| DCSM_FI_DEV_FAN_SPEED          | gauge               | 风扇调速比（单位：%）                       |
| DCSM_FI_DEV_FAN_SPEED_RPM      | gauge               | 风扇转速（RPM）                             |
| 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_DDR_TOTAL          | gauge               | DDR 内存总大小，单位：MB          |
| DCSM_FI_DEV_DDR_RESERVED       | gauge               | 预留 DDR 内存大小，单位：MB |
| DCSM_FI_DEV_DDR_USED_PERCENT   | gauge               | DDR 使用率，公式：Used/(Total−Reserved)，取值范围：0.0~1.0 |
| 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 错误总数                     |
:::

### 标签字段

用于描述指标来源设备的静态特征，如下表所示。这些字段不会作为指标上报，而是作为 Prometheus 指标的标签附加在每条指标数据上。

::: nested-table
| Label 名称             | 描述                            |
| ---------------------- | ------------------------------- |
| DCSM_FI_DEV_NAME       | 设备型号                        |
| DCSM_FI_DEV_SERIAL     | 设备序列号（Serial Number，SN） |
| DCSM_FI_DRIVER_VERSION | 驱动版本                        |
| DCSM_FI_MXML_VERSION   | MXML 版本                       |
:::