本文中对应的框架及版本:

  • vllm-0.25.1
  • sglang-0.5.2

欢迎指出内容谬误,作者将积极修正。

1. 暴露接口

框架 Prometheus OpenTelemetry
vLLM /metrics,FastAPI/Starlette Mount("/metrics", make_asgi_app(...))。指标名前缀主要是 vllm:。 支持 OTLP traces:--otlp-traces-endpoint,可配 --collect-detailed-traces=model/worker/all。当前源码是 trace,不是 OTel metrics。
SGLang --enable-metrics 后挂载 /metrics,使用 prometheus multiprocess registry。指标名前缀主要是 sglang:。 当前 sglang-0.5.2 源码未发现 OpenTelemetry/OTLP exporter。

Prometheus Python client 会把 : 转换成 _ 暴露,例如 vllm:num_requests_running 在 PromQL 中通常写作 vllm:num_requests_running 或按采集端保留格式;如果你的 Prometheus 不接受冒号,可查看实际 /metrics 输出确认是否变成 vllm_num_requests_running。

2. vLLM 指标

默认标签:model_name、engine。部分指标还有 reason、source、finished_reason、position、LoRA 标签。

2.1 服务与调度

指标 类型 含义
vllm:num_requests_running Gauge 正在执行 batch 中的请求数。
vllm:num_requests_waiting Gauge 等待处理的请求数,包含 capacity waiting 与 deferred。
vllm:num_requests_waiting_by_reason{reason="capacity"} Gauge 因调度容量不足等待的请求数。
vllm:num_requests_waiting_by_reason{reason="deferred"} Gauge 因 LoRA/KV transfer/blocked 等瞬时限制推迟的请求数。
vllm:engine_sleep_state{sleep_state="awake"} Gauge 引擎是否 awake,1=awake。
vllm:engine_sleep_state{sleep_state="weights_offloaded"} Gauge sleep level 1,权重 offload。
vllm:engine_sleep_state{sleep_state="discard_all"} Gauge sleep level 2,丢弃更多状态。
vllm:kv_cache_usage_perc Gauge KV cache 使用率,1 表示 100%。
vllm:num_preemptions Counter engine 累计 preemption 次数。
vllm:request_success{finished_reason=...} Counter 成功结束请求数,按结束原因分类。
vllm:corrupted_requests Counter logits 出现 NaN 的请求数;仅 VLLM_COMPUTE_NANS_IN_LOGITS 启用时存在。
vllm:cache_config_info Gauge/Info cache 配置信息,值恒为 1,标签携带配置。
vllm:lora_requests_info Gauge LoRA 请求状态;标签含 max_lora、waiting/running adapter 列表。

2.2 Token 与吞吐

指标 类型 含义
vllm:prompt_tokens Counter 处理过的 prefill/prompt token 数。
vllm:prompt_tokens_by_source{source=...} Counter 按来源拆分的 prompt token 数。source 由 PromptTokenStats.ALL_SOURCES 决定。
vllm:prompt_tokens_cached Counter 命中的 cached prompt token 数,local + external。
vllm:generation_tokens Counter 生成 token 数。
vllm:iteration_tokens_total Histogram 每次 engine step 处理 token 数分布。
vllm:request_prompt_tokens Histogram 单请求 prompt token 数分布。
vllm:request_generation_tokens Histogram 单请求 generation token 数分布。
vllm:request_max_num_generation_tokens Histogram 请求的最大 generation token 数分布。
vllm:request_params_n Histogram 请求参数 n 的分布。
vllm:request_params_max_tokens Histogram 请求参数 max_tokens 的分布。
vllm:request_prefill_kv_computed_tokens Histogram prefill 阶段实际新计算的 KV token 数,不含 cached token。

2.3 延迟

指标 类型 含义
vllm:time_to_first_token_seconds Histogram TTFT,从请求进入到首 token 输出的时间。
vllm:inter_token_latency_seconds Histogram ITL,相邻输出 token 间隔。
vllm:request_time_per_output_token_seconds Histogram 单请求平均每输出 token 耗时。
vllm:e2e_request_latency_seconds Histogram 单请求端到端延迟。
vllm:request_queue_time_seconds Histogram 请求处于 waiting 阶段的时间。
vllm:request_inference_time_seconds Histogram 请求处于 running/inference 阶段的时间。
vllm:request_prefill_time_seconds Histogram prefill 阶段时间。
vllm:request_decode_time_seconds Histogram decode 阶段时间。

2.4 Prefix/MM cache

