# 使用 Prometheus 和 Grafana 监控 Rollout

**作者：** `https://github.com/meituan-search`

最后更新：11/12/2025.

在使用 verl 时，使用 Prometheus 和 Grafana 来监控 rollout 计算过程，以增强系统的可观测性，并便于进一步的性能优化。

我们提供额外的训练监控能力，借助 Prometheus 和 Grafana 来在训练期间展示 rollout 信息，并增强系统可观测性，以便于进一步的性能优化。

系统会自动配置 Prometheus 来从 rollout 服务器抓取指标，从而消除手动配置的步骤。
    
> 注意：SGLang 集成目前正在开发和调试中。某些功能可能无法按预期工作，且实现可能会发生变化。请在生产环境中谨慎使用。

## 概述

下图展示了 Qwen235B 在 AIME2024 数据集上的性能，响应长度为 20k，其中长尾问题的出现非常明显。

![fully_async_policy_structure](
https://github.com/ArronHZG/verl-community/blob/main/docs/grafana_validate.png?raw=true)

下图展示了 Qwen235B 模型的完全异步训练。这里，资源闲置问题非常明显，表明 rollout 资源可以减少。

![fully_async_policy_structure](
https://github.com/ArronHZG/verl-community/blob/main/docs/grafana_fully_async_train.png?raw=true)

通过以上两个示例，我们也展示了系统可观测性的必要性。

## 架构概述

整体工作流程包括以下步骤：

1. **多节点 Ray 集群设置**：在多个节点上启动 Ray 集群，并在主节点的环境变量中配置 Grafana 和 Prometheus 的信息
2. **启动 Grafana 服务**：在主节点上启动 Grafana，用于监控仪表盘的可视化
3. **启动 Prometheus 服务**：在主节点上启动 Prometheus，用于指标收集和存储
4. **verl 异步 Rollout 模式**：verl 使用异步 rollout 模式来获取 rollout 服务器的端口和 IP 地址
5. **自动 Prometheus 配置**：verl 自动重写 Prometheus 配置，以添加对 rollout 服务器的监控，并通知 Prometheus 重新加载配置
6. **指标收集**：程序执行后，可以在 Prometheus 中查看指标
7. **仪表盘可视化**：在 Grafana 仪表盘中上传并查看监控指标

## 详细设置步骤

### 步骤 1：环境变量设置并启动 Ray 集群

首先，设置必要的环境变量并启动 Ray 服务。

> 参考：[configure-manage-dashboard](https://docs.ray.io/en/latest/cluster/configure-manage-dashboard.html)

```bash
# 主节点环境变量
export GF_SERVER_HTTP_PORT=3000                     # Grafana 服务默认端口（可自定义）
export PROMETHEUS_PORT=9090                         # Prometheus 服务默认端口（可自定义）
export RAY_HEAD_PORT=6379                           # Ray 主节点端口（可自定义）
export RAY_DASHBOARD_PORT=8265                      # Ray 仪表盘默认端口（可自定义）
export GRAFANA_PATHS_DATA=/tmp/grafana              # Grafana 数据存储目录（可自定义）
export RAY_GRAFANA_HOST="http://${master_ip}:${GF_SERVER_HTTP_PORT}"        # Ray 关联的 Grafana 地址
export RAY_PROMETHEUS_HOST="http://${master_ip}:${PROMETHEUS_PORT}"         # Ray 关联的 Prometheus 地址

# 在主节点启动 Ray
ray start --head --port=${RAY_HEAD_PORT} --dashboard-port=${RAY_DASHBOARD_PORT}

# 在工作节点启动 Ray
ray start --address={master_addr}:${RAY_HEAD_PORT}
```

**验证：** 访问 `http://master_ip:8265` 以确认 Ray 已成功启动。

### 步骤 2：启动 Grafana（可视化仪表盘）

Grafana 用于展示 Prometheus 收集的指标（例如缓存命中率、吞吐量等）：

```bash
# 主节点
nohup grafana-server \
  --config /tmp/ray/session_latest/metrics/grafana/grafana.ini \
  --homepath /usr/share/grafana \
  web > grafana.log 2>&1 &
```

**验证：** 访问 `http://master_ip:3000` 以确认 Grafana 已成功启动（默认凭据：`admin/admin`）。

如果需要更改端口，请修改 `GF_SERVER_HTTP_PORT` 环境变量，grafana-server 会自动识别它。

### 步骤 3：启动 Prometheus（指标收集）

Prometheus 负责从 vLLM 服务抓取指标，并将其存储为时间序列数据：

```bash
# 主节点
nohup prometheus \
  --config.file /tmp/ray/session_latest/metrics/prometheus/prometheus.yml \
  --web.enable-lifecycle \
  --web.listen-address=:${PROMETHEUS_PORT} \
  > prometheus.log 2>&1 &
```

**验证：** 访问 `http://master_ip:9090` 以确认 Prometheus 服务已成功启动。

### 步骤 4 和 5：启动 verl 训练

使用以下参数配置来启动 verl 训练：

**必需配置：**

* `actor_rollout_ref.rollout.mode="async"`
* `actor_rollout_ref.rollout.disable_log_stats=False`
* `actor_rollout_ref.rollout.prometheus.enable=True`

如果使用默认端口，此参数可以省略。
* `actor_rollout_ref.rollout.prometheus.port=9090`

如果使用默认路径，此参数可以省略。
* `actor_rollout_ref.rollout.prometheus.file="/tmp/ray/session_latest/metrics/prometheus/prometheus.yml"`

served_model_name 默认使用 `model_path.split("/")[-1]` 进行数据统计。用户也可以自定义其他别名：

* `actor_rollout_ref.rollout.prometheus.served_model_name="Qwen3-235B"`

**Shell 脚本示例：**

```bash
WORKING_DIR=${WORKING_DIR:-"${PWD}"}
RUNTIME_ENV=${RUNTIME_ENV:-"${WORKING_DIR}/verl/trainer/runtime_env.yaml"}

rollout_mode="async"
rollout_name="vllm"  # 选项：sglang 或 vllm
if [ "$rollout_mode" = "async" ]; then
    export VLLM_USE_V1=1
    return_raw_chat="True"
fi

# 同步训练
ray job submit --no-wait --runtime-env="${RUNTIME_ENV}" \
    --working-dir "${WORKING_DIR}" \
    -- python3 -m verl.trainer.main_ppo \
    data.return_raw_chat=${return_raw_chat} \
    actor_rollout_ref.rollout.name=${rollout_name} \
    actor_rollout_ref.rollout.mode=${rollout_mode} \
    actor_rollout_ref.rollout.disable_log_stats=False \
    actor_rollout_ref.rollout.prometheus.enable=True
    ...
    
# 异步训练
ray job submit --no-wait --runtime-env="${RUNTIME_ENV}" \
    --working-dir "${WORKING_DIR}" \
    -- python3 recipe.fully_async_policy.fully_async_main \
    data.return_raw_chat=${return_raw_chat} \
    actor_rollout_ref.rollout.name=${rollout_name} \
    actor_rollout_ref.rollout.mode=${rollout_mode} \
    actor_rollout_ref.rollout.disable_log_stats=False \
    actor_rollout_ref.rollout.prometheus.enable=True
    ...
```

### 步骤 6：在 Prometheus 中查看指标

任务执行后，验证 Prometheus 是否正确收集指标。

**验证：** 访问 Prometheus 界面 `http://master_ip:9090` 并搜索 `vllm:` 或 `sglang:` 以确认指标正在正确报告。

**故障排除：**

如果没有指标出现：
1. 检查 `AgentLoopManager` 的日志以查找服务器端口
2. 访问 `http://master_ip:server_port/metrics` 以验证服务器指标是否可用
3. 确认已设置 `actor_rollout_ref.rollout.disable_log_stats=False`

### 步骤 7：在 Grafana 中查看指标

任务执行后，登录 Grafana 以查看和自定义监控仪表盘。

**登录：** 访问 `http://master_ip:3000`（默认凭据：`admin/admin`）

**导入仪表盘：**

1. 选择 “仪表盘” → “新建” → “导入” → “上传仪表盘 JSON 文件”
2. 上传预构建的仪表盘 JSON 文件

**可用仪表盘：**
* [vLLM Grafana 仪表盘样式 1](https://github.com/ArronHZG/verl-community/blob/main/docs/grafana/vllm_grafana.json)
* [vLLM Grafana 仪表盘样式 2](https://github.com/vllm-project/vllm/blob/main/examples/online_serving/dashboards/grafana/performance_statistics.json)
* [vLLM Grafana 仪表盘样式 2](https://github.com/vllm-project/vllm/blob/main/examples/online_serving/dashboards/grafana/query_statistics.json)
* [SGLang Grafana 仪表盘](https://github.com/sgl-project/sglang/blob/main/examples/monitoring/grafana/dashboards/json/sglang-dashboard.json)

## 其他资源

- [Ray 监控文档](https://docs.ray.io/en/latest/cluster/configure-manage-dashboard.html)
- [Prometheus 文档](https://prometheus.io/docs/)
- [Grafana 文档](https://grafana.com/docs/)
- [vLLM GitHub 仓库](https://github.com/vllm-project/vllm)
- [SGLang GitHub 仓库](https://github.com/sgl-project/sglang)