#配置 NPU 故障可观测性

使用本操作指南，使 ACP 管理的业务集群中的 Ascend NPU 卡故障可观测。

主操作步骤配置的是正常的生产路径：

DCMI-reported fault state
  ├─> npu-exporter metrics
  ├─> Prometheus/VictoriaMetrics alert rules
  ├─> ACP alert view
  └─> ACP notification policy
        └─> email, Feishu, DingTalk, Webhook, or another configured channel

Ascend Device Plugin
  └─> marks the affected card unhealthy and reduces Node allocatable resources

可选的验证部分说明了项目如何通过故障注入镜像验证这一路径。该部分有意与生产操作步骤分开。健康的集群不会生成故障告警；这是完成告警路径配置后的预期状态。

#开始之前

请确保：

• 目标集群已安装 Alauda Build of NPU Operator。
• Ascend Device Plugin 在目标节点上报告 NPU 资源。
• NPU Exporter 已启用，且其 ServiceMonitor 已被 ACP Monitoring 栈抓取。
• 你有权限查看 Node、DaemonSet、ConfigMap、指标，并创建 PrometheusRule 资源。
• 如果需要外部通知，ACP notification server、receiver group、notification template 和 notification policy 均已可用。

在 v26.6.0 交付版本中，NPU Exporter 运行在 npu-exporter 中，Ascend Device Plugin 运行在 kube-system 中，exporter 的 ServiceMonitor 运行在 monitoring 中。

有关安装和 exporter 前置条件，请参见 安装、验证安装 和 监控 NPU 使用情况。

有关通知设置，请参见

以及 管理告警。

#1. 验证 NPU 指标是否可用

找到一个 NPU Exporter Pod，并在本地暴露其指标端点：

kubectl -n npu-exporter get pods -l app=npu-exporter -o wide

kubectl -n npu-exporter port-forward \
  pod/<npu-exporter-pod-name> 18082:8082

在另一个终端中，查询芯片指标：

curl -fsS http://127.0.0.1:18082/metrics | \
  grep -E 'npu_chip_info_health_status|npu_chip_info_error_code|npu_chip_info_network_status'

这些指标是按芯片上报的。请保留用于定位卡的标签：

• id
• model_name
• pcie_bus_info
• instance
• node，当抓取或存储流水线添加了该标签时

主指标的含义如下：

如果这些指标缺失，请先修复 exporter 或 ServiceMonitor 的发现问题，再创建芯片故障告警。参见 故障排查。 仅仅没有 error-code 序列，并不能证明该卡是健康的。还应确认同一卡的健康指标存在，且 exporter 正在无错误地收集 DCMI 数据。

#2. 记录健康基线

记录目标 Node 上的 NPU capacity 和 allocatable 资源：

kubectl get node <node-name> \
  -o jsonpath='capacity={.status.capacity.huawei\.com/Ascend310P} allocatable={.status.allocatable.huawei\.com/Ascend310P}{"\n"}'

将 huawei.com/Ascend310P 替换为目标 Node 报告的资源键，例如 huawei.com/Ascend910。

同时检查 Device Plugin 状态：

kubectl -n kube-system get cm mindx-dl-deviceinfo-<node-name> \
  -o jsonpath='{.data.DeviceInfoCfg}' | python3 -m json.tool

在健康状态下：

• capacity 和 allocatable 相等；
• 如果目标卡尚未被分配，它会出现在可用设备列表中；
• 目标卡不会出现在 Fault 和 Unhealthy 列表中。

这一步基线很重要，因为 NPUAllocatableReduced 检测的是 capacity 与 allocatable 之间的差异；它本身并不能证明存在硬件故障。

#3. 创建生产告警规则

在 monitoring 命名空间中创建一个 PrometheusRule。以下规则集覆盖了核心可观测路径：

• NPUChipUnhealthy：exporter 报告某个芯片不健康；
• NPUChipErrorCodePresent：exporter 在任一 error-code 指标槽位中报告 DCMI error code；
• NPUAllocatableReduced：Device Plugin 已减少可调度的 NPU 资源；
• NPUExporterDown：exporter 抓取目标不可用。

应用以下清单：

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: npu-production-fault-rules
  namespace: cpaas-system
  annotations:
    alert.cpaas.io/cluster: <cluster-name>
    alert.cpaas.io/kind: Cluster
    alert.cpaas.io/name: <cluster-name>
    alert.cpaas.io/namespace: cpaas-system
    alert.cpaas.io/notifications: '["<notification-policy-name>"]'
    alert.cpaas.io/rules.version: "26"
    cpaas.io/display-name: npu-production-fault-rules
  labels:
    alert.cpaas.io/cluster: <cluster-name>
    alert.cpaas.io/kind: Cluster
    alert.cpaas.io/name: <cluster-name>
    alert.cpaas.io/namespace: cpaas-system
    alert.cpaas.io/options: Single
    alert.cpaas.io/owner: User
    alert.cpaas.io/project: cpaas-system
    cpaas.io/source: Platform
    prometheus: kube-prometheus
    victoriametrics: victoriametrics
    rule.cpaas.io/cluster: <cluster-name>
    rule.cpaas.io/name: npu-production-fault-rules
    rule.cpaas.io/namespace: cpaas-system
spec:
  groups:
    - name: npu-production-fault
      rules:
        - alert: NPUChipUnhealthy
          expr: npu_chip_info_health_status{vmcluster="<vmcluster-name>"} != 1
          for: 2m
          labels:
            severity: Critical
            vmcluster: <vmcluster-name>
            alert_cluster: <cluster-name>
            alert_name: NPUChipUnhealthy
            alert_resource: npu-production-fault-rules
          annotations:
            alert_current_value: "{{ $value }}"
            alert_notifications: '["<notification-policy-name>"]'
            summary: "NPU chip {{ $labels.id }} on node {{ $labels.node }} is unhealthy; model={{ $labels.model_name }}, PCIe={{ $labels.pcie_bus_info }}"
        - alert: NPUChipErrorCodePresent
          expr: |
            {__name__=~"npu_chip_info_error_code(_[1-9])?",vmcluster="<vmcluster-name>"} > 0
          for: 2m
          labels:
            severity: High
            vmcluster: <vmcluster-name>
            alert_cluster: <cluster-name>
            alert_name: NPUChipErrorCodePresent
            alert_resource: npu-production-fault-rules
          annotations:
            alert_current_value: "{{ $value }}"
            alert_notifications: '["<notification-policy-name>"]'
            summary: "NPU chip {{ $labels.id }} on node {{ $labels.node }} reports DCMI error code {{ $value }}"
        - alert: NPUAllocatableReduced
          expr: |
            (
              kube_node_status_capacity{resource=~"huawei_com_Ascend[0-9A-Za-z]+$",vmcluster="<vmcluster-name>"}
              - on(node, resource, vmcluster)
              kube_node_status_allocatable{resource=~"huawei_com_Ascend[0-9A-Za-z]+$",vmcluster="<vmcluster-name>"}
            ) > 0
          for: 2m
          labels:
            severity: Warning
            vmcluster: <vmcluster-name>
            alert_cluster: <cluster-name>
            alert_name: NPUAllocatableReduced
            alert_resource: npu-production-fault-rules
          annotations:
            alert_current_value: "{{ $value }}"
            alert_notifications: '["<notification-policy-name>"]'
            summary: "NPU allocatable is lower than capacity on node {{ $labels.node }}"
        - alert: NPUExporterDown
          expr: up{vmcluster="<vmcluster-name>",job=~".*npu-exporter.*"} == 0
          for: 3m
          labels:
            severity: High
            vmcluster: <vmcluster-name>
            alert_cluster: <cluster-name>
            alert_name: NPUExporterDown
            alert_resource: npu-production-fault-rules
          annotations:
            alert_current_value: "{{ $value }}"
            alert_notifications: '["<notification-policy-name>"]'
            summary: "NPU Exporter scrape target is unavailable: instance={{ $labels.instance }}, node={{ $labels.node }}"

替换以下占位符：

