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.3-4.8.2-distroless
curl localhost:9400/metrics
# HELP DCGM_FI_DEV_SM_CLOCK SM clock frequency (in MHz).
# TYPE DCGM_FI_DEV_SM_CLOCK gauge
# HELP DCGM_FI_DEV_MEM_CLOCK Memory clock frequency (in MHz).
# TYPE DCGM_FI_DEV_MEM_CLOCK gauge
# HELP DCGM_FI_DEV_MEMORY_TEMP Memory temperature (in C).
# 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 chart：

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

# Let's get the output of a random 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
# HELP DCGM_FI_DEV_MEM_CLOCK Memory clock frequency (in MHz).
# TYPE DCGM_FI_DEV_MEM_CLOCK gauge
# HELP DCGM_FI_DEV_MEMORY_TEMP Memory temperature (in C).
# 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 支持使用 exporter-toolkit 进行 TLS 和基本身份验证。要使用 TLS 和/或基本身份验证，用户需要按如下方式使用 --web-config-file CLI 标志

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

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

IPv6 支持

DCGM-Exporter 支持对远程 hostengine 连接（-r）和指标监听地址（-a）使用 IPv6 地址。当 IPv6 地址与端口结合使用时，必须采用方括号表示法。

远程 Hostengine（CLI）

dcgm-exporter -r "[::1]:5555"

远程主机引擎（环境变量）

export DCGM_REMOTE_HOSTENGINE_INFO="[::1]:5555"
dcgm-exporter

指标监听地址

dcgm-exporter -a "[::]:9400"

注意： [::1]:5555 中的方括号是 DCGM 连接协议的要求。使用命令行界面时，shell 需要用引号（双引号或单引号）将地址括起来，以防止对方括号进行解释。

前提条件

远程 nv-hostengine 必须配置为监听 IPv6。有关配置 nv-hostengine 绑定地址选项的信息，请参阅 DCGM 文档。

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

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

文件约定

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

• 每个文件均以唯一的 GPU ID 命名，或者以唯一的 GPU ID 和 GPU 实例（MIG）ID 命名，两者之间用 "." 分隔（例如，0、1、2.0、2.1、3 等）。
• 文件中的每一行包含在相应 GPU/MIG 实例上运行的作业 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
• 拥有配备 GPU 的 Linux 机器，且该 GPU 与 DCGM 兼容。

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 clock frequency (in MHz).
# TYPE DCGM_FI_DEV_SM_CLOCK gauge
# HELP DCGM_FI_DEV_MEM_CLOCK Memory clock frequency (in MHz).
# TYPE DCGM_FI_DEV_MEM_CLOCK gauge
# HELP DCGM_FI_DEV_MEMORY_TEMP Memory temperature (in C).
# 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 文件来配置要收集的字段。 您可以在仓库的 etc/default-counters.csv 路径下找到默认的 CSV 文件，该文件会被复制到您的系统或容器中的 /etc/dcgm-exporter/default-counters.csv 路径。

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

# Format
# If line starts with a '#' it is considered a comment
# DCGM FIELD, Prometheus metric type, help message

# Clocks
DCGM_FI_DEV_SM_CLOCK,  gauge, SM clock frequency (in MHz).
DCGM_FI_DEV_MEM_CLOCK, gauge, Memory clock frequency (in MHz).

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

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

注意事项：

• 请确保您的条目始终包含 2 个逗号（','）
• 可收集的完整计数器列表可在 DCGM API 参考手册中找到：https://docs.nvidia.com/datacenter/dcgm/latest/dcgm-api/dcgm-api-field-ids.html

剖析指标

请注意，对于 Ampere 及更早代系的 GPU，剖析指标依赖于 datacenter-gpu-manager-4-proprietary 包。此包已包含在容器中。

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 GPU Monitoring

要将 DCGM-Exporter 与 OpenObserve 集成，请遵循博客文章《使用 OpenObserve 监控 GPU》（monitoring GPU with OpenObserve）中的步骤。

我们接受拉取请求！

构建容器

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

基于机器架构构建本地镜像，并使其在“docker images”中可用

make local

构建无发行版镜像并导出至“docker images”

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

构建镜像并将其推送到其他“private_registry”

make REGISTRY=<private_registry> push

问题反馈与贡献指南

查看贡献文档！

• 如需社区支持，请提交新 issue
• 您可以通过创建拉取请求参与贡献

报告安全问题

我们要求所有社区成员和 DCGM Exporter 的用户遵循 NVIDIA 标准流程报告安全漏洞。该流程详见 NVIDIA 产品安全 网站。 遵循此流程将确保创建所需的 CVE，并向整个 DCGM Exporter 社区传达适当的通知。在漏洞修复之前，NVIDIA 保留删除漏洞报告的权利。

有关报告安全问题的相关疑问，请参考该网站列出的政策。