DCSM Exporter 用户手册

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

选择部署方式

DCSM Exporter 支持以下部署方式：

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

须知

DCSM Exporter 在 Kubernetes 集群中可单独部署或通过 SPU Operator 统一部署，任选一种方式以避免冲突。通过 SPU Operator 部署的操作，详见《MOFFETT SPU Operator 用户手册》。

部署前准备

安装 SOLA Toolkit，详见《SOLA Toolkit 安装指南》。

获取容器镜像。

docker pull moffett/dcsm-exporter:1.3.0-1.0.0

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

单机容器环境部署

前提条件

安装 MOFFETT Container Toolkit，详见《MOFFETT Container Toolkit 用户手册》。

操作步骤

生成容器设备接口（Container Device Interface，CDI）规范文件，详见《MOFFETT Container Toolkit 用户手册》。
```
sudo moffett-ctk cdi generate --driver-root / --output=/etc/cdi/moffett.yaml
```

启动 DCSM Exporter 容器。

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

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

命令行参数	环境变量	说明	默认值
-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。确保指定监控的设备在启动容器时挂载的设备范围内，否则会导致容器启动失败。	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

部署后验证

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

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

前提条件

搭建 Kubernetes 集群，详见 Kubernetes 文档。

操作步骤

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

创建名为 moffett-monitoring 的 namespace。
```
kubectl create ns moffett-monitoring
```

创建 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.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

部署 DCSM Exporter。
```
kubectl create -f dcsm-exporter.yaml
```

部署后验证

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

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 输出的指标数据

自定义 DCSM 指标

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

准备自定义指标文件

导出默认指标文件。

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

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

# 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

单机容器环境应用方式

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

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

docker stop dcsm-exporter
docker rm dcsm-exporter

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

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 集群环境应用方式

创建或更新自定义指标 ConfigMap（自定义字段参见可用 DCSM 字段参考）。

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

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

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

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

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

按部署后验证查询 /metrics，确认所配置的指标已输出。

通过 SPU Operator 部署

详见《MOFFETT SPU Operator 用户手册》中的DCSM Exporter 指标。

接入 Prometheus 和 Grafana

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

接入 Prometheus

先部署 Prometheus；Kubernetes 环境使用 Prometheus Operator。安装方法分别参见 Prometheus 文档和 kube-prometheus-stack。

单机容器环境

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

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

Kubernetes 集群环境

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

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

手动部署和 SPU Operator 部署均需在 Prometheus 的部署配置中设置这两个选择器，使其覆盖待采集的 ServiceMonitor。手动部署的示例位于 moffett-monitoring，Operator 创建的资源位于 moffett-spu-operator；字段含义及空值行为参见 Prometheus 配置参考。

手动部署 DCSM Exporter 时，将以下内容保存为 service-monitor.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"

kubectl apply -f service-monitor.yaml

通过 SPU Operator 部署时，设置 dcsmExporter.serviceMonitor.enabled=true，由 Operator 创建 ServiceMonitor，配置方法参见更新配置。

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

使用 Grafana

部署 Grafana 并配置 Prometheus 数据源，然后按导入仪表盘中的步骤，导入墨芯提供的 DCSM Exporter Dashboard。确认仪表盘能够显示目标设备的指标。

停用与卸载

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

停用 DCSM Exporter

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

单机容器环境

检查容器环境的 DCSM Exporter。
```
docker ps | grep dcsm-exporter
```

停止 DCSM Exporter 容器。

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

Kubernetes 集群环境

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

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

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

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

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

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

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。

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

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

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

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

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

添加亲和性配置。

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

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

应用更新的 DCSM Exporter 的 DaemonSet 配置。
```
kubectl apply -f dcsm-exporter.yaml
```
验证 DCSM Exporter 组件的 Pod 在指定节点上停用。
```
kubectl get pod -o wide -n moffett-monitoring
```
如需在指定节点上恢复 DCSM Exporter 组件，删除标签。
```
kubectl label node <node_name> dcsm-exporter-disabled-
```

卸载 DCSM Exporter

单机容器环境

停用并删除容器。

docker stop dcsm-exporter && docker rm dcsm-exporter

删除镜像。

docker rmi moffett/dcsm-exporter:1.3.0-1.0.0

验证卸载是否完成。

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

Kubernetes 集群环境

删除通过本文部署的 DCSM Exporter 及其 Service。
```
kubectl delete -f dcsm-exporter.yaml
```

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

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

确认 DCSM Exporter 资源已移除。

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

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

可用 DCSM 字段参考

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

指标字段

用于实时采集和反映设备的运行状态与性能数据，如下表所示。关于 Prometheus 指标类型的详细信息，参见 Understanding metric types。

指标名称	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 指标的标签附加在每条指标数据上。

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

DCSM Exporter 用户手册

选择部署方式

部署前准备

单机容器环境部署

前提条件

操作步骤

部署后验证

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

前提条件

操作步骤

部署后验证

自定义 DCSM 指标

准备自定义指标文件

单机容器环境应用方式

Kubernetes 集群环境应用方式

通过 SPU Operator 部署

接入 Prometheus 和 Grafana

接入 Prometheus

单机容器环境

Kubernetes 集群环境

使用 Grafana

停用与卸载

停用 DCSM Exporter

单机容器环境

Kubernetes 集群环境

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

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

卸载 DCSM Exporter

单机容器环境

Kubernetes 集群环境

可用 DCSM 字段参考

指标字段

标签字段

选择文档版本