PR 合入模板

1. 修改描述

• 修改原因：
  PR #446 已提供 OpenTelemetry Hook Tracing 基础能力，但尚未接入 vLLM/vLLM-Ascend 业务函数，无法生成包含请求、调度、模型执行和输出处理语义的 Hook Span。

  本 PR 作为 Tracing 系列第二部分，在不修改 vLLM IPC、不侵入 vLLM/vLLM-Ascend 源码、不影响原有 Profiling 能力的前提下，通过现有 Hook 机制接入 vLLM 业务埋点，并复用 vLLM 全局 OpenTelemetry Provider，将 Hook Span 通过 vLLM 配置的 OTLP Endpoint 导出至 Jaeger。

  前置 PR：Tracing 1/3：新增 OpenTelemetry Hook Tracing 基础能力

• 修改内容：

  1. 新增 trace_hook.py，提供独立的 Tracing Around Hook：

     • 支持同步和异步业务函数。
     • 支持 call、request、request_context、schedule、model、output 等语义适配器。
     • 支持 Span 名称、Domain、SpanKind 和适配器的声明式配置。
     • 业务函数异常时记录失败状态并继续抛出原异常，不改变原函数行为。

  2. 扩展现有 Hook 配置加载能力：

     • 在原有 Profiling YAML 条目中增加可选 trace 字段。
     • Tracing 关闭时保持原有 Profiling 配置解析和 Handler 行为。
     • Trace-only 模式下不加载、不执行原有 Profiling Handler。
     • 同一个 Symbol 仅允许一个有效 Tracing Wrapper，避免重复埋点。
     • 非法 Tracing 配置记录告警并跳过，不影响业务进程启动。

  3. 在内置 service_profiling_symbols.yaml 中增加当前 vLLM/vLLM-Ascend 埋点：

     • vllm.request
     • vllm.scheduler.schedule
     • vllm.model.execute
     • vllm_ascend.model_runner.execute
     • vllm.output.process

  4. 复用 vLLM 原生 Tracing 上下文：

     • 从 vLLM 已有 trace_headers 获取 W3C Trace Context。
     • 使用 vLLM 已有 request_id 关联请求、调度和模型执行 Span。
     • 不新增或修改 vLLM IPC 协议。
     • 不自行创建 OpenTelemetry Provider，复用 vLLM 全局 Provider及 OTLP Exporter。

  5. 隔离 Tracing 与原有 Profiling 生命周期：

     • MS_TRACE_ENABLE=1 单独控制 Hook Tracing。
     • Trace-only 模式不初始化 Profiling Metrics 和业务 Handler。
     • Profiling 停止后，如 Tracing 仍开启，则仅保留 Tracing Hook。
     • Profiling 与 Tracing 同时开启时复用同一 Symbol Hook 链，避免重复 Hook。
     • Tracing 关闭时不改变现有 Profiling 启停流程。

  6. 根据前置 PR 检视意见补充可靠性修复：

     • 使用 itertools.islice 限制 Request ID 可迭代对象的消费数量，避免完整展开超大可迭代对象。
     • Perfetto Processor 仅在注册成功后记录 Provider。
     • Processor 注册失败增加退避重试，恢复后允许自动重新注册。
     • Processor 构造或注册失败保持 fail-open，不影响 Jaeger 和推理主链路。

  7. 补充 UT，覆盖：

     • Tracing 配置解析和非法配置降级。
     • 同步、异步 Hook Wrapper。
     • Request Context 注册和释放。
     • Scheduler、Model、Output 语义提取。
     • Trace-only、Profiling-only 和二者同时开启。
     • Profiling 停止后 Tracing Hook 保留。
     • 重复 Symbol 去重。
     • Request ID 迭代数量限制。
     • Perfetto Processor 注册失败、退避及恢复重试。

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

2. 功能验证

