oodle-o11y-review

Oodle Telemetry Review — 左侧可观测性

以资深 SRE 审查 PR 的判断力，审查代码变更中的遥测数据。这项技能不教授如何添加插桩——现代 Agent 已经了解相关 SDK。它运用那些容易被忽略的判断：发出的遥测数据是否携带正确的业务上下文且基数合适，是否避免重复，是否覆盖重要的故障模式，以及是否足以排查当前已保护这段代码的告警。

审查差异，而不是整个仓库。审查结果会记录在 O11y Change Context 清单中，以便后续分诊时使用。具体修复会交由现有的 Oodle 技能处理，而不是在这里重复说明。

适用场景

• 审查或编写新增或修改指标、跨度或日志的变更。
• PR 涉及已添加插桩的代码，或涉及会传递请求上下文（租户／账户／用户）或执行可测量工作的服务代码（I/O、循环、池）。

仅涉及文档或外观的变更可跳过遥测审查。

后端发现（首先执行）

根据功能和工具形态判断可访问的可观测性后端，切勿使用硬编码的服务名称（名称各不相同：oodle-ai-us1、ap1、staging、dev 或客户自定义名称）。

1. 查找提供指标／告警／日志／追踪查询工具的可观测性 MCP。优先根据工具功能发现工具（例如“查找监控项”“查询指标”“搜索追踪”），而不是依赖固定前缀。
2. 如果工具套件符合 Oodle 的形态（监控项、PromQL 查询、日志、追踪，以及 load_skill__* 工作流），则使用 Oodle 紧凑路径：选择负责受影响服务的环境，并在适用时加载匹配的 load_skill__*。
3. 如果存在其他供应商的可观测性 MCP，则使用其对应工具。
4. 如果无法访问任何可观测性后端，则运行检查 1–3（这些检查仅基于差异，属于静态检查），并明确报告检查 4 的能力受限——不要悄悄跳过。

检查 1 — 业务上下文与基数放置

如果请求上下文包含身份信息（租户、账户、用户、组织），这些信息必须体现在遥测数据中，并根据基数放置：

• 低基数 → 指标标签。 仅使用有界集合：路由、方法、状态类别、区域、层级、队列名称。这些会增加时间序列数量。
• 高基数 → 跨度属性和日志字段。 tenant_id、account_id、user_id、order_id、request_id 应放在这里，以便增强可调试性，同时避免时间序列数量激增。
• 循环和批次必须在跨度／日志中携带迭代标识符或批次标识符（item_index、sku、batch_id），以便追溯每次迭代执行的工作。

标记：指标标签中包含高基数值（建议将其移至跨度属性或日志字段；如果该指标已上线，则交由 oodle-drop-rules 处理）；租户范围代码的遥测数据中缺少租户／账户信息。

检查 2 — 不重复遥测数据

每项新增指标、跨度或日志都必须有明确且独立的用途。如果新信号与现有信号重叠（例如，计时器重复记录直方图的数据；日志行重复陈述跨度中的内容；两个计数器测量同一事件），则应标记出来。建议移除——在清单的 telemetry 字段中记录为一条带原因的 - 行——或明确说明其独立用途，以证明保留它的合理性。

如果无法用一句话说明某个信号的用途，就不应添加该信号。

检查 3 — 性能覆盖模式

检查已修改的代码，确认是否具备能捕获性能回归的覆盖：

• RED（速率、错误、耗时）适用于请求处理程序——按路由/方法统计延迟直方图，按类别统计错误计数。
• USE（利用率、饱和度、错误）适用于资源池——DB/HTTP/线程池：活跃数与最大数、等待时间/队列深度、连接错误。
• 队列饱和度适用于异步工作——队列深度、消费者延迟、处理时间。
• 扇出 / N+1——循环中每次迭代都会执行 I/O（DB、缓存、RPC），但没有批量调用，也没有用于衡量整个循环的 span。标记此问题，并将风险记录在清单的 watch 字段中。

将已修改代码中缺失的覆盖报告为缺口；不要要求为未修改的代码添加覆盖。

检查 4 — 基于告警的审查

这是关键差异：让审查力度与生产环境实际关注的问题保持一致。

1. 从后端查明哪些告警和 SLO 保护已修改的代码 （依据变更影响的服务/路由/指标）。
2. 对受保护的代码，要求具备调试相应告警所需的遥测数据。如果延迟告警保护的路径缺少用于定位耗时位置的 span/属性，这是一个严重问题——无人能据此采取行动的告警。
3. 将保护项记录在清单的 guarded-by 字段中，并将变更标记为更高风险（涉及关键 SLO 时，将 type 提升为 critical-path）。
4. 如果受保护的故障模式存在已知盲区，将其添加到清单的 gaps 字段中，让分诊人员知道现有数据无法回答相关问题。

如果无法连接后端，请说明无法查明保护项，并建议作者手动确认。

输出规范

• 仅报告高置信度的问题。为每项标注 critical / important / minor。不要列出一长串琐碎问题—— 目标是提供有用信号，符合 Oodle 避免告警疲劳的理念。
• 将结果写入清单：根据 O11y Change Context 契约，填写或完善 telemetry 用途、guarded-by、watch 和 gaps。
• 交接具体的修复方案，而不是重复讲解：
  • 添加或调整保护性监控项 → oodle-monitors
  • 丢弃高基数/高吞吐量指标 → oodle-drop-rules
  • 从日志派生指标 → oodle-log-metrics
• 说明要更改什么以及其重要性。Agent 已经知道如何编写检测代码。