PR 合入模板

1. 修改描述

• 修改原因：
  前两笔 PR 已分别提供 OpenTelemetry Hook Tracing 基础能力，以及 vLLM/vLLM-Ascend 业务埋点和 Jaeger 链路展示能力。

  本 PR 作为 Tracing 系列第三部分，补充 Hook Span 到 Perfetto/Chrome Trace JSON 的可选导出能力，使开发者在启用 vLLM 原生 Tracing 后，可以选择仅将链路导出到 Jaeger，或者同时生成可通过 Perfetto UI 分析的本地 JSON 文件。

  本 PR 同时完善 vLLM Hook Tracing 使用资料，明确 Jaeger-only、Jaeger与Perfetto双写、容器网络、真实推理负载、Profiling 共存和异常定位流程。

  前置 PR：

  • Tracing 1/3：新增 OpenTelemetry Hook Tracing 基础能力
  • Tracing 2/3：接入vLLM Hook Tracing埋点并支持Jaeger链路展示

• 修改内容：

  1. 扩展 python -m ms_service_profiler.trace 命令：

     • 新增可选参数 --perfetto-output <path.json>。
     • 未指定 --perfetto-output 时，继续使用原有 OTLPForwarderService，不改变 MindIE Motor 原有 Trace 转发行为。
     • 指定 --perfetto-output 时，启动独立的 PerfettoForwarderService。
     • vLLM 原生 Tracing 仍是前置条件，Perfetto Forwarder 本身不创建 Span。

  2. 新增 PerfettoTraceExporter：

     • 将标准化 Hook Span 数据转换为 Perfetto 兼容的 Chrome Trace JSON。
     • 使用 Complete Event（ph=X）记录 Span 名称、开始时间、持续时间、PID、TID和属性。
     • 保留 trace_id、span_id、parent_span_id、Span Kind、Span Status、Service Name和 Resource Attributes。
     • 使用 Flow Event（ph=s/f）展示 Request Span与调度、模型执行 Span 之间的 Link 关系。
     • 支持先收到目标 Span、后收到源 Span时的延迟 Link 关联。
     • 增量写入过程中持续保持 JSON 文件格式有效。
     • 仅接受带有 Hook Span Magic Header 的标准化数据，不转换原有 Profiling 数据或旧版 Binary OTLP 数据。
     • Span位置和待关联 Link 设置最大缓存数量，避免无界内存增长。

  3. 新增独立的 PerfettoForwarderService：

     • 使用独立 Linux Abstract Unix Socket MSP_PERFETTO_SOCKET。
     • 与原有 MindIE OTLP Forwarder 解耦，不修改原有跨进程协议。
     • 使用有界接收队列，避免无界数据积压。
     • 支持 SIGINT、SIGTERM 和 KeyboardInterrupt 安全退出。
     • 服务退出前停止 Socket、排空队列并关闭 JSON 文件。

  4. 增加 Perfetto 输出路径安全校验：

     • 输出路径必须以 .json 结尾。
     • 校验路径字符合法性。
     • 拒绝符号链接、目录和其他非普通文件。
     • 已存在文件必须属于当前用户。
     • 使用 O_NOFOLLOW 防止打开过程中跟随符号链接。
     • 父目录权限设置为 0750，输出文件权限设置为 0640。

  5. 保持 Jaeger 与 Perfetto 两个出口相互隔离：

     • Jaeger 继续由 vLLM 全局 OpenTelemetry Provider及原生 OTLP Exporter负责。
     • Perfetto 通过附加 Span Processor接收 ms_service_profiler.hook.* Scope的 Hook Span。
     • Perfetto Forwarder未启动或写入失败时，Jaeger和推理主链路不受影响。
     • 本实现不支持 Perfetto-only，vLLM必须通过 --otlp-traces-endpoint 开启原生 Tracing。

  6. 新增和更新使用资料：

     • 新增 docs/zh/vLLM_hook_tracing_instruct.md。
     • 更新 msserviceprofiler_trace_data_monitoring_instruct.md。
     • 更新 vLLM_service_oriented_performance_collection_tool.md。
     • 更新 mkdocs.yml，注册 vLLM Hook Tracing使用指南。
     • 资料覆盖功能边界、数据流、埋点配置、Jaeger-only、Jaeger与Perfetto双写、容器网络、真实推理负载、Jaeger分析方法、验收层级、Profiling共存和常见异常。

  7. 补充 UT，覆盖：

     • Hook Span到 Chrome Trace Complete Event的转换。
     • Request Link到 Perfetto Flow Event的转换。
     • Link源 Span延迟到达场景。
     • 非Hook数据包拒绝场景。
     • 非法输出路径拒绝场景。
     • 独立 Perfetto Socket使用。
     • Forwarder数据接收、导出、队列排空和资源关闭。
     • CLI未指定参数时保持原有 OTLP Forwarder。
     • CLI指定 --perfetto-output 时启动 Perfetto Forwarder。

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