• 功能自验

  • PR2 相关 UT：49 passed。
  • PR2 涉及文件 pre-commit 全部通过。
  • PR2 变更量：837 insertions + 52 deletions = 889，低于 1000 行限制。
  • 已在真实 vLLM-Ascend/NPU 环境中启动 vLLM 原生 Tracing，并配置 OTLP Endpoint 对接 Jaeger。
  • 已通过真实推理请求验证 Hook Span 能够写入 Jaeger。
  • Jaeger 中能够查询并展示 vllm.scheduler.schedule、vllm.model.execute 等 Hook Span。
  • Tracing 异常日志检查未发现 error、failed、exception、unavailable 或数据丢弃告警。

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

  

• 冒烟是否通过
  • 已在真实 vLLM-Ascend/NPU 环境通过 vllm serve 启动服务。
  • 已发送真实推理请求并确认请求成功。
  • 已确认 Jaeger 能够查询到 vLLM 原生 Span 和 msserviceprofiler Hook Span。
  • 未发现 Tracing 导致 vLLM 启动失败、请求失败或原有 Profiling 流程异常。

3. 代码检视

• 要求：

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

• 是否经过代码检视
  是

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

  • 新增和扩展 UT 覆盖正常、关闭态、异常、边界、兼容及恢复场景。
  • 当前 PR 相关测试执行结果为 49 passed。

4. 安全自检

典型安全编码问题

• 若涉及对外接口，是否已校验外部数据

  • trace 配置校验名称、Domain、SpanKind 和 Adapter 类型。
  • 非法配置记录告警并跳过。
  • Trace Headers 由 OpenTelemetry W3C Propagator 解析。
  • Request ID、Span Link 和属性数量均设置上限。

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

• 是否进行空指针校验

  • 已处理 Trace Headers、Request ID、Scheduler Output、Engine Output、Span、Provider 和 Processor 为空的场景。

• 是否进行返回值校验

  • 已校验 Span 创建、Context 注册、Processor 注册和 Hook 安装结果。
  • Tracing 创建失败时返回 No-op Span，不影响原函数调用。

• 是否正确考虑文件权限配置

  • 本 PR 不新增落盘文件。
  • Jaeger 数据通过 vLLM 已配置的 OTLP Endpoint 导出，不新增本地文件权限配置。

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

  • 已覆盖非法 YAML、业务函数异常、OpenTelemetry Provider 缺失、Processor 构造失败、Processor 注册失败、Trace Context 无效及 Tracing 关闭等场景。
  • 异常场景采用 fail-open 策略，不影响推理主链路。

• 是否正确记录错误日志

  • 配置错误和 Provider 缺失记录 warning。
  • Span、Processor 和上下文处理异常记录 debug/warning。
  • 日志不记录完整请求内容及 Trace Headers。

• 若涉及正则表达式，是否对正则表达式做 ReDos 校验

  • 本 PR 不涉及新增正则表达式。

• 若涉及运算，是否存在整数溢出、除零等风险

  • 本 PR 不涉及除法运算。
  • Request Context 缓存、Request ID、Span Link、属性数量和字符串长度均设置明确上限。

5. 变更知会

• 资料修改：

  • 本 PR 不新增独立资料文档。
  • Tracing 详细设计已随前置 PR #446 合入。
  • 完整用户使用指导和 Perfetto 导出说明由后续 Tracing 3/3 PR 提供。
  • 本 PR 更新内置 service_profiling_symbols.yaml，增加 vLLM/vLLM-Ascend Tracing 业务埋点配置。

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

6. 冒烟修改

• PR 来源：

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

• 是否存在冒烟可以拦截却未拦截的情况：否

  • Trace-only、Profiling-only、组合开启、真实 vLLM 请求和 Jaeger 展示场景均已有 UT 或真实环境验证。

• 是否需要添加冒烟：是

  • 后续在具备 vLLM-Ascend、NPU 和 OTLP Collector/Jaeger 环境的流水线中增加真实链路冒烟。
  • 冒烟至少验证 vLLM 服务正常启动、推理请求成功、Jaeger 可查询 Hook Span，并确认 Tracing 失败不影响推理请求。