可观测性

本文介绍如何使用 Prometheus 和 Grafana 监控 GPUStack Server、Worker 及 LLM 服务的运行时指标。

概述

GPUStack 为模型服务和 GPU 资源管理提供全面的指标集。通过集成 Prometheus 和 Grafana，用户可以实时收集、存储和可视化这些指标，从而高效监控和排查问题。

内置可观测性（默认）

默认情况下，GPUStack 会启动内嵌的 Prometheus 和 Grafana。可通过以下地址访问：

• Prometheus：http://your_gpustack_server_host_ip/prometheus
• Grafana：http://your_gpustack_server_host_ip/grafana

内置 Grafana 已配置匿名 Viewer 访问，并禁用登录表单。管理员凭据默认仍为 admin / grafana。

外部可观测性（可选）

如果希望使用外部 Prometheus/Grafana 环境，建议使用提供的 Docker Compose 文件：

运行以下命令克隆最新稳定版本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

LATEST_TAG=$(
    curl -s "https://api.github.com/repos/gpustack/gpustack/releases" \
    | grep '"tag_name"' \
    | sed -E 's/.*"tag_name": "([^"]+)".*/\1/' \
    | grep -Ev 'rc|beta|alpha|preview' \
    | head -1
)
echo "Latest stable release: $LATEST_TAG"
git clone -b "$LATEST_TAG" https://github.com/gpustack/gpustack.git
cd gpustack/docker-compose

启动前，将 GPUSTACK_GRAFANA_URL 设置为浏览器可访问的 Grafana URL，而不是 grafana 这类仅容器内可访问的主机名。

启动外部 Prometheus/Grafana（这会禁用内置环境）：

1

sudo docker compose -f docker-compose.external-observability.yaml up -d

如果已有外部 Prometheus/Grafana 环境，也可以改为手动配置：

1. 配置 Prometheus 抓取 GPUStack 指标\ 为 GPUStack 指标端点（默认 :10161）和 Worker 发现端点添加目标。例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

scrape_configs:
  - job_name: gpustack-worker-discovery
    scrape_interval: 5s
    http_sd_configs:
      - url: "http://<gpustack_server_host>:10161/metrics/targets"
        refresh_interval: 1m
  - job_name: gpustack-server
    scrape_interval: 10s
    static_configs:
      - targets: ["<gpustack_server_host>:10161"]

访问指标

• GPUStack 指标端点：\ 在 http://<gpustack_server_host>:10161/metrics 访问指标。
• GPUStack Worker 指标目标：\ 在 http://<gpustack_server_host>:10161/metrics/targets 访问指标。
• Prometheus UI：\ 默认通过 http://<host>:19090 访问 Prometheus，或使用 --builtin-prometheus-port / GPUSTACK_BUILTIN_PROMETHEUS_PORT 配置的端口。
• Grafana UI：\ 默认通过 http://<host>:13000 访问 Grafana，或使用 --builtin-grafana-port / GPUSTACK_BUILTIN_GRAFANA_PORT 配置的端口。内置 Grafana 已配置匿名 Viewer 访问，并禁用登录表单。管理员凭据默认仍为 admin / grafana。

从旧版 Compose 配置迁移

如果此前使用 Docker Compose 在 GPUStack 之外运行 Prometheus/Grafana：

• 保留外部可观测性（建议用于保持连续性）：\ 继续运行现有 Prometheus/Grafana 容器。将 Prometheus 抓取目标更新为新的 GPUStack 指标端点，并将 GPUSTACK_GRAFANA_URL 设置为现有 Grafana。

• 切换到内置可观测性：\ 停止旧 Prometheus/Grafana 容器，然后使用最新的 docker-compose.server.yaml（仅 GPUStack）。内置 Grafana/Prometheus 会接管。旧 Prometheus 的历史指标不会迁移；如需保留访问，可以将旧环境以只读方式保留。

自定义指标映射

GPUStack 支持通过配置 API 动态自定义指标映射，无需重启服务即可更新运行时引擎指标到 GPUStack 指标的映射方式。配置集中在 GPUStack Server 上管理，可通过 HTTP API 访问或修改。

API 端点

• 获取当前指标配置

• GET http://<gpustack_server_host>:<gpustack_server_port>/v2/metrics/config

• 以 JSON 格式返回当前指标映射配置。

• 更新指标配置

• POST http://<gpustack_server_host>:<gpustack_server_port>/v2/metrics/config

• 接受 JSON 请求体，更新指标映射配置。更改会立即对所有 Worker 生效。

• 获取默认指标配置

• GET http://<gpustack_server_host>:<gpustack_server_port>/v2/metrics/default-config
• 以 JSON 格式返回默认指标映射配置，便于参考或重置。

使用示例

获取当前配置：

1

curl http://<gpustack_server_host>:<gpustack_server_port>/v2/metrics/config

更新配置：

1
2
3

curl -X POST http://<gpustack_server_host>:<gpustack_server_port>/v2/metrics/config \
     -H "Content-Type: application/json" \
     -d @custom_metrics_config.json

（其中 custom_metrics_config.json 是你的新配置文件）

获取默认配置：

1

curl http://<gpustack_server_host>:<gpustack_server_port>/v2/metrics/default-config

说明：配置必须采用有效的 JSON 格式。

GPUStack 暴露的指标

以下指标由 GPUStack 暴露，可由 Prometheus 抓取。每个指标都包含用于识别集群、Worker、模型和实例的层级标签。

LLM 服务运行时指标

这些指标按照 metrics_config.yaml 中的定义，从不同运行时引擎（vLLM、SGLang、MindIE）映射而来。

Worker 指标

GPUStack Server 指标

事件总线指标

说明：所有指标均带有相关标识符标签（集群、Worker、模型、实例、用户），便于细粒度监控和筛选。