执行摘要

• 一句话：支持通过环境变量配置启动追踪级别
• 推荐动作：该 PR 变更简洁，适合快速合入。建议运维人员和开发者关注此环境变量，以便在需要减少追踪开销时使用。测试代码虽然简单，但覆盖了主要场景，可以接受。

功能与动机

当前 global_trace_level 默认值为 3，会 emit 高频率的 scheduler spans（如 decode_loop、chunked_prefill），且只能在启动后通过 HTTP 接口 /set_trace_level 调整。PR body 明确指出："There is currently no way to set a lower level at startup — operators must either call the /set_trace_level HTTP endpoint after launch or accept the default verbosity." 该变更提供了启动时即设级别的方法，无需额外运行时操作。

实现拆解

1. 修改核心配置初始化（python/sglang/srt/observability/trace.py）：将硬编码的 global_trace_level = 3 替换为 get_int_env_var("SGLANG_TRACE_LEVEL", 3)。get_int_env_var 是来自 sglang.srt.utils 的辅助函数，负责读取环境变量并转换为 int，若未设置则使用默认值。
2. 新增单元测试（test/registered/unit/observability/test_trace.py）：添加 test_global_trace_level_env_var 方法，使用 patch.dict 设置环境变量后 importlib.reload(mod) 验证 global_trace_level 正确读取为 2，然后清除环境变量再次 reload 验证恢复默认值 3。测试覆盖了 env var 设置和未设置两种场景。
3. 更新文档（docs/references/production_request_trace.md）：在 trace level 说明中增加 "At startup" 小节，给出使用 SGLANG_TRACE_LEVEL=2 启动 server 的示例命令，与已有的 "At runtime" HTTP API 方式并列。

关键文件：

• python/sglang/srt/observability/trace.py（模块 追踪模块；类别 source；类型 core-logic）: 核心变更文件，修改了 global_trace_level 的初始化方式，由硬编码改为读取环境变量。是整个 PR 的实现核心。
• test/registered/unit/observability/test_trace.py（模块 追踪模块；类别 test；类型 test-coverage；符号 test_global_trace_level_env_var）: 新增的单元测试，验证环境变量在模块加载时被正确读取，并测试了默认值回退。保障了变更的正确性。
• docs/references/production_request_trace.md（模块 文档；类别 docs；类型 documentation）: 文档更新，向用户说明如何在启动时通过环境变量配置 trace level，与已有的 HTTP API 方式形成互补。

关键符号：test_global_trace_level_env_var

关键源码片段

test/registered/unit/observability/test_trace.py

新增的单元测试，验证环境变量在模块加载时被正确读取，并测试了默认值回退。保障了变更的正确性。

# test/registered/unit/observability/test_trace.py - 新增的测试方法
    def test_global_trace_level_env_var(self):
        import importlib
​
        # 模拟设置环境变量 SGLANG_TRACE_LEVEL=2
        with patch.dict(os.environ, {"SGLANG_TRACE_LEVEL": "2"}):
            importlib.reload(mod) # 重新加载模块以读取 env var
            self.assertEqual(mod.global_trace_level, 2)
        # 清除环境变量后重新加载，验证默认值为 3
        importlib.reload(mod) # restore default (SGLANG_TRACE_LEVEL unset → 3)
        self.assertEqual(mod.global_trace_level, 3)

评论区精华

该 PR 的 review 评论较少，仅有一条 CI 准入标注。但测试设计值得注意：

• 测试策略：使用 importlib.reload(mod) 重新加载模块来测试环境变量读取，这是一种常见的做法。但需要注意 reload 可能带来副作用（如模块内的导入状态被重置）。测试在 reload 后验证默认值，确保 env var 未设置时恢复为 3。

• 潜在的讨论点：如果后续有模块导入依赖 global_trace_level 的初始值，reload 可能影响全局状态。但当前 PR 未涉及此问题。

  • 暂无高价值评论线程

风险与影响

• 风险：低风险。变更仅涉及一行核心代码，逻辑简单明确。主要风险在于：
  1. 测试副作用：importlib.reload(mod) 可能重置模块内的其他状态（如 opentelemetry_initialized），但测试中 reload 后只检查 global_trace_level，且后续测试不受影响。
  2. 兼容性：环境变量未设置时行为完全一致（默认 3）。已使用 get_int_env_var 保证安全解析。
  3. 没有性能或安全影响。
     - 影响：影响范围小，仅涉及 observability 模块的启动配置。用户现在可以通过环境变量 SGLANG_TRACE_LEVEL 在启动时控制追踪级别，无需启动后调用 HTTP API。这对于自动化部署和容器化场景尤其有用，可以减少因默认高等级追踪而产生的性能开销。对模块内部逻辑无影响，对模型输出无影响。
     - 风险标记：暂无

关联脉络

• 暂无明显关联 PR