指标端点与日志噪声：采集哪些、怎么读

2024-12-05

在 **** 的 ****（8 卡，单卡 64GB HBM，卡间互联 392 GB/s）上用 **** 的基础软件栈配合 vLLM 0.6.x 起 OpenAI 兼容服务。运维手上只有两样东西：一条 stdout 日志流和一个 Prometheus 抓取口。日志每 5 秒刷一行统计，高并发下请求级行更密，关键量被噪声埋掉；/metrics 能拉，但指标量大、口径不明，面板上堆了曲线却读不出结论。排障时需要把两个观测面分开：端点承担时间序列，日志承担现场对照，各自的读法与噪声来源不同。

两个观测面

观测面	载体	频率	适合读
Prometheus 端点 `/metrics`	HTTP，Prometheus 文本格式	抓取周期由采集端决定	时间序列、分位、趋势
stdout 统计日志	`LoggingStatLogger`	5 秒	快速巡检、现场对照

/metrics 由 api_server.py 的 mount_metrics(app) 挂载，实现是把 prometheus 的 asgi 应用挂到路由上（Mount("/metrics", make_asgi_app())），并对 /metrics 的路径加了一处 path_regex 修补以绕开 307 重定向。服务与 OpenAI 接口共用同一个端口，/metrics 与 /health、/version、/v1/models、/v1/chat/completions 同源，不另起独立 metrics server。

多进程采集由环境变量 PROMETHEUS_MULTIPROC_DIR 决定：设置时用带自定义 registry 的注册表并挂 MultiProcessCollector，未设置时用默认注册表。以多进程前端方式启动时框架会自动建一个临时目录并设置该变量；若该变量存在却未正确指向采集目录，读数会不准。

采集哪些：指标清单

vllm/engine/metrics.py 定义的量只有三种类型，无 Summary：

指标	类型	说明
`vllm:num_requests_running`	Gauge	运行中序列数
`vllm:num_requests_waiting`	Gauge	等待队列长度
`vllm:num_requests_swapped`	Gauge	换出到 CPU 的序列数
`vllm:gpu_cache_usage_perc`	Gauge	GPU KV 池占用比例，1 = 100%
`vllm:cpu_cache_usage_perc`	Gauge	CPU KV 池占用比例
`vllm:gpu_prefix_cache_hit_rate` / `vllm:cpu_prefix_cache_hit_rate`	Gauge	前缀缓存块命中率，−1 表示未开启或不支持
`vllm:num_preemptions_total`	Counter	累计抢占次数
`vllm:prompt_tokens_total` / `vllm:generation_tokens_total`	Counter	累计 prefill / generation token 数
`vllm:time_to_first_token_seconds`	Histogram	TTFT
`vllm:time_per_output_token_seconds`	Histogram	相邻输出 token 间隔
`vllm:e2e_request_latency_seconds`	Histogram	端到端时延
`vllm:request_prompt_tokens` / `vllm:request_generation_tokens`	Histogram	每请求输入 / 输出长度
`vllm:request_success_total`	Counter	成功请求数，带 `finished_reason` 标签
`vllm:cache_config_info`	Gauge(info)	恒为 1，标签承载 `CacheConfig` 快照

vllm:cache_config_info 是 info 型：Prometheus 多进程模式不支持 Info，框架用恒置 1 的 Gauge 模拟。它的标签是 CacheConfig.metrics_info() 的字段，读它可确认 block_size、是否开启前缀缓存等生效配置，省去从命令行反推。除它之外，静态指标的公共标签是 model_name（取 served_model_name）。

直方图桶：TTFT 为 0.001…10.0 秒，每输出 token 间隔为 0.01…2.5 秒，端到端为 1.0…60.0 秒。读分位要用 _bucket 差分出区间计数。

日志怎么读：一行统计

LoggingStatLogger 按 _LOCAL_LOGGING_INTERVAL_SEC = 5 的间隔打一行：

Avg prompt throughput: <x> tokens/s, Avg generation throughput: <x> tokens/s,
Running: <n> reqs, Swapped: <n> reqs, Pending: <n> reqs,
GPU KV cache usage: <x>%, CPU KV cache usage: <x>%.

