DCGM Exporter Docker

一个用于监控 Docker 容器 GPU 内存使用的 Prometheus Exporter。

功能特性

✅ 支持 Prometheus 格式输出
✅ 监控每个容器的 GPU 内存使用量和占比
✅ 支持监控容器内子进程的 GPU 使用情况
✅ 实时收集 GPU 硬件指标（温度、功耗、利用率等）
✅ 通过 cgroup 追踪容器资源使用
✅ 健康检查和状态监控端点
✅ 支持真实 NVIDIA GPU 数据收集（通过 NVML）

指标说明

GPU 硬件指标

gpu_temperature_celsius - GPU 温度（摄氏度）
gpu_power_usage_watts - GPU 功耗（瓦特）
gpu_utilization_percent - GPU 利用率（百分比）
gpu_memory_total_bytes - GPU 总内存（字节）
gpu_memory_used_bytes - GPU 已用内存（字节）
gpu_memory_utilization_percent - GPU 内存利用率（百分比）

所有 GPU 指标都包含以下标签：

gpu_id - GPU ID
gpu_uuid - GPU UUID
gpu_name - GPU 名称
hostname - GPU 所在主机名

容器 GPU 使用指标

container_gpu_memory_used_bytes - 容器使用的 GPU 内存（字节）
container_gpu_memory_utilization_percent - 容器 GPU 内存利用率（百分比）
container_gpu_process_count - 容器中使用 GPU 的进程数量

Exporter 指标

exporter_up - Exporter 运行状态
exporter_errors_total - Exporter 错误总数
exporter_collection_duration_seconds - 收集周期耗时

安装要求

系统要求

Linux 系统（支持 cgroup）
NVIDIA 驱动已安装（真实 GPU 模式）
Go 1.21 或更高版本（本地构建）

依赖组件

NVIDIA Container Toolkit（Docker GPU 支持）
NVML (NVIDIA Management Library)

Docker 数据目录配置（重要）

⚠️ 启动容器前必须检查并配置正确的 Docker 数据目录挂载！

Exporter 需要访问 Docker 数据目录来读取容器信息。默认使用 /var/lib/docker，但如果您的 Docker 配置了自定义 data-root，必须挂载正确的目录。

第一步：检查您的 Docker 数据目录

# 方法1: 查看 Docker 配置文件
cat /etc/docker/daemon.json | grep "data-root"

# 方法2: 使用 docker info
docker info | grep "Docker Root Dir"

第二步：根据检查结果配置挂载

如果使用默认目录 (/var/lib/docker)：

docker run -d \
  --name dcgm-docker-exporter \
  -v /var/lib/docker:/var/lib/docker:ro \
  -v /etc/docker/daemon.json:/etc/docker/daemon.json:ro \
  ...

如果使用自定义目录 (例如 /data/docker)：

# ⚠️  必须将主机的实际目录挂载到容器的相同路径！
docker run -d \
  --name dcgm-docker-exporter \
  -v /data/docker:/data/docker:ro \
  -v /etc/docker/daemon.json:/etc/docker/daemon.json:ro \
  ...

注意：Exporter 会自动读取 /etc/docker/daemon.json 中的 data-root 配置来定位容器数据，但您必须确保在启动容器时正确挂载了对应的目录。

快速开始

方法一：Docker 部署（推荐）

项目已简化为单一 Dockerfile，基于 Debian 构建，支持真实 GPU 数据：

1. 使用 Docker Compose（最简单）

# 启动所有服务（exporter + prometheus + grafana）
make up

# 查看服务状态
make ps

# 查看日志
make logs

2. 手动 Docker 命令

# 构建镜像（使用 Debian 基础镜像，内置 NVML 支持）
docker build -t dcgm-docker-exporter .

# 运行容器（使用真实 GPU 数据）
docker run -d \
  --name dcgm-docker-exporter \
  --privileged \
  --runtime=nvidia \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  -v /var/lib/docker:/var/lib/docker:ro \
  -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -v /proc:/host/proc:ro \
  -p 9401:9401 \
  dcgm-docker-exporter

# 运行容器（使用模拟数据 - 无需 GPU）
docker run -d \
  --name dcgm-docker-exporter \
  -p 9401:9401 \
  dcgm-docker-exporter -mock=true

方法二：本地构建运行

1. 克隆项目

git clone <repository-url>
cd dcgm-docker-exporter

2. 构建项目

# 使用构建脚本
./build.sh

# 或使用 make
make build

3. 运行 Exporter

# 使用真实 GPU 数据（需要 root 权限）
sudo ./dcgm-docker-exporter

# 或使用模拟数据
./dcgm-docker-exporter -mock=true

4. 验证运行

# 查看指标
curl http://localhost:9401/metrics

# 健康检查
curl http://localhost:9401/health

# 查看容器日志
make docker-logs

命令行参数

./dcgm-docker-exporter -h

Usage of ./dcgm-docker-exporter:
  -collect.interval duration
    	Collection interval (default 15s)
  -log.level string
    	Logging level (debug, info, warn, error) (default "info")
  -mock
    	Use mock data instead of real GPU/container data (default false)
  -web.listen-address string
    	Address to listen on for web interface and telemetry. (default ":9401")
  -web.telemetry-path string
    	Path under which to expose metrics. (default "/metrics")

运行模式

真实 GPU 模式（默认）

# 使用真实 NVIDIA GPU 数据
./dcgm-docker-exporter

# 或明确指定
./dcgm-docker-exporter -mock=false

模拟数据模式

# 使用模拟数据进行演示
./dcgm-docker-exporter -mock=true

Docker 部署

Docker Compose 配置