• <cluster-name>：目标业务集群名称。
• <vmcluster-name>：ACP Monitoring 后端使用的 vmcluster 标签。若环境未添加 vmcluster 标签，请移除此匹配项。
• <notification-policy-name>：一个已存在的 ACP notification policy。项目验证中使用的是 cpaas-admin-notification。
• 如果资源名称、抓取作业名称和指标标签与目标环境不同，请相应替换。

示例使用的是告警规则元数据版本 26。这是 ACP 告警对象的元数据版本；它不是 NPU Operator 的发布版本。

应用并验证该规则：

kubectl apply -f npu-production-fault-rules.yaml

kubectl -n cpaas-system get prometheusrule npu-production-fault-rules \
  -o custom-columns='NAME:.metadata.name,DISPLAY:.metadata.annotations.cpaas\.io/display-name,KIND:.metadata.labels.alert\.cpaas\.io/kind,TARGET:.metadata.labels.alert\.cpaas\.io/name,OPTIONS:.metadata.labels.alert\.cpaas\.io/options'

预期结果是一个作用域为 Cluster、面向目标集群的规则。如果规则对象已存在但在 ACP 中不可见，请检查目标 ACP 版本所需的告警元数据和标签。

对于 Ascend 910 环境，如果 exporter 暴露了预期的网络指标和 model 标签，请添加以下规则：

npu_chip_info_network_status{vmcluster="<vmcluster-name>",model_name=~".*910.*"} != 1

你也可以添加一个集群级别的缺失指标规则：

absent(npu_chip_info_health_status{vmcluster="<vmcluster-name>"})

absent 规则用于检测集群级别的采集问题。它并不能证明每个预期的 Node 都有 exporter 目标。

#4. 配置通知投递

PrometheusRule 通过以下配置选择一个 ACP notification policy：

metadata:
  annotations:
    alert.cpaas.io/notifications: '["<notification-policy-name>"]'

每个告警还会携带所选 policy：

annotations:
  alert_notifications: '["<notification-policy-name>"]'

这些字段用于选择一个现有 policy。它们不会创建 notification server、receiver group、template 或 policy。

在 ACP Operations Center > Notifications 中配置投递对象：

1. 配置一个 notification server。
2. 创建一个 receiver group，并添加所需的 email、Feishu、DingTalk 或 Webhook 目标。
3. 创建或选择一个告警通知 template。
4. 创建一个 notification policy 并记录其名称。
5. 将该名称填入 PrometheusRule 中的两个字段。

有关平台操作步骤，请参见

。

#5. 在健康集群中验证已配置的可观测性

健康集群对于验证配置很有用，即使它不会触发故障告警。

验证以下所有内容：

kubectl -n npu-exporter get pods -l app=npu-exporter
kubectl -n monitoring get servicemonitor npu-exporter-servicemonitor
kubectl -n cpaas-system get prometheusrule npu-production-fault-rules

然后再次查询指标，并确认：

• 每个健康芯片的 npu_chip_info_health_status 都为 1；
• 所有发出的 npu_chip_info_error_code 指标要么为 0，要么不存在，同时芯片健康指标存在，且 exporter 未报告 DCMI 采集错误；
• NPU allocatable 等于 capacity；
• NPUChipUnhealthy、NPUChipErrorCodePresent 和 NPUAllocatableReduced 均未触发；
• NPUExporterDown 未触发。

此时没有活动的故障告警是预期行为。这证明规则对象已安装且健康状态数据路径正常工作，但并不能证明触发路径可用。触发路径需要真实的 DCMI 故障，或者受支持的非生产故障注入测试。

#6. 观察真实的 NPU 故障

当 DCMI 报告真实故障时，按以下顺序观察事件：

1. 从 exporter 中查询 npu_chip_info_health_status 和 npu_chip_info_error_code，并使用 id、model_name、pcie_bus_info 和 node 或 instance 识别该卡。
2. 等待告警规则持续时间，例如 NPUChipUnhealthy 和 NPUChipErrorCodePresent 的 2 分钟。
3. 打开 ACP Operation and Maintenance Center > Alerts > Alert Policies，并搜索 npu-production-fault-rules。
4. 打开告警详情，并验证卡身份、当前值、error code、严重性和通知状态。
5. 检查 Node allocatable 资源和 DeviceInfoCfg，确认 Device Plugin 是否已隔离该卡。

