3、日志监控核心概念：日志级别（DEBUG/INFO/WARNING/ERROR）、结构化日志、日志轮转与保留策略

vLLM 作为高性能 LLM 推理服务，其运行状态直接决定了上层业务的可用性与响应质量。在生产环境中，日志是运维人员观察系统内部行为的“眼睛”。然而，vLLM 的日志输出量巨大，若缺乏体系化的管理，极易陷入“日志海洋”中无法定位问题。本章将围绕日志监控的三个核心支柱展开：日志级别（控制输出粒度）、结构化日志（统一解析格式）以及日志轮转与保留策略（管理存储成本与合规要求）。理解并掌握这三者，是构建可观测性体系的基础，也是后续进行故障排查与性能调优的必备前提。

上图清晰地展示了日志监控三大核心概念之间的协同关系。日志级别决定了信息采集的“广度与深度”，结构化日志决定了信息存储的“规范与效率”，而轮转与保留策略则决定了日志数据的“生命周期与成本”。在实际运维中，三者必须联动配置，才能构建出既高效又可靠的日志体系。下面我们将逐一深入剖析。

3.1 日志级别：控制输出粒度的阀门

3.1.1 核心原理：从 DEBUG 到 CRITICAL 的过滤机制

vLLM 基于 Python 的 logging 模块实现日志记录，其级别体系遵循标准定义。每个级别对应一个数值，数值越小，优先级越低，输出越详细。默认情况下，vLLM 的日志级别为 INFO，这意味着 DEBUG 级别的日志（如每次请求的详细参数、内部状态变更）会被过滤掉，而 INFO 及以上级别的日志（如模型加载完成、启动参数、请求统计）会正常输出。

3.1.2 判断方法与操作流程：如何设置与动态调整

设置日志级别有两种常用方式。第一种是通过环境变量 VLLM_LOG_LEVEL 在启动前指定；第二种是在代码中通过 logging.basicConfig 或 vLLM 的 EngineArgs 参数进行配置。推荐使用环境变量，因为它无需修改代码即可灵活调整。

# 启动 vLLM 服务时设置日志级别为 DEBUG
export VLLM_LOG_LEVEL=DEBUG
python -m vllm.entrypoints.openai.api_server --model meta-llama/Llama-3-8B-Instruct

# 或者仅将某个模块的日志级别调高，避免刷屏
export VLLM_LOGGING_LEVEL=WARNING

3.1.3 案例拆解：一次“静默失败”的定位过程

背景：某团队反馈 vLLM 服务偶尔返回 500 错误，但 INFO 级别日志中没有任何异常记录。

分析过程：运维人员将日志级别临时调整为 DEBUG，并过滤 vllm.engine 模块。很快发现，在错误发生的时间点，有一条 WARNING 级别的日志被忽略：CUDA error: an illegal memory access was encountered。由于该错误被 vLLM 的异常捕获机制吞掉并降级为 WARNING，导致上层应用只看到 500 错误，而根因被隐藏。

操作步骤：

1. 将 VLLM_LOG_LEVEL 临时设为 DEBUG，重启服务。
2. 复现故障，收集 vllm.engine 与 vllm.worker 的完整日志。
3. 发现 WARNING 级别的 CUDA 错误后，进一步检查 GPU 显存状态，确认是显存不足导致的内存越界。
4. 调整 --gpu-memory-utilization 参数并增加 --max-num-seqs 限制，问题解决。

复盘：仅依赖默认 INFO 级别会掩盖底层硬件或驱动层的警告。建议在监控系统中对 WARNING 级别日志单独建立索引，并设置告警阈值，避免“静默失败”。

3.2 结构化日志：从“人读”到“机读”的转变

3.2.1 核心原理：为什么需要结构化

传统的文本日志（如 2025-01-15 10:00:00 ERROR Failed to process request）对人类友好，但难以被自动化工具解析。结构化日志将信息编码为键值对或 JSON 格式，使得日志可以被 Logstash、Loki、Elasticsearch 等工具直接索引和查询。vLLM 原生支持 JSON 格式输出，通过配置 --log-format json 即可启用。

# 启用 JSON 结构化日志
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3-8B-Instruct \
  --log-format json

# 输出示例
{"timestamp": "2025-01-15T10:00:00.123456Z", "level": "INFO", "event": "request_completed", "request_id": "req_123", "latency_ms": 45.2, "prompt_tokens": 128, "completion_tokens": 256}

3.2.2 关键字段设计与最佳实践

一份高质量的结构化日志应包含以下字段：时间戳（ISO 8601 格式，含时区）、级别、事件名称（如 request_started、request_completed）、请求 ID（用于关联全链路）、模型名称、延迟指标、Token 计数、GPU 显存使用量等。避免在日志中嵌入换行符或未转义的引号，这会破坏 JSON 解析。

3.2.3 实战场景：基于结构化日志的延迟分析

某团队需要分析 P99 延迟突增的原因。通过查询 JSON 日志中的 event: "request_completed" 记录，按 model_name 和 timestamp 分组，计算 latency_ms 的百分位数。进一步关联 prompt_tokens 与 completion_tokens，发现延迟突增与输入 Token 长度超过 2048 的请求高度相关。由此定位到是长序列导致 Attention 计算量激增，而非系统资源瓶颈。

3.3 日志轮转与保留策略：存储成本与合规的平衡

3.3.1 核心原理：防止磁盘被写满

vLLM 在高并发下每天可产生数 GB 的日志。若不加以控制，日志文件会迅速占满磁盘，导致服务崩溃。日志轮转（Log Rotation）是指在日志文件达到特定条件（如大小、时间）时，自动重命名并创建新文件的过程。保留策略则规定了历史日志文件的保存数量或保存时长。

3.3.2 操作流程：使用 logrotate 管理 vLLM 日志

Linux 系统下最常用的工具是 logrotate。以下是一个针对 vLLM 的配置示例：

# /etc/logrotate.d/vllm
/var/log/vllm/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
    maxsize 500M
    postrotate
        # 可选：通知 vLLM 重新打开日志文件（如果支持）
        # kill -USR1 $(cat /var/run/vllm.pid)
    endscript
}

• daily：每天轮转一次。
• rotate 7：保留最近 7 个轮转文件。
• compress：对旧文件进行 gzip 压缩。
• copytruncate：复制日志内容并清空原文件，适用于 vLLM 这类不重新打开文件句柄的进程。
• maxsize 500M：即使未到一天，文件达到 500MB 也强制轮转。

3.3.3 案例拆解：磁盘告警的紧急处置与长期优化

背景：某生产环境 vLLM 节点磁盘使用率超过 90%，触发告警。

初始现象：检查发现 /var/log/vllm/ 目录下存在一个 20GB 的 vllm.log 文件，且仍在持续增长。

分析判断：该节点未配置 logrotate，导致日志无限增长。同时，日志级别为 INFO，包含大量请求级信息。

实际操作：

1. 立即执行 logrotate -f /etc/logrotate.d/vllm 强制轮转，释放磁盘空间。
2. 将日志级别调整为 WARNING，减少 INFO 级别的请求日志输出。
3. 配置 --log-format json 并接入集中式日志系统（如 Loki），实现日志的实时采集与长期存储。
4. 设置磁盘配额监控，当使用率超过 80% 时自动告警。

结果对比：优化后，单节点日志日增量从 5GB 降至 200MB，磁盘使用率稳定在 40% 以下。同时，由于采用了结构化日志，排障效率显著提升。

复盘经验：日志轮转不是“可选项”而是“必选项”。在部署 vLLM 时，应将 logrotate 配置纳入初始化脚本，并定期演练日志恢复流程。