PR 合入模板

1. 修改描述

• 修改原因：
  vLLM 推理性能定位仅依赖 Metrics 无法分析单个请求的执行链路，需要补充基于 Hook 的 Tracing 基础能力。本 PR 作为系列变更的第一部分，提供与具体 vLLM 业务埋点解耦的 Tracing Runtime、OpenTelemetry Provider 复用和 Span 旁路处理基础，为后续 Jaeger 接入及 Perfetto 文件导出提供公共接口。

• 修改内容：

  1. 新增 HookTraceRuntime，负责：
     • 请求 Trace Context 注册和释放。
     • W3C Trace Context 关联。
     • Request ID 与 Span Link 管理。
     • Span 创建、激活、结束和属性设置。
     • 并发请求上下文缓存及容量限制。
  2. 新增 OpenTelemetryHookBackend：
     • 复用 vLLM 已创建的全局 OpenTelemetry Provider。
     • 不创建私有 Provider，避免与 vLLM 原生 Tracing 重复初始化。
     • 通过 MS_TRACE_ENABLE=1 控制基础能力是否启用。
     • OTel SDK或全局 Provider 不可用时采用 fail-open 降级。
  3. 新增 Hook Span 的 Perfetto Processor 和异步 Socket Sender 基础：
     • 仅处理 instrumentation scope 以 ms_service_profiler.hook 开头的 Span。
     • 使用有界队列异步发送，避免阻塞推理线程。
     • 对属性数量、属性长度、Link 数量及队列容量设置上限。
     • Forwarder 不可用或队列满时丢弃旁路数据，不影响主业务及 Jaeger。
  4. 新增 vLLM Hook Tracing 详细设计文档，并注册到 mkdocs.yml。
  5. 新增 7 条 UT，看护全局 Provider 复用、关闭态、依赖缺失、Processor 注册失败、Span 序列化和 Scope 过滤等场景。
  6. 本 PR 不包含 vLLM 业务 Hook/YAML 配置，相关内容由后续 tracing-jaeger PR 提供。
  7. 本 PR 不包含 Perfetto JSON Exporter、Forwarder CLI，相关内容由后续 tracing PR 提供。

• 涉及代码双合（贴上另一个PR链接）：不涉及，本次仅修改 msserviceprofiler 仓库。

2. 功能验证

• 功能自验

  • test_otel_hook.py：7 passed。
  • 验证复用 vLLM 全局 OpenTelemetry Provider，不创建私有 Provider。
  • 验证 MS_TRACE_ENABLE 未开启时不访问 Provider、不创建 Span。
  • 验证 OTel SDK 缺失、Provider 缺失和 Perfetto Processor 注册失败时 fail-open。
  • 验证仅导出 ms_service_profiler.hook.* Scope 的 Span。
  • 本 PR 涉及文件 pre-commit 全部通过。
  • check_mkdocs.sh 检查通过。
  • PR 变更量为 963 行，低于 1000 行限制。

• 本地自验用例截图（请确保不体现个人信息）
  

  

• 冒烟是否通过
  Y

3. 代码检视

• 要求：

  • 合入代码大于 200 行，需三人以上会议检视。
  • 检视密度≥2个/100行。
  • 检视缺陷密度达不到要求的需给出说明。
  • 大于 1000 行代码原则上不允许合入，需进行备案。

• 是否经过代码检视
  当前 PR 共 963 行变更，未超过 1000 行，但超过 200 行，合入前需完成三人以上会议检视并补充检视记录。

• 是否具备UT测试用例看护

  • 全局 OTel Provider 复用。
  • 禁止创建私有 Provider。
  • Tracing 关闭态不访问 Provider。
  • OTel 依赖缺失时 fail-open。
  • Perfetto Processor 注册失败不影响 Jaeger Provider。
  • Hook Span 标准化序列化。
  • instrumentation scope 过滤。

4. 安全自检

典型安全编码问题

• 若涉及对外接口，是否已校验外部数据
  Trace Headers 使用 OpenTelemetry W3C Propagator 解析；非法上下文降级为空上下文。Span 属性仅接受受支持的基础类型，并限制属性数量、Key 长度、Value 长度和 Link 数量。

• MR 标题和描述是否按格式填写

• 是否进行空指针校验
  已处理 OTel SDK缺失、全局 Provider 缺失、Span 不可记录、Trace Headers 为空、上下文无效和 instrumentation scope 缺失等场景。

• 是否进行返回值校验
  Span 创建失败返回 No-op Span；上下文注册、Processor 探测和发送操作均检查结果或提供安全降级。

• 是否正确考虑文件权限配置
  本 PR 不创建落盘文件；Perfetto Sender 使用 Linux Abstract Unix Socket，不产生需要配置权限的 Socket 文件。实际 JSON 文件权限由第三笔 Perfetto PR负责。

• 是否充分考虑接口的异常场景

  • OTel SDK未安装。
  • vLLM 未创建全局 Provider。
  • Trace Headers 无效。
  • Span 创建、激活、结束失败。
  • Perfetto Forwarder 不可用。
  • Processor 注册或关闭失败。
  • 异步发送队列已满。
  • Socket 连接和发送失败。

• 是否正确记录错误日志
  Provider 缺失和依赖缺失记录 warning；旁路注册、序列化和发送失败记录 debug/warning，日志不记录完整请求内容和 Trace Headers。

• 若涉及正则表达式，是否对正则表达式做 ReDos 校验
  本 PR 不涉及新增正则表达式。

• 若涉及运算，是否存在整数溢出、除零等风险
  本 PR 不涉及除法运算；请求上下文、Span Links、属性数量、字符串长度及异步队列均设置明确上限。

5. 变更知会

• 资料修改：

  • 新增 docs/design/vLLM_Hook_Tracing_Detailed_Design.md。
  • 更新 mkdocs.yml，增加 vLLM Hook Tracing 详细设计入口。

• 变更通知（消息知会 + 邮件知会）：

6. 冒烟修改

• PR 来源：

  • 问题单
  • 需求特性
  • 安全排查
  • 其他

• 是否存在冒烟可以拦截却未拦截的情况：否
  当前基础能力的正常、关闭态和异常降级场景均由 UT 看护，未发现已有冒烟可拦截但未拦截的问题。

• 是否需要添加冒烟：否（本 PR）
  本 PR 为未绑定具体业务符号的内部基础能力，使用 UT 看护。真实 vLLM 请求链路、Jaeger 展示和 Perfetto 双写冒烟分别在后续业务接入 PR 中验证。