vLLM Grafana 监控仪表盘实战从 Prometheus 指标到性能与查询统计可视化【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllmvLLM 仓库在examples/observability/dashboards/grafana/目录下提供了两套现成的 Grafana 仪表盘 JSON 配置分别面向性能统计延迟、吞吐与查询统计请求量、Token 分布两类监控场景。本文以该目录下的 README 为主体完整讲解前置条件、两种部署方式手动导入与 Grafana Operator、每个面板的 PromQL 查询含义并溯源到 vLLM 中这些指标的注册实现帮助你在生产环境中快速搭起一套可复制、可验证的 vLLM 可观测性方案。目录结构与前提条件Grafana 仪表盘所在目录结构如下examples/observability/dashboards/ ├── README.md # 仪表盘总览Grafana 与 Perses 双平台 ├── grafana/ │ ├── README.md # Grafana 平台专属文档 │ ├── performance_statistics.json │ └── query_statistics.json └── perses/ # Perses 平台的等价 YAML 版本上层 总览文档 说明了两套平台Grafana 与 Perses提供等价的监控能力Performance Statistics 跟踪延迟与吞吐Query Statistics 监控请求量、查询性能与 KPI。Grafana 版采用原生 JSON 格式兼容任意 Grafana 实例云端、自托管、Docker可直接通过 UI 或 API 导入也可按需包裹进 Kubernetes Operator无供应商锁定。按 Grafana README 列出的 Requirements使用这些仪表盘需要满足Grafana 8.0仪表盘 JSON 的schemaVersion为 40实测导入时建议 10.x 以获得完整面板类型支持Grafana 中已配置 Prometheus 数据源两个仪表盘都引用了名为DS_PROMETHEUS的 Prometheus 类型数据源变量导入后 Grafana 会弹出数据源选择框务必选中你的 Prometheus 实例vLLM 部署已启用 Prometheus 指标vLLM 的 OpenAI 兼容 API Server 默认在/metrics端点暴露 Prometheus 格式指标如vllm:e2e_request_latency_seconds_bucket、vllm:time_to_first_token_seconds等这些正是仪表盘所有面板的数据来源。指标定义与暴露方式可参考仓库内的 Production Metrics 文档Prometheus 抓取侧通常配置为针对 vLLM 服务实例的scrape_configs抓取:8000/metrics端点即可对应vllm serve model的默认端口。两套仪表盘性能统计与查询统计performance_statistics.json端到端延迟 / TTFT / ITL / TPSperformance_statistics.json约 35 KB标题 Performance Statistics默认时间范围now-12h用于跟踪 vLLM 服务的核心性能指标按四大区块组织面板区块row 面板面板数据来源指标E2E latency over timeE2E Latency over Timetimeseries、Avg / P50 / P90 / P99statvllm:e2e_request_latency_secondsHistogramTTFT over timeTTFT Over Timetimeseries、Avg / P50 / P90 / P99statvllm:time_to_first_token_secondsHistogramITL over timeTime Per Output Token Over Timetimeseries含 Avg/P50/P90/P99 四条线、四个分位数 statvllm:inter_token_latency_secondsHistogramTPS (Tokens Per Second)TPS Over Timetimeseries三条曲线vllm:generation_tokens_total、vllm:prompt_tokens_total、vllm:iteration_tokens_total_count核心面板的代表性 PromQL 如下均摘自 JSON 的targets[].expr字段平均 E2E 延迟曲线sum/count 相除得到滑动平均值rate(vllm:e2e_request_latency_seconds_sum[$__interval]) / rate(vllm:e2e_request_latency_seconds_count[$__interval])P99 E2E 延迟对 Histogram 桶做分位数插值histogram_quantile(0.99, sum by(le) (rate(vllm:e2e_request_latency_seconds_bucket[$__range])))TTFT 与 ITL 的分位数面板采用完全相同的histogram_quantile(..., sum by(le) (rate(..._bucket[...])))模式仅把指标名换为vllm:time_to_first_token_seconds与vllm:inter_token_latency_secondsITL 的 timeseries 面板同时叠加 Avgsum/count与 P50/P90/P99 四条曲线便于观察解码阶段逐 token 延迟的分布漂移。TPS 面板用三条速率曲线刻画吞吐rate(vllm:generation_tokens_total[$__interval]) # 生成 token 速率 rate(vllm:prompt_tokens_total[$__interval]) # 提示 token 速率 rate(vllm:iteration_tokens_total_count[$__interval]) # 引擎每步迭代 token 计数速率其中 TPS 面板的纵轴单位为 tokens/sunit: short量级下按 rate 计是判断 prefill/decode 吞吐趋势的直接依据。值得注意的细节这些延迟 Histogram 面板的字段配置里设置了红色阈值例如 E2E Latency 面板thresholds.steps中value: 80处由绿转红单位s意味着当 P99 端到端延迟超过约 80 秒时统计块会变红提示属于对超长尾请求的告警式可视化。在 vLLM 源码中这三个核心 Histogram 均在 vllm/v1/metrics/loggers.py 中以 PrometheusHistogram类型注册vllm:time_to_first_token_secondsL797 附近、vllm:inter_token_latency_secondsL830 附近、vllm:e2e_request_latency_secondsL913 附近并带有model_name等标签。也就是说仪表盘与 vLLM V1 引擎的指标注册是严格对齐的——指标名一旦在引擎侧变更导入的仪表盘会查询不到数据升级 vLLM 后建议对照源码核对该文件。query_statistics.json请求量、Token 规模分布与按模型过滤query_statistics.json约 24 KB标题 Query Statistics_New4默认时间范围now-12h关注请求侧 KPI同样分四大区块区块row 面板面板数据来源指标Request Over TimeSuccessful Requests Over Timetimeseries按model_name分线、Requests Avg Rate、p50 / p90 / p99 Latencystatvllm:request_success_total、vllm:e2e_request_latency_seconds_bucketSize DistributionInput Token Size Distributionhistogram、Avg / p50 / p90 / p99statvllm:request_prompt_tokens_bucket、vllm:prompt_tokens_totalInput Token Over TimeInput Tokens Over Timetimeseries、Input Tokens/Sec Avgvllm:prompt_tokens_totalOutput Token Over TimeOutput Tokens Over Timetimeseries、Output Tokens/Sec Avgvllm:generation_tokens_total与性能仪表盘最关键的区别是query 仪表盘的所有查询都带{model_name~$Deployment_id}标签过滤从而支持在多模型混部场景下按部署即模型名维度切分视图。代表性查询按模型分线的成功请求速率sum by (model_name) ( rate(vllm:request_success_total{model_name~$Deployment_id}[$__rate_interval]) )按模型过滤的 p99 延迟histogram_quantile(0.99, sum by(le, model_name) (rate(vllm:e2e_request_latency_seconds_bucket{model_name~$Deployment_id}[$__rate_interval])))输入 Token 平均大小提示 token 速率 / 请求成功率得到每请求平均输入长度sum(rate(vllm:prompt_tokens_total{model_name~$Deployment_id}[$__rate_interval])) / sum(rate(vllm:request_success_total{model_name~$Deployment_id}[$__rate_interval]))模板变量导入后需要检查的配置两个仪表盘的templating.variables中定义了 Grafana 变量这是导入后必须确认的地方performance_statistics.json定义了 3 个变量DS_PROMETHEUSdatasource 类型query 为prometheus数据源选择导入时由 Grafana 自动弹出确认框Deployment_idquery 类型多选 含 All 选项取值为label_values(vllm:generation_tokens_total, model_name)即自动从 Prometheus 中发现所有上报过生成 token 的model_name标签值agg_methodcustom 类型仅含一个占位选项 avg : Average / 0.50 : P50 / 0.90 : P90 / 0.99 : P99 / 0.999 : Max (Approx)从源码结构看这是一个预留的聚合方法变量当前各面板的分位数是硬编码在查询里的实际切换分位数需要直接编辑面板查询。query_statistics.json定义了 5 个变量DS_PROMETHEUS同上Deployment_id取值为label_values(vllm:request_success_total, model_name)多选含 All这是请求类面板过滤下拉框的实际数据源rush_hours/rush_hours_type/query0均为隐藏变量hide: 2分别对应 All hours / Rush hours、All / Static / Dynamic 等选项当前查询表达式中并未引用它们从源码结构看属于模板遗留的隐藏变量可按需忽略或清理。一个实操提醒Deployment_id变量的发现依赖 Prometheus 中已存在对应指标序列。如果 vLLM 刚启动、尚无成功请求label_values(vllm:request_success_total, model_name)可能返回空此时 query 仪表盘的模型下拉框会是空选项等流量产生后会自动出现。部署方式一手动导入官方推荐Grafana README 将 Manual Import 标注为 Recommended步骤为打开 Grafana 实例点击侧边栏图标选择 Import将仪表盘 JSON 文件的内容粘贴进去或直接上传 JSON 文件。由于仓库提供的是完整 JSON 文件通常直接上传 performance_statistics.json 或 query_statistics.json 即可。导入后在弹窗中把Prometheus数据源指向你的实例并保存。如果希望在 CI/脚本化场景中批量导入上层 总览文档 给出了 Grafana HTTP API 的用法cd examples/observability/dashboards curl -X POST http://grafana/api/dashboards/db \ -H Content-Type: application/json \ -d grafana/performance_statistics.json该方式要求 Grafana 允许匿名或带凭据访问生产环境请在请求头补充Authorization: Bearer service_account_token一类鉴权并可将-d包裹进{dashboard: ..., overwrite: true}结构以覆盖式更新。部署方式二Grafana OperatorKubernetes若在 Kubernetes 中使用 Grafana Operator可以按 README 提供的模式把 JSON 配置包裹进GrafanaDashboard自定义资源# Note: Adjust the instanceSelector to match your Grafana instances labels # You can check with: kubectl get grafana -o yaml apiVersion: grafana.integreatly.org/v1beta1 kind: GrafanaDashboard metadata: name: vllm-performance-dashboard spec: instanceSelector: matchLabels: dashboards: grafana # Adjust to match your Grafana instance labels folder: vLLM Monitoring json: | # Replace this comment with the complete JSON content from # performance_statistics.json - The JSON should start with { and end with }要点instanceSelector.matchLabels必须与集群中Grafana自定义资源的标签匹配可用kubectl get grafana -o yaml查看json字段需要填入performance_statistics.json的完整 JSON 内容以{开始、}结束并保证 YAML 块缩进正确应用方式kubectl apply -f your-dashboard.yaml -n namespace对query_statistics.json可照同样模式再建一个GrafanaDashboard资源。注意 README 中的apiVersion: grafana.integreatly.org/v1beta1对应 Grafana OperatorIntegreatly的 API 组不同 Operator 发行版如 grafana-agent / grafana k8s sidecar 等的 CRD 可能不同使用前应先确认集群中安装的 Operator 及其 CRD 版本。从指标定义到面板与 vLLM 源码的对应关系理解这套仪表盘的一个高效路径是把面板查询反向映射到 vLLM 的指标注册代码指标注册vllm:v1/metrics/loggers.py即 vllm/v1/metrics/loggers.py负责在 V1 引擎中创建并更新各请求级 Histogram 与 Counter。仪表盘用到的vllm:time_to_first_token_seconds、vllm:inter_token_latency_seconds、vllm:e2e_request_latency_seconds均在该文件注册分别位于约 L797、L830、L913Counter 类指标vllm:prompt_tokens_total、vllm:generation_tokens_total、vllm:request_success_total也随引擎日志逻辑更新标签体系引擎指标带有model_name标签这正是 query 仪表盘Deployment_id变量与sum by (model_name)分线查询能工作的原因端点指标通过 API Server 的/metrics端点以 Prometheus 文本格式暴露详见 Production Metrics 文档其中还列出了/metrics的 curl 输出样例、通用指标表、Speculative Decoding 指标、NIXL KV Connector 指标以及--enable-mfu-metrics的 MFU 指标兼容窗口文档指出指标有弃用策略——版本X.Y弃用的指标在X.Y1隐藏可用--show-hidden-metrics-for-versionX.Y恢复在X.Y2移除。因此跨大版本升级 vLLM 后若仪表盘出现空面板应优先核对指标名是否仍存在于loggers.py。落地检查清单结合上述内容一条最小可运行的接入路径是用vllm serve model或对应部署方式启动 vLLM确认curl http://host:8000/metrics能看到vllm:e2e_request_latency_seconds_bucket等序列在 Prometheus 中配置抓取该实例确认vllm:request_success_total{model_name...}有数据在 Grafana 中配置 Prometheus 数据源然后按 Manual Import 流程依次导入 performance_statistics.json 与 query_statistics.json数据源选择你的 Prometheus发送若干测试请求后检查性能仪表盘的 E2E/TTFT/ITL/TPS 曲线应出现查询仪表盘的 Successful Requests Over Time 应按model_name分线显示如部署在 K8s可改用 Grafana Operator 的GrafanaDashboard资源方式实现 Dashboard-as-CodeJSON 内容与手动导入完全一致。若还需要不依赖 Grafana 的方案同一目录树下的 Perses 仪表盘 提供了等价的 YAML 版本performance_statistics.yaml/query_statistics.yaml可通过 Perses CLIpercli apply导入两者面板能力一致可按团队栈任选。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考