GPU 与加速器可观测性：DCGM 指标、显存归因与 XID 故障定位

语义差异：
  CPU 利用率 = 非空闲时间占比，接近线性可解释
  GPU "利用率" 至少有三个口径：SM 活跃、显存带宽、Tensor Core 占用
  它们可以同时很高或同时很低，单看一个数字会得出相反结论

故障差异：
  CPU 故障多数表现为进程崩溃或 ECC 内存报错
  GPU 故障表现为 XID 错误、NVLink 降速、显存不可纠正 ECC、
  甚至"静默降频"——任务不报错但变慢

归因差异：
  一个进程独占一个 CPU 核心是常态
  一张 GPU 上可能同时跑多个进程、多个容器、多个 MIG 实例
  不解决归因，"这块卡很忙"就无法回答"该找谁"

典型误判一：GPU_UTIL 98% 但吞吐低
  原因：kernel 之间存在大量串行同步与空洞，或者 kernel 本身访存受限
  佐证：同时看 MEM_COPY_UTIL 与 SM_CLOCK，若带宽打满则是访存瓶颈

典型误判二：GPU_UTIL 30% 但任务"很慢"
  原因：数据加载（DataLoader）在 CPU 侧成为瓶颈，GPU 在等数据
  佐证：看进程的 CPU 使用率与磁盘/网络 IO

典型误判三：显存 OOM 但 FB_FREE 不为 0
  原因：PyTorch 缓存分配器碎片化，或 MIG 实例限额
  佐证：看 FB_USED 的锯齿曲线与 MIG 配置

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: dcgm-exporter
  namespace: gpu-observability
spec:
  selector:
    matchLabels:
      app: dcgm-exporter
  template:
    metadata:
      labels:
        app: dcgm-exporter
    spec:
      nodeSelector:
        nvidia.com/gpu.present: "true"
      tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule
      containers:
      - name: dcgm-exporter
        image: nvcr.io/nvidia/k8s/dcgm-exporter:3.3.5-3.4.0-ubuntu22.04
        args:
        - -f
        - /etc/dcgm-exporter/counters.csv
        - --kubernetes=true
        - --collect-interval=15000
        ports:
        - name: metrics
          containerPort: 9400
        securityContext:
          privileged: false
          capabilities:
            add: ["SYS_ADMIN"]
        volumeMounts:
        - name: dev
          mountPath: /dev
      volumes:
      - name: dev
        hostPath:
          path: /dev

--collect-interval      采集周期，默认 30000ms；训练场景建议 10~15s
--kubernetes=true       附加 Pod/Namespace 标签，需 RBAC 读 Pods
--mig-format            多实例 GPU 的标签格式，决定能否按 MIG 归因
-f counters.csv         白名单式选字段，避免暴露全部 200+ 字段导致基数膨胀

# 方式一：从 dmesg / journald 抓 NVRM 行，转成日志指标
journalctl -k -f | grep -E 'NVRM: Xid' 
# 输出样例：
# NVRM: Xid (PCI:0000:3b:00): 79, pid=12345, GPU has fallen off the bus.

# 方式二：nvidia-smi 查询 XID 与健康状态
nvidia-smi --query-gpu=index,pci.bus_id,xid.errors,retired_pages.pending \
  --format=csv

# 方式三：DCGM 主动诊断（可离线跑，用于送修前取证）
dcgmi diag -r 3 -g 0

groups:
- name: gpu-health
  rules:
  - alert: GPUUncorrectableECC
    expr: increase(DCGM_FI_DEV_ECC_DBE_VOL_TOTAL[1h]) > 0
    labels:
      severity: critical
    annotations:
      summary: "GPU {{ $labels.gpu }} 出现不可纠正 ECC 错误"
      runbook: "确认 XID=48/94，隔离该卡并申请更换"

  - alert: GPUXidError
    expr: DCGM_FI_DEV_XID_ERRORS != 0
    for: 1m
    labels:
      severity: warning
    annotations:
      summary: "GPU {{ $labels.gpu }} XID={{ $value }}，检查 dmesg NVRM 行"

  - alert: GPUThrottling
    expr: DCGM_FI_DEV_SM_CLOCK < DCGM_FI_DEV_SM_CLOCK_MAX * 0.7
    for: 10m
    labels:
      severity: warning
    annotations:
      summary: "GPU {{ $labels.gpu }} 降频超过 30%，检查温度与功耗"