对于 SeparateNPU 故障，预期的隔离结果是：

capacity remains unchanged
allocatable decreases
the affected card appears in the Unhealthy list
DeviceInfoCfg records the fault code and SeparateNPU handling

NPUAllocatableReduced 是一个隔离结果信号。请将其与 NPUChipUnhealthy 或 NPUChipErrorCodePresent 结合起来，再将事件视为相关联的 NPU 故障和设备隔离事件。判断根因是硬件、驱动还是其他更底层的问题，还需要进一步诊断。

Device Plugin 的健康更新不会自动驱逐、重启或迁移已经分配到受影响卡的运行中 Pod。请先识别受影响的工作负载，然后单独遵循其恢复流程。

在评估结果时，请使用以下状态：

如果 ACP 中可见告警，但未收到外部消息，请先检查 notification policy、receiver group、template 和 notification server，然后再排查 NPU 指标。

#7. 可选的非生产验证

项目曾在非生产环境中，通过在共享 Device Manager 边界注入 DCMI 故障来验证触发路径。验证使用了两个专门构建的镜像：

• 一个使用故障注入构建标签编译的 Ascend Device Plugin 镜像；
• 一个使用相同故障注入支持构建的 NPU Exporter 镜像。

这两个镜像必须同时替换。只替换其中一个组件无法证明完整的检测与隔离路径。

内部验证使用了以下输入：

ASCEND_DCMI_FAULT_INJECT=<logicID>:<hexFaultCode>

测试故障 0:80E3A201 被归类为 SeparateNPU。预期结果是 exporter 健康故障、非零 error-code 指标、Node allocatable 资源减少，以及一个活动的 ACP 告警。

故障注入镜像不作为 NPU 产品包的一部分交付，本页面也不会发布其镜像引用或提供可直接复制粘贴的镜像替换命令。如需在非生产环境中运行此验证，请联系你的集群管理员，获取一个经过批准、带版本号的测试包，其中应包含：

• Device Plugin 和 NPU Exporter 的镜像引用及 digest；
• 适用于两个 DaemonSet 的镜像覆盖清单；
• 已验证的 Demo PrometheusRule；
• 目标命名空间和容器名称；
• 清理与恢复命令；
• 支持的硬件和 NPU Operator 版本。

请使用同一个测试包中的两个镜像，并遵循其清理和恢复说明。不要使用来源未经验证的镜像，也不要在生产 DaemonSet 中设置 ASCEND_DCMI_FAULT_INJECT。在获得经过批准的测试包之前，请将本部分视为验证范围和证据，而不是可执行操作步骤。

#故障排查

#exporter 指标缺失

检查 exporter Pod、ServiceMonitor、Monitoring 目标，以及 Prometheus 或 VictoriaMetrics 后端所选择的标签。

#规则存在，但没有可见告警

检查表达式是否返回时间序列，vmcluster 和 job 标签是否与目标环境匹配，以及告警是否已在其完整的 for 持续时间内保持激活。

#卡是不健康的，但 allocatable 没有减少

检查 Device Plugin 日志和故障码分类。在已验证的故障注入路径中，卡的即时隔离使用的是被归类为 SeparateNPU 的故障。其他故障分类会遵循其配置的处理策略。同时，也要等待下一次 Device Plugin 健康刷新。

#卡已隔离，但 Node 仍然是 Ready

这是设备级隔离的预期行为。Device Plugin 会将受影响的卡从可用于新分配的设备中移除，但不会对 Node 执行 cordon。请确认 reduced allocatable NPU 数量以及 DeviceInfoCfg 中的 Unhealthy 条目。不要期望 Node 显示 SchedulingDisabled。

#运行中的 Pod 仍停留在不健康的卡上

本操作步骤不会自动驱逐或重新调度已经使用受影响卡的 Pod。请先根据卡和 Node 信息识别工作负载，然后再遵循该工作负载的恢复流程。

#告警可见，但没有发送通知

检查 notification policy 名称是否存在、receiver group 和 template 是否有效，以及 notification server 是否可达。在排查 NPU 指标之前，先查看 ACP 中的通知状态。