告警 RCA 多分支诊断最佳实践

对话回放：Skill 诊断流程 ｜ InvestigationAgent 开放调查

STAROps 内置 InvestigationAgent 适合处理根因方向未知的问题。它可以从一条告警出发，动态探索指标、日志、Trace、拓扑、资源、变更和关联实体，逐步补齐证据链。对于复杂故障、多因素叠加或告警主体不清晰的场景，InvestigationAgent 的泛化调查能力是默认入口。

在生产环境中，还有一类告警已经被团队反复处理过：触发条件明确，业务语义稳定，常见错误码和处置路径已经沉淀为 Runbook。继续让 Agent 每次从开放式调查开始，会增加工具调用和证据收集成本。STAROps 支持通过 DefaultRule 和 Skill 把这类特定诊断流程放进 Agent 上下文，让 Agent 命中特定告警后按 Runbook 分支快速取数、判断和汇总。

订单创建失败率升高是本文的示例场景。一次真实线上告警通常不会同时出现大量错误码，更常见的是 1 个主导错误码加 1 个伴随错误码。示例默认使用两个经典分支：库存锁定失败和优惠价格校验失败，用它们说明如何把历史 Runbook 固化为 Agent 可执行流程。支付、幂等、数据库写入、配置缺失等分支可以作为客户后续扩展 Skill，而不是默认实验的一部分。

实际生产中，客户应根据自己的业务交易、错误码体系、ARMS/APM 接入情况和历史 Runbook 选择适合固化的告警类型。

这类 Skill 的价值，是让 Agent 在告警触发后先按错误码快速分流，再调用子 Agent 并行取数，最后合并证据并给出可审计结论。InvestigationAgent 仍然作为兜底能力，用于处理错误码缺失、分支无法覆盖、证据互相矛盾或需要跨多跳关系继续调查的场景。

适用场景

一条可落地的确定性诊断流程应满足三个条件：

1. 告警能绑定到稳定业务交易，例如 OrderCreate。
2. 失败请求能提取错误码或错误族，例如 INV_LOCK_FAIL、PROMO_PRICE_MISMATCH。
3. 每个高频错误码都能映射到一条 Runbook：查什么实体、看什么证据、什么情况下可下结论、什么情况下升级。

调查边界

推荐策略：订单创建失败率这类核心交易告警，先由特定 Skill 快速路由到已知 Runbook；固定分支无法解释时，再升级 InvestigationAgent 做跨域动态调查。

数据前提

多分支诊断依赖稳定的实体关系和错误码分布，不能靠加长自然语言描述补齐数据缺口。

如果客户已经使用 ARMS/APM，应用、接口、实例、调用拓扑、上下游依赖、Trace 等对象通常已经具备定义。此时不建议把错误码建模成新的 UModel 对象；更适合把错误码作为告警、指标、日志或 Trace span 的维度直接上报，让 Agent 在告警触发时按 error_code 聚合并路由到对应 Runbook 分支。

建议准备的数据对象：

错误码必须进入指标、日志或 Trace 属性，至少包含 error_code、order_id 或 request_id、入口渠道、应用版本、依赖服务、时间窗。涉及用户、订单和金额等敏感字段时，只保留脱敏标识和聚合统计。

如果客户没有使用 ARMS/APM，也可以通过 UModel 自行建模业务交易、应用、接口、下游依赖和证据源。STAROps 支持这种扩展方式，但建议先从最小可用关系开始：应用、接口、调用拓扑、错误码维度和关键日志/Trace 链接。

Runbook 主导阈值应由客户基于历史告警配置。建议至少包含三类条件：错误码占比阈值、绝对失败量阈值、入口/渠道/租户等适用范围。文档中的错误码名称和阈值口径用于说明设计方法，正式发布前需要替换为客户 Workspace 中的真实枚举和规则。

落地形态

告警 RCA 多分支诊断建议采用 DefaultRule + Skill 的组合，避免把全部规则写进唯一的 DefaultRule。

• DefaultRule：放在数字员工默认上下文中，定义通用原则，例如只读边界、优先识别告警主体、先看错误码分布、证据不足时升级 InvestigationAgent。
• Skill：承载特定告警类型的诊断流程，例如订单创建失败率、支付回调失败率、登录验证码失败率。一个告警 RCA 数字员工可以配置多个 Skill，后续按告警类型逐步扩展。