XID 48/94（不可纠正 ECC）
  → 立即隔离该卡：kubectl cordon 节点，或把该 GPU 从资源池摘除
  → dcgmi diag -r 3 留证
  → 更换硬件，不要"再观察一下"

XID 79（掉卡）
  → 通常是 PCIe 链路或供电问题
  → 检查 dmesg 是否有 link down / AER 报错
  → 重启节点后若复现，换卡或换槽位

XID 74（NVLink）
  → nvidia-smi nvlink -s 查看各链路状态与错误计数
  → 多机训练场景下，NVLink 降速会直接拖垮 AllReduce

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: dcgm-exporter-reader
rules:
- apiGroups: [""]
  resources: ["pods", "nodes", "services", "endpoints"]
  verbs: ["get", "list", "watch"]

# 每个训练 Pod 的显存占用（MiB）
sort_desc(
  sum by (namespace, pod) (DCGM_FI_DEV_FB_USED)
)

# 找出"占着卡但没干活"的 Pod：显存高、SM 利用率低
(
  sum by (pod) (DCGM_FI_DEV_FB_USED) > 20000
)
and on (pod)
(
  avg by (pod) (DCGM_FI_DEV_GPU_UTIL) < 5
)

指标区分：
  DCGM_FI_DEV_GPU_UTIL 仍是整卡视角，会把多个实例混在一起
  必须按 GPU_I_ID（实例 ID）与 GPU_I_PROFILE（如 3g.40gb）分组
  显存指标在 MIG 下按实例上报，可精确归因

注意：
  MIG 实例的 SM 数固定，利用率上限受实例规格限制
  混部不同规格实例时，跨实例比较利用率没有意义

关联维度：pod / node / gpu
典型问题：vLLM 的 prefill 延迟上升
  若 GPU_UTIL 同时下降 → 上游请求变少或数据侧阻塞
  若 GPU_UTIL 上升但吞吐下降 → 可能是显存不足触发重算，或降频
  若 SM_CLOCK 下降 → 先查温度与功耗，再看业务

采集频率：
  15s  —— 告警与容量规划（推荐默认）
  1s   —— 短期性能分析，仅临时开启
  60s  —— 长期趋势，可降低远端存储压力

基数控制：
  每卡约 20 个字段 × 8 卡 × 数百节点 = 数万时序
  加上 pod/namespace 标签后基数会放大
  策略：counters.csv 白名单 + 关闭 DCGM_FI_PROF_*
  长期存储用远端写，参考 Prometheus 长期存储方案

必告：
  ECC 不可纠正错误 > 0
  XID 出现在高危码表（48/74/79/94/119/120）
  温度 > 85℃ 持续 5 分钟
  降频（SM_CLOCK / MAX_CLOCK < 0.7）持续 10 分钟
  掉卡（GPU 数量少于期望值）

不该告：
  GPU_UTIL 高 —— 卡忙是正常状态，不是故障
  FB_USED 高 —— 显存占满在设计内
  单次 XID 13 —— 多为应用问题，交业务侧处理

# GPU 利用率长期低于 20% 的卡（闲置浪费）
avg_over_time(DCGM_FI_DEV_GPU_UTIL[7d]) < 20

# 显存分配率高但利用率低（低效使用）
avg_over_time(DCGM_FI_DEV_FB_USED[7d])
  / avg_over_time(DCGM_FI_DEV_FB_TOTAL[7d]) > 0.8
and
avg_over_time(DCGM_FI_DEV_GPU_UTIL[7d]) < 30

□ 用 dcgm-exporter DaemonSet 采集，白名单字段而非全量
□ 指标必须带 gpu / pod / namespace / GPU_I_ID 标签
□ ECC 不可纠正错误与高危 XID 一律 critical 告警
□ 单独监控降频（实际频率 / 最大频率）
□ 显存与利用率交叉查询，识别"占卡不干活"
□ XID 历史从 journald 采集，不只依赖 exporter 的最近值
□ 采集频率 15s 起步，不要用脚本高频调 nvidia-smi
□ GPU 指标与业务指标按 pod 对齐，形成归因闭环