指标 类型 含义
vllm:prefix_cache_queries Counter prefix cache 查询 token 数。
vllm:prefix_cache_hits Counter prefix cache 命中 token 数。
vllm:external_prefix_cache_queries Counter KV connector 跨实例 external prefix cache 查询 token 数。
vllm:external_prefix_cache_hits Counter KV connector external prefix cache 命中 token 数。
vllm:mm_cache_queries Counter 多模态 cache 查询 item 数。
vllm:mm_cache_hits Counter 多模态 cache 命中 item 数。

2.5 KV cache 驻留指标

需要启用 --kv-cache-metrics。

指标 类型 含义
vllm:kv_block_lifetime_seconds Histogram KV block 从分配到 eviction 的生命周期。
vllm:kv_block_idle_before_evict_seconds Histogram KV block eviction 前 idle 时间。
vllm:kv_block_reuse_gap_seconds Histogram KV block 连续访问之间的间隔。

2.6 Speculative decoding / diffusion

启用 speculative decoding 时:

指标 类型 含义
vllm:spec_decode_num_drafts Counter draft 次数。
vllm:spec_decode_num_draft_tokens Counter draft token 数。
vllm:spec_decode_num_accepted_tokens Counter 被接受的 draft token 数。
vllm:spec_decode_num_accepted_tokens_per_pos{position=...} Counter 各 draft 位置被接受 token 数。

diffusion 模型路径使用:

指标 类型 含义
vllm:diffusion_num_denoising_steps Counter denoising step 数。
vllm:diffusion_num_canvas_positions Counter 被评估的 canvas position 数。
vllm:diffusion_num_committed_tokens Counter 最终 committed token 数。

2.7 MFU/带宽估算

需要启用 --enable-mfu-metrics。

指标 类型 含义
vllm:estimated_flops_per_gpu_total Counter 每 GPU 估算 FLOPs 累计值。
vllm:estimated_read_bytes_per_gpu_total Counter 每 GPU 估算内存读字节数。
vllm:estimated_write_bytes_per_gpu_total Counter 每 GPU 估算内存写字节数。

2.8 KV connector 相关

按 connector 启用时出现。

指标 类型 含义
vllm:nixl_xfer_time_seconds Histogram NIXL KV transfer 时间。
vllm:nixl_post_time_seconds Histogram NIXL post 操作时间。
vllm:nixl_bytes_transferred Histogram/Counter 语义 NIXL 传输字节数。
vllm:nixl_num_descriptors Histogram NIXL descriptor 数分布。
vllm:nixl_num_failed_transfers Counter NIXL transfer 失败数。
vllm:nixl_num_failed_notifications Counter NIXL notification 失败数。
vllm:nixl_num_kv_expired_reqs Counter NIXL 中 KV 过期请求数。
vllm:hf3fs_save_duration_seconds Histogram HF3FS save 耗时。
vllm:hf3fs_load_duration_seconds Histogram HF3FS load 耗时。
vllm:hf3fs_num_failed_save Counter HF3FS save 失败数。
vllm:hf3fs_num_failed_load Counter HF3FS load 失败数。
vllm:mooncake_store_operation_time_seconds{operation=...} Histogram Mooncake store 操作耗时。
vllm:mooncake_store_operation_total{operation=...} Counter Mooncake store 操作次数。
vllm:mooncake_store_operation_keys_total{operation=...} Counter Mooncake store 操作 key 数。
vllm:mooncake_store_operation_bytes_total{operation=...} Counter Mooncake store 操作字节数。
vllm:mooncake_store_operation_failed_keys_total{operation=...} Counter Mooncake store 失败 key 数。

2.9 其他

指标 类型 含义
vllm:websocket_connections_active Gauge realtime STT WebSocket 活跃连接数。
vllm:websocket_connections_total Counter realtime STT WebSocket 累计连接数。
vllm:websocket_connection_duration_seconds Histogram realtime STT WebSocket 连接持续时间。

3. SGLang 指标

默认标签:model_name、tp_rank。Tokenizer collector 使用 model_name;函数/startup 指标使用自己的标签。

3.1 调度与资源

