1. 修改描述

• 修改原因：
  当前用户自定义指标仅支持通过 MS_SERVICE_METRIC_CONFIG_PATH 指定单个 YAML；自定义 Handler 还需要修改、安装 Python 包或调整 PYTHONPATH，不利于用户按模块组织和维护自定义指标。

  同时，vLLM Metrics 插件初始化异常会向上传播，依赖缺失等 Metrics 故障可能导致 vllm serve 启动失败，不符合 Metrics 可选观测能力的 fail-open 原则。

• 修改内容：

  1. 扩展 MS_SERVICE_METRIC_CONFIG_PATH，兼容原有单 YAML，并支持指定单目录下多个 .yaml/.yml 文件。
  2. YAML 按文件名稳定排序加载，忽略子目录和非 YAML 文件，复用原有配置合并及语义去重逻辑。
  3. 支持用户在配置根目录提供多个外部 Handler，保持原有 module.path:function_name 写法，无需修改 PYTHONPATH 或安装额外 Handler 包。
  4. 新增受控外部 Handler 加载器，仅加载 YAML 明确引用的文件，不修改全局 sys.path。
  5. 校验 Handler 模块路径、目标文件和真实路径，防止非法路径、目录穿越及符号链接逃逸。
  6. 外部 Handler 模块使用真实文件路径哈希进行进程内缓存；Handler 文件变更后需重启 vLLM 服务。
  7. 配置或 Handler 构造失败时保留原配置及 Hook，避免提交部分状态。
  8. vLLM Metrics 插件入口增加 fail-open 保护：Metrics 初始化失败时记录错误、清理半初始化状态并禁用 Metrics，不再阻断 vLLM 启动。
  9. 更新 README 和整体重构设计文档，补充使用方法、文件放置要求、安全边界及责任边界。
  10. 外部 YAML 和外部 Handler 的正确性、依赖及维护由用户自行负责。

• 涉及代码双合（不涉及，本次修改仅位于 msserviceprofiler）

2. 功能验证

• 功能自验

  • 相关 UT：112 passed, 1 skipped。
  • 跳过项为 Windows 环境无权限创建符号链接，不影响 Linux CI 对应能力。
  • 真实 vLLM-Ascend 服务验证通过。
  • 同一用户配置目录成功加载 2 个 YAML。
  • 成功加载并执行两个不同位置的外部 Handler：
    • execute_handler.py
    • handlers/prepare_handler.py
  • 实际采集结果：
    • vllm_profiling_user:external_execute_model:duration_count = 100
    • vllm_profiling_user:external_prepare_inputs_total = 80
  • vLLM 请求正常，指标可通过 /metrics 获取。
  • Ruff、Ruff format、Pylint、Bandit、codespell、typos 等检查通过。

• 本地自验用例截图
  

  

  

  

• 冒烟是否通过

3. 代码检视

• 要求：

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

• 是否经过代码检视

• 是否具备UT测试用例看护
  已覆盖：

  • 单 YAML 兼容。
  • 单目录多 YAML 排序和加载。
  • 多 YAML 语义去重。
  • 同目录及子目录外部 Handler。
  • 多个外部 Handler。
  • 非法模块名和目录穿越。
  • 符号链接逃逸。
  • Handler 文件、函数缺失及加载异常。
  • 加载失败后的重试。
  • 配置及 Handler 构造失败回滚。
  • vLLM Metrics 插件初始化 fail-open。
  • 半初始化 Manager 清理。

4. 安全自检

典型安全编码问题

• 若涉及对外接口，是否已校验外部数据
  已校验配置路径、模块名、目标文件、真实路径、函数存在性和可调用性。

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

• 是否进行空指针校验
  已处理空配置路径、空 Handler 根目录、无效模块加载描述及部分初始化对象。

• 是否进行返回值校验
  已校验模块加载 spec、loader、目标函数和指标初始化结果。

• 是否正确考虑文件权限配置
  不修改用户文件权限；外部 YAML 和 Handler 目录权限由用户负责。

• 是否充分考虑接口的异常场景
  已覆盖配置解析、目录扫描、文件缺失、模块执行、Handler 构造、共享内存及插件初始化异常。

• 是否正确记录错误日志
  配置、Handler 和插件初始化失败均记录明确错误及异常堆栈。

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

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

5. 变更知会

• 资料修改：
  已更新：

  • ms_service_metric/README.md
  • docs/design/ms_service_metric_Refactor_Design.md

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

6. 冒烟修改

• PR 来源：

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

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

• 是否需要添加冒烟：