跳转到正文

SGLang 日志注入的行为与边界

本文目录

是什么、为什么

SGLang 默认的日志格式只有时间戳和 rank 前缀,没有级别。引擎里的真实错误和普通请求日志因此看起来一样,平台「日志」页的级别过滤(level=warn)和直方图也就看不到它们。

SGLang 支持通过环境变量 SGLANG_LOGGING_CONFIG_PATH 读取一份 Python dictConfig 文件。平台利用这一点:在适用的部署上,由 SGLang 适配代码(internal/server/deploy/sglang_logging.go)生成一份带级别的日志配置和写入它的启动前脚本。这套环境和脚本由 SGLang 适配代码持有,API、通用部署流程和前端不重复实现(见 ADR 0022)。

日志级别的选择方法见查看指标与检索日志 · 设置引擎日志级别;本文解释它自动做什么、什么时候不做、以及怎么自己接管。

自动做什么

满足条件时,平台在最终启动方案里加两样东西,二者始终成对出现:

内容说明
环境变量SGLANG_LOGGING_CONFIG_PATH=/tmp/gpuworks-sglang-logging.json
启动前脚本每次容器启动、引擎命令之前,把配置写入上面的路径

脚本每次启动都执行,因为 SGLang 把“变量已设置但文件不存在”当作致命的配置错误,所以文件和变量必须同时存在。

配置本身做这几件事:

  • 输出格式为 [时间 进程号] 级别 消息,写到容器 stderr,所以 docker logs 和平台日志采集看到的仍是同一路输出。
  • 根 logger 的阈值取自最终的 --log-level(转成大写)。
  • 顺带压低噪声:httpx、httpcore 只输出 WARNING 及以上,flashinfer.jit 只输出 ERROR 及以上。

部署命令预览默认显示命令,环境变量与准备步骤可展开查看,预览里能看到 SGLANG_LOGGING_CONFIG_PATH 和写入配置的启动前脚本;实例详情也可以查看保存的脚本和 env。复制预览会包含全部启动步骤。

/tmp/gpuworks-sglang-logging.json 是配置文件,不是日志输出文件。

什么时候不自动做

只有下面全部成立才会注入;任何一条不成立就保持现状,由引擎用自己的默认格式。每条限制都对应一种真实的失败方式:

条件不满足时为什么不注入
命令模式是 engine(引擎接管)manual 和 image-entry 的命令归用户所有,平台不改写
启动方案有明确的 entrypointagent 的包装脚本要按 entrypoint 边界执行原命令,只有启动方案写明边界时才可靠
没有 pre_start_argvagent 不接受启动前脚本与 argv 同时存在;模板自带的准备命令优先于平台追加的脚本
没有人设置 SGLANG_LOGGING_CONFIG_PATH谁设置了,谁就拥有日志配置
最终命令里没有 --log-fileSGLang 使用自定义日志配置时会跳过它自己的文件 handler 设置,注入会让文件日志悄悄消失
最终命令里有明确的 --log-level配置阈值由它派生;没有显式设置时不注入,由引擎决定默认级别(表单里选「未设置」就是这种情况)
没有用户指定的 --config,--log-level 写法完整且取值有效缩写或无效的级别参数交给 SGLang 自己解释,不重新解读
单进程启动(tp/pp/dp/ep/nnodes/moe-dp 均为 1 或未设置,且不是符号占位值)并行启动保留上游的 rank 日志前缀,不改格式

另外,即使注入了配置,引擎或第三方库直接写出的、不含级别的原始日志行,在「日志」页里仍可能没有级别(按普通文本显示,设了级别过滤后不会命中)。

怎么自己接管

带准备步骤的方案(例如模板带启动前脚本)仍可手动编辑命令。在部署页命令预览里进入编辑时:

  1. 页面把完整脚本(包括准备步骤和日志配置)放进手工命令,命令模式切到 manual。
  2. 部署请求的 container_overrides.command_includes_preparation 被设为 true,表示“这份手工脚本已经包含准备步骤”。服务端因此不再额外执行模板的准备步骤,避免同样的副作用执行两次。
  3. manual 模式下平台不注入日志配置;脚本里保留、修改或删掉日志配置,都由你控制。

几条边界:

  • command_includes_preparation 是部署覆盖上的意图标记,无法从任意 shell 文本推断。旧的手写命令没有这个标记,继续照原样执行模板准备步骤。
  • 它只在有手工命令且命令模式为 manual 时有效,否则被校验拒绝。
  • 从编辑状态“返回表单”会丢弃手工覆盖,按表单重新生成命令,此时自动注入的规则重新生效。

如果不想接管整个脚本,只是想换用自己的日志配置,直接在环境变量里设置 SGLANG_LOGGING_CONFIG_PATH(并自行保证文件存在)即可:平台看到这个变量就不再注入。

这篇文档有帮助吗?