指标 类型 含义
sglang:num_running_reqs Gauge 正在运行请求数。
sglang:num_used_tokens Gauge 已使用 token 数,通常对应 KV/token pool 占用。
sglang:token_usage Gauge token 使用率。
sglang:swa_token_usage Gauge SWA layer 的 token 使用率。
sglang:gen_throughput Gauge 生成吞吐,token/s。
sglang:num_queue_reqs Gauge 等待队列请求数。
sglang:num_grammar_queue_reqs Gauge grammar waiting queue 请求数。
sglang:num_running_reqs_offline_batch Gauge 低优先级 offline batch 正在运行请求数。
sglang:avg_request_queue_latency Gauge 最近一批请求平均排队延迟,秒。
sglang:cache_hit_rate Gauge prefix cache 命中率。
sglang:utilization Gauge SGLang 内部计算的 utilization。
sglang:max_running_requests_under_SLO Gauge SLO 下可承载的最大 running request 数。
sglang:total_retracted_reqs Gauge 因 KV cache 满导致的累计 retract 请求数。
sglang:num_retracted_reqs Gauge 当前/本轮 retract 请求数。
sglang:num_paused_reqs Gauge async weight sync 暂停的请求数。

3.2 请求、token 与延迟

指标 类型 含义
sglang:prompt_tokens_total Counter 已处理 prompt/prefill token 数。
sglang:generation_tokens_total Counter 已生成 token 数。
sglang:cached_tokens_total Counter cached prompt token 数。
sglang:num_requests_total Counter 已处理请求数。
sglang:num_so_requests_total Counter structured output 请求数。
sglang:num_aborted_requests Counter abort 请求数。源码变量名是 _total,实际指标名无 _total。
sglang:prompt_tokens_histogram Histogram prompt token 长度分布;需启用 token histogram 采集。
sglang:generation_tokens_histogram Histogram generation token 长度分布;需启用 token histogram 采集。
sglang:time_to_first_token_seconds Histogram TTFT。
sglang:time_to_first_token_seconds_offline_batch Histogram offline batch 请求 TTFT。
sglang:inter_token_latency_seconds Histogram ITL。实现按 interval / num_new_tokens 放入 bucket,sum 增加总 interval。
sglang:e2e_request_latency_seconds Histogram 请求端到端延迟。
sglang:queue_time_s Histogram 请求排队时间。

3.3 Speculative decoding

指标 类型 含义
sglang:spec_accept_length Gauge speculative decoding 平均 acceptance length。

3.4 PD disaggregation / KV transfer

指标 类型 含义
sglang:num_prefill_prealloc_queue_reqs Gauge prefill prealloc queue 请求数。
sglang:num_prefill_inflight_queue_reqs Gauge prefill inflight queue 请求数。
sglang:num_decode_prealloc_queue_reqs Gauge decode prealloc queue 请求数。
sglang:num_decode_transfer_queue_reqs Gauge decode transfer queue 请求数。
sglang:num_bootstrap_failed_reqs_total Counter bootstrap 失败请求数。
sglang:num_transfer_failed_reqs_total Counter transfer 失败请求数。
sglang:kv_transfer_speed_gb_s Gauge KV cache transfer 速度,GB/s。
sglang:kv_transfer_latency_ms Gauge KV cache transfer 延迟,ms。

3.5 Grammar / structured output

指标 类型 含义
sglang:grammar_compilation_time_seconds Histogram grammar 编译耗时。
sglang:num_grammar_cache_hit_total Counter grammar cache 命中次数。
sglang:num_grammar_aborted_total Counter grammar abort 请求数。
sglang:num_grammar_total Counter grammar 请求总数。
sglang:grammar_schema_count Histogram grammar schema 数量分布。
sglang:grammar_ebnf_size Histogram grammar EBNF 大小分布。
sglang:grammar_tree_traversal_time_avg Histogram grammar tree traversal 平均耗时。
sglang:grammar_tree_traversal_time_max Histogram grammar tree traversal 最大耗时。

3.6 HiCache/storage

指标 类型 含义
sglang:prefetched_tokens_total Counter prefetch 的 prompt token 数。
sglang:backuped_tokens_total Counter backup token 数。
sglang:prefetch_pgs Histogram batch prefetch page 数分布。
sglang:backup_pgs Histogram batch backup page 数分布。
sglang:prefetch_bandwidth Histogram prefetch 带宽,GB/s。
sglang:backup_bandwidth Histogram backup 带宽,GB/s。

3.7 启动与函数耗时

指标 类型 含义
sglang:engine_startup_time Gauge engine 启动耗时。
sglang:engine_load_weights_time Gauge 权重加载耗时。
sglang:startup_latency_breakdown_seconds_max{context=...} Gauge 启动阶段分 context 最大耗时。
sglang:func_latency_seconds{name=...} Histogram 被 time_func_latency 装饰的函数耗时。

4. 组合指标 / PromQL

下面用 $__rate_interval 表示 Grafana rate interval,可替换成 1m、5m。

4.1 吞吐