version: '3.8'
services:
  dcgm-docker-exporter:
    build: .
    ports:
      - "9401:9401"
    privileged: true
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,utility
    volumes:
      - /var/lib/docker:/var/lib/docker:ro
      - /sys/fs/cgroup:/sys/fs/cgroup:ro
      - /proc:/host/proc:ro
    command: [
      "-web.listen-address=:9401",
      "-collect.interval=15s",
      "-mock=false"
    ]

Makefile 命令

make help                 # 显示帮助信息
make build                # 本地构建 Go 二进制文件
make docker-build         # 构建 Docker 镜像（Debian + NVML）
make docker-run           # 运行容器（真实 GPU 模式）
make docker-run-mock      # 运行容器（模拟数据模式）
make up                   # 启动所有服务（docker-compose）
make down                 # 停止所有服务
make logs                 # 查看服务日志
make dev                  # 启动开发环境（Prometheus + Grafana）
make demo                 # 运行本地演示
make run-real             # 运行真实 GPU 监控
make system-check         # 检查系统要求

真实 GPU 监控配置

要监控真实的 GPU 和容器使用情况，需要进行以下配置：

1. 系统要求

NVIDIA 驱动已安装
NVIDIA Container Toolkit 已配置
Docker 支持 GPU

2. 检查 GPU 支持

make system-check

3. Docker 运行配置

# 构建镜像
make docker-build

# 运行 GPU 监控容器
make docker-run

# 或者手动运行
docker run -d \
  --name dcgm-docker-exporter \
  --privileged \
  --runtime=nvidia \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  -v /var/lib/docker:/var/lib/docker:ro \
  -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -v /proc:/host/proc:ro \
  -p 9401:9401 \
  dcgm-docker-exporter:latest

集成 Prometheus

在 Prometheus 配置文件中添加：

scrape_configs:
  - job_name: 'dcgm-docker-exporter'
    static_configs:
      - targets: ['localhost:9401']
    scrape_interval: 15s

Grafana 面板

可以导入预定义的 Grafana 面板来可视化 GPU 和容器指标。

故障排除

常见问题

权限不足
```
Error: Failed to initialize NVML
```
解决：使用 sudo 运行或确保用户有访问 GPU 设备的权限。

Docker GPU 运行时错误

docker: Error response from daemon: could not select device driver "nvidia"

解决：安装 NVIDIA Container Toolkit：

# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

找不到容器信息
```
Warning: No Docker containers found
```
解决：确保 Docker 正在运行，且容器使用了 GPU。
cgroup 路径问题
```
Error: Failed to read cgroup data
```
解决：检查系统使用的 cgroup 版本，目前支持 v1 和 v2。

调试命令

# 检查 GPU 状态
nvidia-smi

# 进入容器调试
make docker-shell

# 查看详细日志
docker logs dcgm-docker-exporter

# 检查系统要求
make system-check

日志级别

debug: 详细调试信息
info: 常规运行信息（默认）
warn: 警告信息
error: 错误信息

架构说明

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   NVML Library  │◄──►│  GPU Collector   │◄──►│  Prometheus     │
│  (NVIDIA Driver)│    │                  │    │  Metrics        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
┌─────────────────┐    ┌──────────────────┐
│   cgroup FS     │◄──►│Container Tracker │
│  (/sys/fs/cgroup)│    │                  │
└─────────────────┘    └──────────────────┘

开发

项目结构

dcgm-docker-exporter/
├── collector/              # 数据收集器
│   ├── mock_collector.go   # 模拟数据收集器
│   └── real_gpu_collector.go # 真实 GPU 数据收集器
├── metrics/                # Prometheus 指标
│   └── metrics.go
├── types/                  # 数据类型定义
│   └── types.go
├── main.go                 # 主程序入口
├── Dockerfile              # Docker 构建文件（Debian + NVML）
├── docker-compose.yml      # Docker Compose 配置
├── Makefile                # 构建和部署命令
├── go.mod                  # Go 模块定义
├── build.sh                # 构建脚本
├── demo.sh                 # 演示脚本
├── prometheus-example.yml  # Prometheus 配置示例
├── prometheus-queries.txt  # 查询语句示例
└── README.md               # 说明文档

添加新指标

在 types/types.go 中定义数据结构
在 metrics/metrics.go 中添加 Prometheus 指标
在 collector/real_gpu_collector.go 或 collector/mock_collector.go 中更新收集逻辑

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.idea		.idea
collector		collector
include		include
metrics		metrics
types		types
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
grafana-dashboard-screenshot.png		grafana-dashboard-screenshot.png
grafana-dashboard.json		grafana-dashboard.json
main.go		main.go
prometheus-example.yml		prometheus-example.yml
prometheus-queries.txt		prometheus-queries.txt

Folders and files

Latest commit

History

Repository files navigation

DCGM Exporter Docker

功能特性

指标说明

GPU 硬件指标

容器 GPU 使用指标

Exporter 指标

安装要求

系统要求

依赖组件

Docker 数据目录配置（重要）

快速开始

方法一：Docker 部署（推荐）

1. 使用 Docker Compose（最简单）

2. 手动 Docker 命令

方法二：本地构建运行

1. 克隆项目

2. 构建项目

3. 运行 Exporter

4. 验证运行

命令行参数

运行模式

真实 GPU 模式（默认）

模拟数据模式

Docker 部署

Docker Compose 配置

Makefile 命令

真实 GPU 监控配置

1. 系统要求

2. 检查 GPU 支持

3. Docker 运行配置

集成 Prometheus

Grafana 面板

故障排除

常见问题

调试命令

日志级别

架构说明

开发

项目结构

添加新指标

许可证

贡献

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages