# DCSM Exporter 用户手册
DCSM Exporter 是基于 DCSM 构建的指标采集工具，用于在单机或集群环境中实时监控墨芯计算卡的负载与健康状态。DCSM Exporter 支持导出墨芯计算卡的运行数据，兼容 Prometheus 格式。
```{admonition} 须知
:class: note
DCSM Exporter 在 Kubernetes 集群中可单独部署或通过 SPU Operator 统一部署，任选一种方式以避免冲突。通过 SPU Operator 部署的详细操作，请参见 [MOFFETT SPU Operator 用户手册](../k8s-spu-operator.md)。
```
## 部署 DCSM Exporter
DCSM Exporter 可部署在单机容器中运行，也可在 Kubernetes 集群中的墨芯设备节点上以 DaemonSet 方式部署。
### 前提条件
- 安装 SOLA Toolkit，具体请参见 [SOLA Toolkit 安装指南](../../installation/sola-toolkit-installation-guide.md)。
- 使用单机容器方式部署时，需安装 MOFFETT Container Toolkit，具体请参见 [MOFFETT Container Toolkit 用户手册](../mct.md)。
- 使用 Kubernetes 集群方式部署时，需安装 Kubernetes 集群，具体请参见 Kubernetes 文档。
### 操作步骤
#### 获取 DCSM Exporter 容器镜像
````{tabs}
```{tab} 在线拉取
```Bash
docker pull moffett/dcsm-exporter:1.2.0-1.0.0
```
```{tab} 离线导入
```Bash
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/images/Ubuntu/business/dcsm/dcsm-exporter_1.2.0-1.0.0.tar
docker load -i dcsm-exporter_1.2.0-1.0.0.tar
```
````
#### 单机容器环境部署 DCSM Exporter
1. 生成 CDI 配置文件，具体请参见 [MOFFETT Container Toolkit 用户手册](../mct.md)。
```bash
sudo moffett-ctk cdi generate --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.2.0-1.0.0 \
-f /etc/dcsm-exporter/default-counters.csv \
-c 15000 -a :7788 -d all
```
配置 DCSM Exporter 容器的命令行参数或环境变量如下表所示：
| **命令行参数** | **环境变量** | **说明** | **默认值** |
| ------------------------------ | --------------------------------- | ----------------------------------------------------------- | --------------------------------------------------- |
| --f,--collectors | DCSM_EXPORTER_COLLECTORS | 指定包含要收集的 DCSM 字段的文件路径。 | /etc/dcsm-exporter/default-counters.csv |
| -c,--collect-interval | DCSM_EXPORTER_INTERVAL | 指定收集指标的时间间隔，单位：毫秒（ms）。 | 30000 |
| -a,--address value | DCSM_EXPORTER_LISTEN | 指定监听 HTTP 服务的地址，格式：:**。 | :7788 |
| -r,--remote-hostengine-info | DCSM_REMOTE_HOSTENGINE_INFO | 指定 DCSM Exporter 连接特定主机上部署的 `mx-hostengine`，格式：*machine_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 |
通过 `--f,--collectors` 参数指定的 `default-counters.csv` 文件默认包含以下两类字段：
- 指标：用于实时采集和反映设备的运行状态与性能数据，如下表所示：
::: 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_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 指标类型的详细信息，请参见 Understanding metric types。
- Label：用于描述指标来源设备的静态特征。这些字段不会作为指标上报，而是作为 Prometheus 指标的标签附加在每条指标数据上，如下表所示：
::: nested-table
| **label 名称** | **描述** |
| ------------------------------ | ---------------------------------|
| DCSM_FI_DEV_SERIAL | 设备序列号（Serial Number，SN） |
| DCSM_FI_DRIVER_VERSION | 驱动版本 |
| DCSM_FI_MXML_VERSION | MXML 版本 |
:::
#### Kubernetes 集群环境部署 DCSM Exporter
在 Kubernetes 集群中，创建 DCSM Exporter 的 DaemonSet 和 Service，步骤如下：
1. 创建名为 `moffett-monitoring` 的 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.2.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
```
### 部署后验证
````{tabs}
```{tab} 单机容器环境验证
```bash
curl http://:/metrics # 终端中验证
http://:/metrics # 浏览器中验证
```
```{tab} Kubernetes 集群环境验证
```bash
kubectl get pod -n moffett-monitoring -o wide # 查看 NAMESPACE 为 moffett-monitoring 的所有 Pod 的详细信息
kubectl get svc -n moffett-monitoring # 查询 NAME 为 moffett-dcsm-exporter 的 CLUSTER-IP 和 PORT
curl http://:/metrics # 查询 DCSM Exporter 输出的指标数据
```
````
## 配置 Prometheus
DCSM Exporter 支持接入 Prometheus，根据部署 DCSM Exporter 的方式选择以下一种配置方式：
- 单机容器环境，主机上安装 Prometheus 并直接修改配置文件。
- Kubernetes 集群环境，在 Kubernetes 集群中部署 Prometheus 并配置 Service Monitor。
关于如何使用 Prometheus 的详细信息，请参见 Prometheus Docs。
### 单机容器环境
安装 Prometheus，并修改其配置文件，步骤如下：
1. 获取 Prometheus 安装包，并解压缩。
```
tar xvfz prometheus-.tar.gz
cd prometheus-
```
2. 修改 Prometheus 配置文件，添加监控目标。
在 `prometheus.yml` 文件的 `scrape_configs` 字段，添加监控目标（`targets`），示例如下：
```YAML
scrape_configs:
- job_name: "spu-metrics"
static_configs:
- targets: [":7788"] # 添加监控目标主机的 IP 地址及端口号，DCSM Exporter 默认监听端口为 7788；可添加多个目标
```
3. 重启 Prometheus 服务，使配置生效。Prometheus 默认监听端口为 9090。
```bash
./prometheus --config.file=prometheus.yml &
```
4. 主机上通过浏览器访问 `http://:9090`，检索指标数据。
### Kubernetes 集群环境
在 Kubernetes 集群环境中，使用 Prometheus Operator 和 Service Monitor 自动发现和监控 DCSM Exporter。Service Monitor 配置会通过 Operator 自动同步到 Prometheus 中。
1. 部署 `kube-prometheus-stack`。
```
# 添加 Helm 仓库（只需执行一次）
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
# 安装 kube-prometheus-stack
helm install kube-prometheus-stack prometheus-community/kube-prometheus-stack \
--create-namespace --namespace prometheus \
--set prometheus.service.type=NodePort \ # 将 ClusterIP 修改为 NodePort（默认端口号为 30090）
--set prometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues=false # 指定 Prometheus 能够监控集群中所有命名空间的 ServiceMonitor
```
更多关于安装 `kube-prometheus-stack` 的详细信息，请参见 kube-prometheus-stack。
2. 验证已部署的 Prometheus 服务及端口信息。
```
kubectl get svc -A | grep prometheus
```
3. 部署 Service Monitor。
```{admonition} 须知
:class: note
如果通过 SPU Operator 部署 DCSM Exporter，无需该步骤，可通过 SPU Operator 启用 Service Monitor 服务，具体请参见 [MOFFETT SPU Operator 用户手册](../k8s-spu-operator.md)。
```
a. 创建配置文件。
```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"
```
b. 应用配置。
```
kubectl apply -f service-monitor.yaml
```
4. 通过浏览器访问 `http://:30090`，检索指标数据。
## 使用 Grafana
Grafana 是一款开源的可视化与分析工具，可通过仪表盘（Dashboard）帮助收集、关联并可视化数据。在 Kubernetes 集群中部署的 `kube-prometheus-stack` 集成了 Grafana Dashboard。
### 单机容器环境
1. 根据 Download Grafana 页面指示，选择对应平台的安装包部署 Grafana，完成后 Grafana 默认监听端口为 3000。
2. 通过浏览器访问 `http://:3000`，进入 Grafana 登录页面。使用用户名 `admin` 和密码 `admin` 登录 Grafana 主界面。
3. 将 Grafana 的数据源设置为 Prometheus，具体操作请参见 Configure the Prometheus data source。
### Kubernetes 集群环境
默认情况下，Grafana 服务通过 `ClusterIP` 类型监听端口，仅限集群内部访问。为便于通过浏览器访问，可将其修改为 `NodePort` 类型，方式类似于 Prometheus Dashboard 的访问方式。步骤如下：
1. 创建 `grafana-patch.yaml` 补丁文件，修改 Grafana 服务的对外端口为 `NodePort` 并指定端口号。NodePort 端口号取值在 30000~32767 闭区间范围内，这里以 32300 为例。
```bash
vim grafana-patch.yaml
```
```
spec:
type: NodePort # 服务监听方式
ports:
- port: 80 # 集群内访问端口号
targetPort: 3000 # Pod 内部端口号
nodePort: 32300 # 节点主机上暴露的端口号
```
2. 修改服务监听使用指定的 `NodePort`。
```bash
kubectl patch svc -n prometheus --patch "$(cat grafana-patch.yaml)" # 通过 kubectl get svc -A | grep grafana 命令查询
```
3. 验证已修改的 Grafana 监听端口信息。
```
kubectl get svc -A | grep grafana
```
4. 通过浏览器访问 `http://:32300` Grafana 主页面，登录用户名：`admin`；密码：`prom-operator`。
```{admonition} 须知
:class: note
登录 Grafana 的密码可通过 `kubectl --namespace prometheus get secrets -o jsonpath="{.data.admin-password}" | base64 -d ; echo` 命令查询获取。
```
### 应用 DCSM Dashboard
参见 Import dashboards 导入墨芯提供的 Dashboard 模板（.json 文件），创建 MOFFETT DCSM Exporter Dashboard。可根据实际需求自定义 Dashboard 内容。
## 停用 DCSM Exporter
当更新 SOLA Toolkit 时，DCSM Exporter 组件会影响 SOLA Toolkit 卸载，执行以下步骤在指定节点停用 DCSM Exporter。
### 单机容器环境
1. 检查容器环境的 DCSM Exporter。
```
docker ps | grep dcsm-exporter
```
2. 停止 DCSM exporter 容器。
```
docker stop # 或使用 container ID
```
### Kubernetes 集群环境
#### 给指定节点添加 Taint
1. 查询集群中部署的 DCSM Exporter 所有 Pod 的详细信息。
```
kubectl get pods -l app.kubernetes.io/name=dcsm-exporter -n moffett-monitoring -o wide
```
2. 为集群的指定节点添加污点（Taint）并删除该节点上 DCSM Exporter 相关 Pod。
```
kubectl get node # 查询集群的所有节点
kubectl taint nodes NeedFix=true:NoSchedule # 为指定节点添加 Taint，标记为不可调度
kubectl describe node | grep Taints # 验证节点 Taint 是否生效
kubectl delete pod -l app.kubernetes.io/name=dcsm-exporter -n moffett-monitoring --field-selector spec.nodeName= # 删除指定节点上特定标签的 Pod
kubectl get pod -n moffett-monitoring -o wide # 验证 Pod 状态
```
如需恢复指定节点上的 DCSM Exporter 相关 Pod，移除该节点上的 Taint。
```
kubectl taint nodes NeedFix=true:NoSchedule-
```
#### 利用节点亲和性给指定节点添加标签
1. 给需要移除 DCSM Exporter 组件的节点添加 `dcsm-exporter-disabled=true` 标签。
```
kubectl label node dcsm-exporter-disabled=true
```
2. 验证指定节点具有 `dcsm-exporter-disabled=true` 标签。
```
kubectl get nodes --show-labels | grep
```
3. 在 `dcsm-exporter.yaml` 文件的 `spec` 字段添加亲和性配置（`requiredDuringSchedulingIgnoredDuringExecution`），选择拥有指定标签的节点。
```YAML
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: dcsm-exporter-disabled
operator: NotIn
values:
- "true"
```
4. 应用更新的 DCSM Exporter 的 DaemonSet 配置。
```
kubectl apply -f dcsm-exporter.yaml
```
5. 验证 DCSM Exporter Pod 在指定节点上停用。
```
kubectl get pods -o wide -n moffett-monitoring
```
如需在指定节点上恢复 DCSM Exporter 组件，删除标签。
```
kubectl label node dcsm-exporter-disabled-
```
## 卸载 DCSM Exporter
### 单机容器环境
1. 停用并删除容器。
```Bash
docker stop dcsm-exporter && docker rm dcsm-exporter
```
2. 删除镜像。
```Bash
docker rmi moffett/dcsm-exporter:1.2.0-1.0.0
```
3. 验证卸载是否完成。
```Bash
docker ps | grep dcsm-exporter
docker images | grep dcsm-exporter
```
### Kubernetes 集群环境
1. 删除 DCSM Exporter 对应 namespace 下特定资源类型的所有资源，包括 Pod、Deployment、Service、ReplicaSet 等。
```Bash
kubectl delete all --all -n moffett-monitoring
```
2. 删除 DCSM Exporter 的 namespace。
```Bash
kubectl delete ns moffett-monitoring
```
3. 验证卸载是否完成。
```Bash
kubectl get all -A | grep dcsm-exporter
kubectl get ns | grep moffett-monitoring
```