目标 vLLM SGLang
输出 token/s sum(rate(vllm:generation_tokens[$__rate_interval])) by (model_name) sum(rate(sglang:generation_tokens_total[$__rate_interval])) by (model_name);也可直接看 sglang:gen_throughput
输入/prefill token/s sum(rate(vllm:prompt_tokens[$__rate_interval])) by (model_name) sum(rate(sglang:prompt_tokens_total[$__rate_interval])) by (model_name)
总 token/s sum(rate(vllm:prompt_tokens[$__rate_interval]) + rate(vllm:generation_tokens[$__rate_interval])) by (model_name) sum(rate(sglang:prompt_tokens_total[$__rate_interval]) + rate(sglang:generation_tokens_total[$__rate_interval])) by (model_name)
请求 QPS sum(rate(vllm:request_success[$__rate_interval])) by (model_name) sum(rate(sglang:num_requests_total[$__rate_interval])) by (model_name)

4.2 延迟分位

目标 vLLM SGLang
TTFT p50/p95/p99 histogram_quantile(0.95, sum(rate(vllm:time_to_first_token_seconds_bucket[$__rate_interval])) by (le, model_name)) histogram_quantile(0.95, sum(rate(sglang:time_to_first_token_seconds_bucket[$__rate_interval])) by (le, model_name))
ITL p95 histogram_quantile(0.95, sum(rate(vllm:inter_token_latency_seconds_bucket[$__rate_interval])) by (le, model_name)) histogram_quantile(0.95, sum(rate(sglang:inter_token_latency_seconds_bucket[$__rate_interval])) by (le, model_name))
E2E p95 histogram_quantile(0.95, sum(rate(vllm:e2e_request_latency_seconds_bucket[$__rate_interval])) by (le, model_name)) histogram_quantile(0.95, sum(rate(sglang:e2e_request_latency_seconds_bucket[$__rate_interval])) by (le, model_name))
Queue p95 histogram_quantile(0.95, sum(rate(vllm:request_queue_time_seconds_bucket[$__rate_interval])) by (le, model_name)) histogram_quantile(0.95, sum(rate(sglang:queue_time_s_bucket[$__rate_interval])) by (le, model_name))
Decode p95 histogram_quantile(0.95, sum(rate(vllm:request_decode_time_seconds_bucket[$__rate_interval])) by (le, model_name)) 无直接 decode request latency;看 ITL 与 PD transfer queue。
Prefill p95 histogram_quantile(0.95, sum(rate(vllm:request_prefill_time_seconds_bucket[$__rate_interval])) by (le, model_name)) 无直接 prefill request latency;看 TTFT、queue、PD prefill queue。

4.3 Cache 效率

目标 vLLM SGLang
prefix cache 命中率 sum(rate(vllm:prefix_cache_hits[$__rate_interval])) / sum(rate(vllm:prefix_cache_queries[$__rate_interval])) 直接看 sglang:cache_hit_rate,或 sum(rate(sglang:cached_tokens_total[$__rate_interval])) / sum(rate(sglang:prompt_tokens_total[$__rate_interval]))
external prefix cache 命中率 sum(rate(vllm:external_prefix_cache_hits[$__rate_interval])) / sum(rate(vllm:external_prefix_cache_queries[$__rate_interval])) 无同名指标;PD/HiCache 场景看 storage 与 transfer 指标。
cached prompt token 占比 sum(rate(vllm:prompt_tokens_cached[$__rate_interval])) / sum(rate(vllm:prompt_tokens[$__rate_interval])) sum(rate(sglang:cached_tokens_total[$__rate_interval])) / sum(rate(sglang:prompt_tokens_total[$__rate_interval]))
多模态 cache 命中率 sum(rate(vllm:mm_cache_hits[$__rate_interval])) / sum(rate(vllm:mm_cache_queries[$__rate_interval])) 无对应通用指标。

4.4 饱和度 / 排队 / 容量

目标 vLLM SGLang
运行请求数 sum(vllm:num_requests_running) by (model_name) sum(sglang:num_running_reqs) by (model_name)
等待请求数 sum(vllm:num_requests_waiting) by (model_name) sum(sglang:num_queue_reqs) by (model_name)
等待原因 sum(vllm:num_requests_waiting_by_reason) by (model_name, reason) grammar queue 单独看 sum(sglang:num_grammar_queue_reqs) by (model_name)
KV/token 使用率 avg(vllm:kv_cache_usage_perc) by (model_name) avg(sglang:token_usage) by (model_name);SWA 看 avg(sglang:swa_token_usage) by (model_name)
preemption/retract 速率 sum(rate(vllm:num_preemptions[$__rate_interval])) by (model_name) sum(rate(sglang:total_retracted_reqs[$__rate_interval])) by (model_name) 或看 sglang:num_retracted_reqs
abort/error 速率 无统一失败请求 counter;看 server HTTP 指标或 vllm:corrupted_requests sum(rate(sglang:num_aborted_requests[$__rate_interval])) by (model_name)