2. 功能验证

• 功能自验

  • 本 PR新增/修改功能专项 UT：9 passed。
  • 完整 Tracing相关回归：58 passed。
  • 本 PR涉及文件 pre-commit全部通过。
  • scripts/check_mkdocs.sh资料导航检查通过。
  • PR变更量：707 insertions + 30 deletions = 737，低于1000行限制。
  • 已在真实 vLLM-Ascend/NPU环境启动 vLLM原生 Tracing并发送真实推理请求。
  • Jaeger能够查询 vLLM原生 Span和 msserviceprofiler Hook Span。
  • Perfetto JSON能够生成有效 Complete Event。
  • Perfetto JSON已匹配以下 Hook Span：
    • vllm.scheduler.schedule
    • vllm.model.execute
    • vllm_ascend.model_runner.execute
    • vllm.output.process
  • Jaeger与Perfetto双写过程中未发现影响 vLLM启动或推理请求的异常。
  • 
  • 

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

  • 请补充 Jaeger Trace查询结果截图。
  • 请补充 Perfetto/Chrome Trace JSON校验结果或 Perfetto UI截图。
  • 请补充真实推理请求成功截图。

• 冒烟是否通过

  • 已在真实 vLLM-Ascend/NPU环境启动 vLLM服务。
  • 已发送真实推理请求并确认请求成功。
  • 已验证 Jaeger-only场景。
  • 已验证 Jaeger与Perfetto双写场景。
  • 已验证 Perfetto JSON非空且包含预期 Hook Span。
  • 未发现 Tracing功能影响原有 Profiling或推理主链路。

3. 代码检视

• 要求：

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

• 是否经过代码检视

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

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

  • 新增9条专项 UT。
  • 覆盖正常转换、Link关联、输入校验、旧数据拒绝、资源关闭和CLI兼容场景。
  • 完整 Tracing相关回归执行结果为 58 passed。

4. 安全自检

典型安全编码问题

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

  • 校验输出路径类型、后缀、合法字符、文件类型、文件属主和符号链接。
  • Perfetto Exporter仅接受带有指定 Magic Header的 Hook Span数据包。
  • JSON解析或字段转换失败时记录告警并丢弃异常数据，不影响服务主流程。

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

• 是否进行空指针校验

  • 已处理空数据包、空属性、空Resource Attributes、空Links、空Socket数据和重复关闭场景。

• 是否进行返回值校验

  • 校验路径合法性、Exporter转换结果、Socket读取数据及服务初始化结果。
  • Exporter失败时返回 False，Forwarder继续运行并记录告警。

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

  • 父目录使用 0750 权限创建。
  • 输出文件使用 0640 权限创建。
  • 使用 O_NOFOLLOW 防止跟随符号链接。
  • 拒绝非普通文件、非当前用户所有文件及符号链接。

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

  • 已覆盖非法路径、非法数据包、JSON解析失败、Socket异常、Exporter异常、服务信号退出、队列排空和重复关闭等场景。
  • Perfetto异常采用旁路降级，不影响Jaeger和推理主链路。

• 是否正确记录错误日志

  • 路径、数据转换和导出异常记录 warning/error。
  • 服务启动、退出及信号处理记录 info。
  • 日志不记录完整请求内容、Trace Headers或敏感模型输入。

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

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

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

  • 本 PR不涉及除法运算。
  • Span持续时间使用非负值保护。
  • Span位置和待关联 Link缓存设置最大数量。
  • Socket接收队列设置明确容量上限。

5. 变更知会

• 资料修改：

  • 新增 docs/zh/vLLM_hook_tracing_instruct.md。
  • 更新 docs/zh/msserviceprofiler_trace_data_monitoring_instruct.md。
  • 更新 docs/zh/vLLM_service_oriented_performance_collection_tool.md。
  • 更新 mkdocs.yml资料导航。
  • 已通过资料导航和本地链接检查。

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

  • 合入前知会 msserviceprofiler、vLLM-Ascend及推理服务可观测性相关开发和维护人员。
  • 新增用户可感知参数 --perfetto-output，需在版本说明中知会。
  • 未指定该参数时保持原有 Trace Forwarder行为，不影响现有用户。

6. 冒烟修改

• PR 来源：

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

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

  • CLI兼容、Perfetto导出、真实 vLLM请求、Jaeger展示和双写场景均已有UT或真实环境验证。

• 是否需要添加冒烟：是

  • 建议在具备 vLLM-Ascend、NPU和Jaeger环境的流水线中增加真实链路冒烟。
  • 冒烟至少验证：
    • 未指定 --perfetto-output 时原有 OTLP Forwarder正常。
    • 指定 --perfetto-output 时能够生成合法 JSON。
    • 真实推理请求成功。
    • Jaeger可查询 Hook Span。
    • Perfetto JSON包含预期 Hook Span。
    • Perfetto异常不影响Jaeger和推理请求。