SuperAPI AI 工具集

span-convention-review

通用与其它

查看项目

更新于 10-16 05:48

技能介绍

用途:审查 SDK 仓库中涉及 OpenTelemetry tracing span 的改动,确保符合 Sentry Conventions;在 Sentry 规范未明确处,参考 OpenTelemetry Semantic Conventions。

主要能力与流程:

  1. 识别 span 变更。用 git diff main...HEAD 查找 start_span、start_child、startSpan、StartSpan、op=、set_data、set_attribute、setAttribute、SPANDATA.、OP. 等模式,以及 gen_ai.、db.、http.、cache.、queue.、messaging.、resource.、ui. 引用;无 diff 时需询问用户要审查的文件或改动。
  2. 按 op 前缀把 span 归类到 Sentry Insights 模块,如 gen_ai.(AI Agents)、db.(Queries)、http.client(Requests)、cache.(Caches)、queue.(Queues)、resource.(Assets)、app.start.(App Starts)、ui.load*(Screen Loads)、ui.interaction.*(Web Vitals),并据此确定规范 URL。
  3. 用 WebFetch 拉取对应 Sentry Convention 页面,作为主要依据;页面不足时再取 OTel 语义约定。规范需实时获取,不得硬编码。
  4. 逐 span 检查:op 是否符合模式;name/description 是否符合格式;必需属性是否齐全;推荐属性是否缺失;是否泄露敏感数据(数据库查询值需脱敏/参数化,AI 输入输出与系统指令仅显式 opt-in 时设置,HTTP 敏感 URL 参数需遮蔽,缓存键不应含原始用户标识);属性类型是否正确(复杂数据须为字符串化 JSON、布尔、数值、数组等)。
  5. 按严重级别报告:必需修复、推荐改进、备注;每项含文件与行号、违反的规范、期望值、实际值、规范来源链接。

边界处理:未知模块需标记并检查是否有新规范,无则回退到通用 OTel 约定;多模块集成需分别审查;不同 SDK 的 API 差异不影响语义审查;自动埋点 span 需确认 origin 为 auto.{category}.{integration}。

限制:资料未提供该技能的安装命令、收费方式、支持平台与具体效果数据,暂未提供。使用依赖仓库 access 与网络获取规范页。