可観測性

本ドキュメントでは、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. GPUStack メトリクスを収集するように Prometheus を構成する
   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、または --builtin-prometheus-port / GPUSTACK_BUILTIN_PROMETHEUS_PORT で設定したポートにアクセスします。
• Grafana UI：
  既定では http://<host>:13000、または --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 のメトリクスへマッピングする方法を、サービスを再起動せずに更新できます。構成は 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 のメトリクス

Server のメトリクス

イベントバスのメトリクス

注意：すべてのメトリクスには、詳細な監視と絞り込みのために、クラスター、Worker、モデル、インスタンス、ユーザーなどの関連識別子のラベルが付いています。