架构说明
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 的命令归用户所有,平台不改写 |
| 启动方案有明确的 entrypoint | agent 的包装脚本要按 entrypoint 边界执行原命令,只有启动方案写明边界时才可靠 |
没有 pre_start_argv | agent 不接受启动前脚本与 argv 同时存在;模板自带的准备命令优先于平台追加的脚本 |
没有人设置 SGLANG_LOGGING_CONFIG_PATH | 谁设置了,谁就拥有日志配置 |
最终命令里没有 --log-file | SGLang 使用自定义日志配置时会跳过它自己的文件 handler 设置,注入会让文件日志悄悄消失 |
最终命令里有明确的 --log-level | 配置阈值由它派生;没有显式设置时不注入,由引擎决定默认级别(表单里选「未设置」就是这种情况) |
没有用户指定的 --config,--log-level 写法完整且取值有效 | 缩写或无效的级别参数交给 SGLang 自己解释,不重新解读 |
单进程启动(tp/pp/dp/ep/nnodes/moe-dp 均为 1 或未设置,且不是符号占位值) | 并行启动保留上游的 rank 日志前缀,不改格式 |
另外,即使注入了配置,引擎或第三方库直接写出的、不含级别的原始日志行,在「日志」页里仍可能没有级别(按普通文本显示,设了级别过滤后不会命中)。
怎么自己接管
带准备步骤的方案(例如模板带启动前脚本)仍可手动编辑命令。在部署页命令预览里进入编辑时:
- 页面把完整脚本(包括准备步骤和日志配置)放进手工命令,命令模式切到
manual。 - 部署请求的
container_overrides.command_includes_preparation被设为true,表示“这份手工脚本已经包含准备步骤”。服务端因此不再额外执行模板的准备步骤,避免同样的副作用执行两次。 manual模式下平台不注入日志配置;脚本里保留、修改或删掉日志配置,都由你控制。
几条边界:
command_includes_preparation是部署覆盖上的意图标记,无法从任意 shell 文本推断。旧的手写命令没有这个标记,继续照原样执行模板准备步骤。- 它只在有手工命令且命令模式为
manual时有效,否则被校验拒绝。 - 从编辑状态“返回表单”会丢弃手工覆盖,按表单重新生成命令,此时自动注入的规则重新生效。
如果不想接管整个脚本,只是想换用自己的日志配置,直接在环境变量里设置 SGLANG_LOGGING_CONFIG_PATH(并自行保证文件存在)即可:平台看到这个变量就不再注入。
这篇文档有帮助吗?