4.5 Spec decode

目标 vLLM SGLang
draft acceptance rate sum(rate(vllm:spec_decode_num_accepted_tokens[$__rate_interval])) / sum(rate(vllm:spec_decode_num_draft_tokens[$__rate_interval])) 直接看 sglang:spec_accept_length,没有 draft/accepted token counter。
mean acceptance length 1 + sum(rate(vllm:spec_decode_num_accepted_tokens[$__rate_interval])) / sum(rate(vllm:spec_decode_num_drafts[$__rate_interval])) avg(sglang:spec_accept_length) by (model_name)
per-position acceptance sum(rate(vllm:spec_decode_num_accepted_tokens_per_pos[$__rate_interval])) by (position) / sum(rate(vllm:spec_decode_num_drafts[$__rate_interval])) 无。

4.6 MFU / 带宽 / GPU 利用近似

目标 vLLM SGLang
估算 TFLOPS/GPU sum(rate(vllm:estimated_flops_per_gpu_total[$__rate_interval])) by (model_name, engine) / 1e12 无直接 MFU counter。
估算内存带宽 GB/s/GPU (sum(rate(vllm:estimated_read_bytes_per_gpu_total[$__rate_interval])) by (model_name, engine) + sum(rate(vllm:estimated_write_bytes_per_gpu_total[$__rate_interval])) by (model_name, engine)) / 1e9 无直接;HiCache 看 sglang:prefetch_bandwidth、sglang:backup_bandwidth。
MFU 近似 rate(vllm:estimated_flops_per_gpu_total[$__rate_interval]) / <GPU_peak_flops> 需要外部 GPU 指标或手工填峰值。

4.7 PD / KV transfer / Storage

目标 vLLM SGLang
NIXL 传输 p95 histogram_quantile(0.95, sum(rate(vllm:nixl_xfer_time_seconds_bucket[$__rate_interval])) by (le)) avg(sglang:kv_transfer_latency_ms) by (model_name)
NIXL 失败速率 sum(rate(vllm:nixl_num_failed_transfers[$__rate_interval])) sum(rate(sglang:num_transfer_failed_reqs_total[$__rate_interval]))
transfer 带宽 NIXL 字节吞吐:sum(rate(vllm:nixl_bytes_transferred_sum[$__rate_interval])),以实际暴露类型校准 avg(sglang:kv_transfer_speed_gb_s) by (model_name)
prefetch/backup token/s 无通用指标 rate(sglang:prefetched_tokens_total[$__rate_interval])、rate(sglang:backuped_tokens_total[$__rate_interval])

4.8 Structured output / grammar

目标 SGLang PromQL
structured output QPS sum(rate(sglang:num_so_requests_total[$__rate_interval])) by (model_name)
structured output 占比 sum(rate(sglang:num_so_requests_total[$__rate_interval])) / sum(rate(sglang:num_requests_total[$__rate_interval]))
grammar cache 命中率 sum(rate(sglang:num_grammar_cache_hit_total[$__rate_interval])) / sum(rate(sglang:num_grammar_total[$__rate_interval]))
grammar abort 率 sum(rate(sglang:num_grammar_aborted_total[$__rate_interval])) / sum(rate(sglang:num_grammar_total[$__rate_interval]))
grammar 编译 p95 histogram_quantile(0.95, sum(rate(sglang:grammar_compilation_time_seconds_bucket[$__rate_interval])) by (le, model_name))

5. 建议核心看板

看板项 vLLM SGLang
请求量 QPS: request_success rate QPS: num_requests_total rate
吞吐 prompt/generation token rate prompt/generation token rate + gen_throughput
延迟 TTFT p95/p99、ITL p95/p99、E2E p95/p99、queue p95 TTFT p95/p99、ITL p95/p99、E2E p95/p99、queue p95
饱和 running、waiting、KV cache usage、preemption rate running、queue、token_usage、retract/abort rate
cache prefix/external/mm hit rate、cached token 占比 cache_hit_rate、cached token 占比、storage metrics
高级性能 MFU TFLOPS、估算内存带宽、spec decode acceptance spec_accept_length、PD transfer latency/speed