DCGM-Exporter

此仓库包含 DCGM-Exporter 项目。它利用 NVIDIA DCGM，为 Prometheus 提供 GPU 指标导出器。

文档

DCGM-Exporter 的官方文档可在 docs.nvidia.com 上找到。

快速入门

要在 GPU 节点上收集指标，只需启动 dcgm-exporter 容器：

docker run -d --gpus all --cap-add SYS_ADMIN --rm -p 9400:9400 nvcr.io/nvidia/k8s/dcgm-exporter:4.5.2-4.8.1-distroless
curl localhost:9400/metrics
# HELP DCGM_FI_DEV_SM_CLOCK SM 时钟频率（单位：MHz）。
# TYPE DCGM_FI_DEV_SM_CLOCK gauge
# HELP DCGM_FI_DEV_MEM_CLOCK 显存时钟频率（单位：MHz）。
# TYPE DCGM_FI_DEV_MEM_CLOCK gauge
# HELP DCGM_FI_DEV_MEMORY_TEMP 显存温度（单位：℃）。
# TYPE DCGM_FI_DEV_MEMORY_TEMP gauge
...
DCGM_FI_DEV_SM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 139
DCGM_FI_DEV_MEM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 405
DCGM_FI_DEV_MEMORY_TEMP{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 9223372036854775794
...

Kubernetes 上的快速入门

注意：建议使用 NVIDIA GPU Operator，而不是直接使用 DCGM-Exporter。

请确保您的集群已设置为使用 NVIDIA 默认运行时。

安装 DCGM-Exporter 的推荐方式是使用 Helm 图表：

helm repo add gpu-helm-charts \
  https://nvidia.github.io/dcgm-exporter/helm-charts

更新仓库：

helm repo update

然后安装图表：

helm install \
    --generate-name \
    gpu-helm-charts/dcgm-exporter

一旦 dcgm-exporter Pod 部署完毕，您可以通过端口转发快速获取指标：

kubectl create -f https://raw.githubusercontent.com/NVIDIA/dcgm-exporter/master/dcgm-exporter.yaml

# 获取任意一个 Pod 的输出：
NAME=$(kubectl get pods -l "app.kubernetes.io/name=dcgm-exporter" \
                         -o "jsonpath={ .items[0].metadata.name}")

kubectl port-forward $NAME 8080:9400 &

curl -sL http://127.0.0.1:8080/metrics
# HELP DCGM_FI_DEV_SM_CLOCK SM 时钟频率（单位：MHz）。
# TYPE DCGM_FI_DEV_SM_CLOCK gauge
# HELP DCGM_FI_DEV_MEM_CLOCK 显存时钟频率（单位：MHz）。
# TYPE DCGM_FI_DEV_MEM_CLOCK gauge
# HELP DCGM_FI_DEV_MEMORY_TEMP 显存温度（单位：℃）。
# TYPE DCGM_FI_DEV_MEMORY_TEMP gauge
...
DCGM_FI_DEV_SM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52",container="",namespace="",pod=""} 139
DCGM_FI_DEV_MEM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52",container="",namespace="",pod=""} 405
DCGM_FI_DEV_MEMORY_TEMP{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52",container="",namespace="",pod=""} 9223372036854775794
...

要将 DCGM-Exporter 与 Prometheus 和 Grafana 集成，请参阅 用户指南 中的完整说明。dcgm-exporter 已作为 GPU Operator 的一部分部署。要开始与 Prometheus 集成，请查看 Operator 的 用户指南。

TLS 和基本认证

导出器支持使用 exporter-toolkit 实现 TLS 和基本认证。要使用 TLS 和/或基本认证，用户需要使用 --web-config-file CLI 标志，如下所示：

dcgm-exporter --web-config-file=web-config.yaml

示例 web-config.yaml 文件可从 exporter-toolkit 仓库 获取。有关 web-config.yaml 文件的参考信息，请参阅 文档。

如何在指标标签中包含 HPC 作业信息

DCGM-exporter 可以将高性能计算 (HPC) 作业信息纳入其指标标签中。为此，HPC 环境管理员必须配置其 HPC 环境，以生成将 GPU 映射到 HPC 作业的文件。

文件约定

这些映射文件遵循特定格式：

• 每个文件的命名基于唯一的 GPU ID 或唯一的 GPU ID 与 GPU 实例（MIG）ID，两者之间用“.”分隔（例如：0、1、2.0、2.1、3 等）。
• 文件中的每一行包含在相应 GPU/MIG 实例上运行的 JOB ID。

在 DCGM-Exporter 上启用 HPC 作业映射

要在 DCGM-Exporter 端启用 GPU 到作业的映射，用户必须使用 --hpc-job-mapping-dir 命令行参数运行 DCGM-Exporter，并指向 HPC 集群创建作业映射文件的目录。或者，用户也可以设置环境变量 DCGM_HPC_JOB_MAPPING_DIR 来达到相同的效果。

从源代码构建

要构建 dcgm-exporter，请确保您具备以下条件：

• 已安装 Golang >= 1.24
• 已安装 DCGM
• 拥有兼容 DCGM 的带有 GPU 的 Linux 机器。

git clone https://github.com/NVIDIA/dcgm-exporter.git
cd dcgm-exporter
make binary
sudo make install
...
dcgm-exporter &
curl localhost:9400/metrics
# HELP DCGM_FI_DEV_SM_CLOCK SM 时钟频率（单位：MHz）。
# TYPE DCGM_FI_DEV_SM_CLOCK gauge
# HELP DCGM_FI_DEV_MEM_CLOCK 显存时钟频率（单位：MHz）。
# TYPE DCGM_FI_DEV_MEM_CLOCK gauge
# HELP DCGM_FI_DEV_MEMORY_TEMP 显存温度（单位：℃）。
# TYPE DCGM_FI_DEV_MEMORY_TEMP gauge
...
DCGM_FI_DEV_SM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 139
DCGM_FI_DEV_MEM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 405
DCGM_FI_DEV_MEMORY_TEMP{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 9223372036854775794
...

修改指标

借助 dcgm-exporter，您可以通过指定自定义 CSV 文件来配置要收集的字段。默认的 CSV 文件位于仓库中的 etc/default-counters.csv，该文件会被复制到您的系统或容器中的 /etc/dcgm-exporter/default-counters.csv。

该文件的布局和格式如下：

# 格式
# 如果行以 '#' 开头，则被视为注释
# DCGM 字段, Prometheus 指标类型, 帮助信息

# 时钟
DCGM_FI_DEV_SM_CLOCK,  gauge, SM 时钟频率（单位：MHz）。
DCGM_FI_DEV_MEM_CLOCK, gauge, 显存时钟频率（单位：MHz）。

可以使用 -f 选项或 --collectors 指定自定义 CSV 文件，如下所示：

dcgm-exporter -f /tmp/custom-collectors.csv

注意事项：

• 务必确保每条记录包含两个逗号（',')
• 可以收集的完整计数器列表可在 DCGM API 参考手册中找到： https://docs.nvidia.com/datacenter/dcgm/latest/dcgm-api/dcgm-api-field-ids.html

那 Grafana 仪表板呢？

您可以在以下链接找到官方的 NVIDIA DCGM-Exporter 仪表板：https://grafana.com/grafana/dashboards/12239

此外，您也可以在本仓库的 grafana/dcgm-exporter-dashboard.json 文件中找到对应的 json 文件。

您可以在这里找到 DCGM-Exporter 的 OpenObserve 仪表板

NVIDIA DCGM-Exporter 的仪表板地址为：https://github.com/openobserve/dashboards/tree/main/NVIDIA%20GPU%20Monitoring

要将 DCGM-Exporter 与 OpenObserve 集成，请参考博客文章 使用 OpenObserve 监控 GPU。

欢迎提交 Pull Request！

构建容器

该项目使用 docker buildx 来构建多架构镜像。请按照该页面的说明设置一个可用的构建器实例，以便创建这些容器。以下是一些其他有用的构建选项。

基于当前机器架构构建本地镜像，并将其添加到 docker images 中：

make local

构建无发行版（distroless）镜像并导出到 docker images：

make distroless PLATFORMS=linux/amd64 OUTPUT=type=docker

构建镜像并推送到某个私有镜像仓库：

make REGISTRY=<private_registry> push

问题与贡献

请查看贡献文档！

• 如需社区支持，请提交新 issue。
• 您可以通过打开 pull request 来做出贡献。

安全漏洞报告

我们要求所有社区成员和 DCGM Exporter 用户遵循 NVIDIA 标准的安全漏洞报告流程。该流程已在 NVIDIA 产品安全 网站上记录。遵循此流程将确保生成必要的 CVE 编号，并向整个 DCGM Exporter 社区发送适当的通知。NVIDIA 保留删除未修复漏洞报告的权利。

有关安全漏洞报告的相关问题，请参阅该网站上列出的政策。

DCGM-Exporter 快速上手指南

DCGM-Exporter 是一个基于 NVIDIA DCGM 的 GPU 指标导出器，可将 GPU 监控数据暴露给 Prometheus。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux 系统。
• 硬件：配备兼容 DCGM 的 NVIDIA GPU。
• 驱动与运行时：已安装 NVIDIA 驱动，并配置好容器运行时（如 Docker 或 Kubernetes），确保默认运行时为 nvidia。
• 依赖工具：
  • 单机部署需安装 Docker。
  • Kubernetes 部署需安装 kubectl 和 helm。
  • （可选）源码编译需安装 Golang >= 1.24 及 DCGM 开发库。

安装步骤

方式一：Docker 单机部署（推荐快速测试）

直接运行官方容器即可启动导出器：

docker run -d --gpus all --cap-add SYS_ADMIN --rm -p 9400:9400 nvcr.io/nvidia/k8s/dcgm-exporter:4.5.2-4.8.1-distroless

方式二：Kubernetes 集群部署

建议使用 Helm Chart 进行安装。

1. 添加 Helm 仓库：

   helm repo add gpu-helm-charts \
     https://nvidia.github.io/dcgm-exporter/helm-charts
   

2. 更新仓库索引：

   helm repo update
   

3. 安装 DCGM-Exporter：

   helm install \
       --generate-name \
       gpu-helm-charts/dcgm-exporter
   

注意：在生产环境的 Kubernetes 集群中，更推荐使用 NVIDIA GPU Operator，它会自动包含并管理 DCGM-Exporter。

基本使用

安装完成后，您可以通过以下方式验证指标是否正常采集。

1. 验证指标输出

Docker 环境： 直接使用 curl 访问本地端口：

curl localhost:9400/metrics

Kubernetes 环境： 通过端口转发将 Pod 的 9400 端口映射到本地 8080 端口：

# 获取 Pod 名称
NAME=$(kubectl get pods -l "app.kubernetes.io/name=dcgm-exporter" \
                         -o "jsonpath={ .items[0].metadata.name}")

# 执行端口转发
kubectl port-forward $NAME 8080:9400 &

# 获取指标
curl -sL http://127.0.0.1:8080/metrics

预期输出示例：

# HELP DCGM_FI_DEV_SM_CLOCK SM clock frequency (in MHz).
# TYPE DCGM_FI_DEV_SM_CLOCK gauge
DCGM_FI_DEV_SM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 139
# HELP DCGM_FI_DEV_MEM_CLOCK Memory clock frequency (in MHz).
# TYPE DCGM_FI_DEV_MEM_CLOCK gauge
DCGM_FI_DEV_MEM_CLOCK{gpu="0", UUID="GPU-604ac76c-d9cf-fef3-62e9-d92044ab6e52"} 405

2. 自定义采集指标

默认情况下，DCGM-Exporter 会采集一组预设指标。如需自定义，可创建一个 CSV 配置文件（格式参考 /etc/dcgm-exporter/default-counters.csv），并通过 -f 参数指定：

dcgm-exporter -f /tmp/custom-collectors.csv

CSV 文件格式示例：

# DCGM FIELD, Prometheus metric type, help message
DCGM_FI_DEV_SM_CLOCK,  gauge, SM clock frequency (in MHz).
DCGM_FI_DEV_MEM_CLOCK, gauge, Memory clock frequency (in MHz).

3. 后续集成

获取到指标后，您需要在 Prometheus 配置中添加 dcgm-exporter 作为抓取目标（Scrape Job），并导入 Grafana 仪表盘（ID: 12239）以实现可视化监控。