本实践建议把订单创建失败率多分支诊断做成一个 Guide Skill，并在 DefaultRule 中要求 Agent 命中订单失败类告警时优先加载该 Skill。其它交易类告警可以复用同一模式，按业务交易和错误码体系扩展新的 Skill。

DefaultRule 只放通用诊断原则，不承载具体 Runbook：

Guide Skill 承载具体告警类型的执行协议。以订单创建失败率为例，Skill 应包含以下契约：

诊断流程总览

订单创建失败率示例的最小诊断地图包含告警事件、业务交易、API、服务、错误码分支和证据源。

查看诊断流程图

Runbook 分支

以下错误码为示例分类，客户应替换为企业内部真实错误码和 Runbook 名称。关键点是让错误码分支足够具体，避免再次回到“应用错误率升高”的泛化诊断。

分支之间没有依赖顺序时，应并行取证。典型并行方式：

主 Agent 只在所有必要分支返回后汇总，不让单个子 Agent 直接给全局根因。

诊断报告结构

Agent 最终输出应是自然语言诊断报告。报告建议包含以下模块：

诊断示例

以下演示一次订单创建失败率告警的多分支诊断路径。

1. 告警触发：OrderCreate 失败率超过阈值，告警绑定到 POST /api/orders 和 order-service。
2. Agent 查询触发窗口和基线窗口，发现失败请求能按 error_code 聚合。
3. 错误码分布显示总失败率约 10%，其中库存锁定相关错误约 7%，优惠价格校验失败约 3%。
4. 主 Agent 并行启动库存证据 Agent、优惠证据 Agent 和变更证据 Agent。
5. 库存分支发现失败集中在少数 SKU，Trace 与日志都指向库存锁定失败；优惠分支发现少量请求携带旧价格快照。
6. 主 Agent 汇总后给出结论：库存锁定是主导分支，优惠价格校验失败是伴随分支；未登记错误码或证据冲突时升级 InvestigationAgent。

这条路径能够体现确定性诊断流程的特性：Agent 先利用历史 Runbook 快速命中错误码分支，再通过 UModel 和 UModel PaaS 精确取数，最后由 InvestigationAgent 兜底未知和冲突场景。

Guide Skill

本实践适合沉淀为 Guide Skill。Guide Skill 的职责是把订单创建失败率诊断流程固化为 Agent 的执行协议，帮助用户或数字员工稳定复用。

Guide Skill 应包含：

• 适用业务交易和告警名称。
• 错误码到 Runbook 分支的映射表。
• DefaultRule 触发条件。
• 必填输入参数和缺失信息补充策略。
• ARMS/APM 或 UModel 诊断地图构建方法。
• 子 Agent 并行取数规则。
• 每个分支必须查询的数据。
• 证据充分性标准。
• 升级 InvestigationAgent 的条件。
• 自然语言诊断报告结构与 L0 只读边界。

安装 Skill

本实践落地一份 Guide Skill，仅支持在 STAROps 运行时执行，本地 Agent 不支持。下载 tar.gz 后在 STAROps 控制台「技能管理 → 上传技能」上传。

验证方式

本实践的验证重点是 Skill 是否能比泛化调查更快命中历史 Runbook，并保持证据质量。

建议选择一条企业历史订单失败告警做对比，验证资料避免使用演练样例或模拟数据。

通过标准：

• Skill 能绑定 OrderCreate、订单 API、order-service 和关键依赖。
• Skill 能输出错误码分布，并命中至少一个已登记 Runbook 分支。
• 每个根因候选至少包含两类独立证据。
• 并行子 Agent 的结果能被主 Agent 合并为一致证据板。
• 未覆盖错误码、证据冲突或跨域问题能明确升级 InvestigationAgent。
• 两条路径结论不一致时，有差异分析和证据解释。

实施边界

• 本实践是 L0 只读诊断，不执行任何生产变更。
• Skill 只覆盖已登记错误码和 Runbook 分支。
• 错误码缺失或错误码语义不稳定时，Skill 需要先补充日志/Trace 提取规则或升级 InvestigationAgent。
• 涉及用户、订单、金额等敏感信息时，报告只展示脱敏标识和聚合统计。
• 修复建议需要人工确认后执行；涉及写入 SQL、配置、发布、重启、扩缩容等动作时应进入客户自己的变更流程。

相关入口

• 返回 STAROps 最佳实践首页
• 打开 STAROps Playground
• 进入 STAROps 控制台