开启了前缀缓存时追加一行：

Prefix cache hit rate: GPU: <x>%, CPU: <x>%

这行对应 get_prefix_cache_hit_rate()；未开启或后端不支持时返回 −1，该行不出现。字段口径：Running 是运行中序列数，Swapped 是换出到 CPU 的序列数，Pending 是等待队列长度，后两个 KV 占用字段已按百分比换算。Running 与 Pending 同看，可判断受限点是在批规模还是在 KV 池容量。

日志噪声：来源与抑制

噪声分三类：统计行（每 5 秒一行，有效信息）、请求级行（每请求一行，高并发下密度最高）、其他框架日志（受日志级别控制）。请求级行的原文形如：

# 请求级日志（片段，字段名示意）
Received request <id>: prompt: <prompt>, params: <params>, prompt_token_ids: <ids>, ...
Added request <id>.

抑制开关：

开关	作用	影响
`--disable-log-requests`	关请求级日志	保留 5 秒统计行与 Prometheus 端点
`--disable-log-stats`	关统计	`LoggingStatLogger` 与 `PrometheusStatLogger` 一并停，`/metrics` 不再写入 vllm 指标
`VLLM_LOGGING_LEVEL`	全局日志级别，默认 `INFO`	会一并影响后端选择等证据行，排障时慎调

--disable-log-stats 关闭的是整个统计块：本地日志 logger 与 Prometheus logger 同处一个开关之下，关闭后引擎不再写任何 vllm: 指标，/metrics 端点虽然仍挂载，但会返回空指标。稳态运行的推荐组合是只加 --disable-log-requests，保留统计行与端点。

定位步骤

先确认 /metrics 可拉：请求挂载的 /metrics 路径，注意是否被 307 重定向。
确认多进程配置：单进程用默认注册表；多进程须正确设置 PROMETHEUS_MULTIPROC_DIR，否则读数不准。
读 vllm:cache_config_info 的标签，确认生效的 block_size 与前缀缓存开关。
取四个基线量：vllm:num_requests_running、vllm:num_requests_waiting、vllm:gpu_cache_usage_perc、vllm:num_preemptions_total。
用 5 秒统计行做现场对照：Running / Pending / 两个 KV 占用列的时间序列。
按需关噪声：稳态加 --disable-log-requests，定位期再打开。

# 稳态运行：保留统计与端点，只关请求级日志（参数名取自框架）
python -m vllm.entrypoints.openai.api_server \
  --model <model-path> \
  --served-model-name <served-name> \
  --disable-log-requests

记录字段

# 一条指标采集记录（字段名示意）
endpoints:
  metrics_path: /metrics
  health_path: /health
  version_path: /version
  prometheus_multiproc_dir_set:   # 是否设置
collect:
  num_requests_running:
  num_requests_waiting:
  num_requests_swapped:
  gpu_cache_usage_perc:
  cpu_cache_usage_perc:
  prefix_cache_hit_rate:
  num_preemptions_total:
  time_to_first_token_seconds_p95:
  time_per_output_token_seconds_p95:
  cache_config_info_labels:       # cache_config_info 的标签快照
log:
  log_interval_sec: 5
  disable_log_requests:           # 是否关闭请求级日志
  disable_log_stats:              # 是否关闭统计
  logging_level:
labels:
  model_name:

小结

vLLM 0.6.x 有两个观测面：挂载在 /metrics 的 Prometheus 端点与每 5 秒一行的 stdout 统计。端点上的 KV 相关量是 vllm:gpu_cache_usage_perc 与 vllm:cpu_cache_usage_perc，生效配置从 vllm:cache_config_info 的标签读；多进程采集必须先设 PROMETHEUS_MULTIPROC_DIR。日志噪声以请求级行为主，用 --disable-log-requests 关掉即可保留统计行与端点；--disable-log-stats 会连 Prometheus 写入一并停掉，不宜在稳态使用。排障的四条基线是运行中序列数、等待队列、KV 池占用与抢占计数。