# Byted Volcengine Rootcause Analyzer > 当监控平台、日志平台、值班对话或变更后异常暴露出某个资源、域名、IP 或业务现象时，围绕告警目标自动展开上下游拓扑，检查同一拓扑内的关联异常并归并根告警、派生告警和噪声告警，输出根因候选、影响范围和结构化诊断摘要。 - Skill: `bytedance/byted-volcengine-rootcause-analyzer` (Agent Skill) - Install (CLI): `npx skillmds@latest add bytedance/byted-volcengine-rootcause-analyzer` - Raw SKILL.md: https://api.skillmd.com/api/skills/bytedance/byted-volcengine-rootcause-analyzer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: bytedance (https://skillmd.com/u/bytedance) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/bytedance/byted-volcengine-rootcause-analyzer --- # 告警根因定位与归并 Skill ## 能力定位 这个 Skill 是一个**面向故障场景的编排层**。它不把告警当作一条孤立事件处理，而是把告警、资源拓扑、同时间窗异常和运行时证据拼成一个完整的故障上下文。 它的职责是： - 从告警文本、现象描述或值班对话中提取实例、域名、IP、产品类型、指标和时间窗 - 围绕目标资源自动展开上下游拓扑，形成当前故障上下文 - 检查同一拓扑内其他资源是否存在关联异常 - 区分根告警、派生告警和噪声告警，避免把一组相关告警分散处理 - 汇总拓扑事实、运行时状态、监控证据和 API 补数结果，给出根因候选排序 - 输出影响范围、优先处理节点、建议修复动作和可升级交接的结构化摘要 这个 Skill 的目标不是“解释某一条告警”，而是把**分散异常收敛成一条业务链路问题**，尽快逼近真正的故障源头。 ## 当前边界 当前版本重点覆盖以下能力： - 告警解析 - 资源识别 - 拓扑展开 - 同拓扑异常归并 - 根因候选排序 - 结构化故障摘要输出 以下能力可以作为未来扩展输入，但**当前不是必须步骤，也不能假设一定可用**： - 近期变更 - 历史故障案例 - 知识库经验 - 授权执行预案并验证恢复 一句话区分： - `byted-volcengine-rootcause-analyzer`：负责把“告警 + 拓扑 + 异常归并 + 证据”串成诊断结论 - 它不是统一告警平台，不是资源管理中心本体，也不是自动执行平台 ## 依赖 Skill 及关系 这个 Skill 依赖以下四个已有 Skill： ### 1. `byted-volcengine-topology-builder` 职责： - 采集火山引擎账号资产快照 - 构建 `topology.json`、`topology.md`、图文件等基础拓扑数据 边界： - 只负责“把资源关系建出来” - 不负责解释告警，不负责给出根因结论 适合什么时候调用： - 当前没有覆盖目标资源的拓扑 - 已有拓扑过旧或缺失关键节点 - 需要从实例、监听器、EIP、VPC、安全组等资源补齐链路 ### 2. `byted-volcengine-topology-analyzer` 职责： - 基于已有拓扑定位目标节点 - 展开直接上下游、入口链路和受影响资源 - 给出静态影响面分析 边界： - 只消费静态拓扑，不等于实时健康状态 - 不负责直接查询监控时序或 API 详情 适合什么时候调用： - 已识别出主告警资源或候选资源 - 需要判断“这个资源在整条链路里影响谁、被谁依赖” ### 3. `byted-volcengine-cloudmonitor` 职责： - 查询目标资源的监控时序 - 验证异常是否持续、放大或同步传播 边界： - 只回答“指标怎么变” - 不能单独替代拓扑归因 适合什么时候调用： - 需要确认告警是否仍持续 - 需要验证同拓扑内多个资源是否在同时间窗同步异常 - 需要区分瞬时抖动与持续故障 ### 4. `byted-volcengine-api-assistant` 职责： - 识别产品 `ServiceCode` - 搜索可用 OpenAPI - 查询资源详情、配置和映射关系 边界： - 它是补数能力，不是拓扑分析引擎 - 只在 OpenAPI 能力范围内工作 适合什么时候调用： - 从告警文本无法直接判断资源类型 - 拓扑里缺少监听器、后端组、实例、转发规则映射 - 需要补充产品配置、绑定关系、健康检查详情 ## 何时触发 当出现以下场景时，应主动触发这个 Skill： - 监控平台产生单点告警 - 监控平台出现告警风暴，需要判断是否属于同一条链路问题 - 值班人员在会话中提交“某业务不可用”“某域名报错”“某接口超时”等现象 - 变更后短时间内出现可用性或性能异常 - 用户希望知道一组告警里哪条更接近根因、哪些只是派生结果 即使用户没有明确说“拓扑”或“告警归并”，只要问题本质是**围绕一个故障现象收敛上下游异常并定位真正根因**，就应该触发。 ## 输入信息 优先从告警文本、日志摘录或自由描述中提取以下字段： - 账号 - 告警策略 - 地域中文名 - 地域对应 Region ID - 告警级别 - 项目 - 告警时间 - 时间窗 - 云产品 - 资源 ID - 实例 ID - 监听器 ID - 域名 - IP - 当前值 - 指标名称 - 业务现象描述 - 同一会话中出现的多条相关告警 如果文本里没有显式字段，也要继续识别： - 产品别名 - 资源层级关键词 - 健康检查、连接数、状态码、超时、探活失败等指标语义 - 入口层、转发层、计算层、网络层等上下文词 如果缺少资源 ID，也允许从域名、IP 或现象描述反推候选资源，但最终回答必须显式标记不确定性。 ## 标准执行流程 ### 第 1 步：结构化输入 先把原始输入整理为结构化对象，例如： ```json { "account": "xx", "policy_name": "xx", "region_name": "华北2（北京）", "region_id": "cn-beijing", "severity": "严重", "project": "mysite", "alarm_time": "2026-05-09 17:26:11", "time_window": "alarm_time +/- 15m", "product": "clb", "resource_id": "clb-xxx", "instance_id": "", "listener_id": "lsn-xxx", "domain": "", "ip": "", "metric_name": "监听器/后端服务器异常个数", "current_value": "AVG(xxx)[1m]:1Count", "symptom": "", "related_alerts": [] } ``` 如果某些字段缺失，要显式标记为“缺失信息”，不要自行脑补。 ### 第 2 步：识别主告警节点 先判断这次故障的主起点更接近哪一层： - 入口层：`domain`、`eip`、`clb`、`alb`、`listener` - 转发层：`rule`、`server_group` - 计算层：`ecs` - 网络层：`security_group`、`subnet`、`vpc` - 其他产品层：需要借助 API 进一步确认 判断原则： - 告警中如果同时出现 `资源 ID`、`实例 ID`、`监听器 ID`，要区分“告警对象”和“潜在根因对象” - 域名、入口告警通常只是入口层信号，不应直接等同于最终根因 - 如果是负载均衡类告警，必须继续追溯监听器、后端组和实例 ### 第 3 步：获取故障拓扑上下文 围绕主告警节点获取上下游拓扑。优先级如下： 1. 优先使用工作区中已存在且可复用的拓扑数据 2. 如果现有拓扑不覆盖目标资源，调用 `byted-volcengine-topology-builder` 3. 使用 `byted-volcengine-topology-analyzer` 展开目标节点的上下游、入口链路和受影响资源 这一步的目标不是“画图展示”，而是为后续做告警归并建立一个可分析的故障上下文。 ### 第 4 步：检查同拓扑内的关联异常 在已展开的拓扑范围内，检查同一时间窗内其他资源是否也有异常信号。 异常来源可以包括： - 当前会话中提供的多条告警 - 同一资源链路上的其他监控指标 - 通过 `byted-volcengine-cloudmonitor` 查询到的同步异常 - 通过 API 补数拿到的异常状态字段 如果当前无法直接查询告警平台，则应退化为： - 分析会话中已有的告警集合 - 分析当前主资源和上下游的实时状态 - 明确说明“当前无法完整拉取同时间窗所有告警” ### 第 5 步：归并告警并分类 拿到同拓扑异常后，至少要分成三类： - `root_alert`：更接近链路收敛点，且能解释其他异常传播的告警 - `derived_alert`：由根问题向上游或下游传播形成的派生告警 - `noise_alert`：与当前主链路弱相关、证据不足或无法证明同源的告警 归并原则： - 优先找多条异常路径最终汇聚的节点或资源层 - 优先找既有拓扑解释力、又有运行时异常证据的节点 - 不把单纯时间接近但链路无关的告警强行归为一组 ### 第 6 步：按需补数和验证 当出现以下情况时，按需使用补充能力： - 拓扑里有节点但关系不完整：调用 `byted-volcengine-api-assistant` - 需要确认异常是否仍持续或是否同步放大：调用 `byted-volcengine-cloudmonitor` - 无法从域名、IP 直接映射到资源：优先使用拓扑和 API 反推 使用原则： - API 和监控是补证据，不替代拓扑上下文 - 没有证据时不要假装“已经归并完成” - 归并失败时宁可保守，也不要把噪声告警误判为同根因 ### 第 7 步：形成根因候选排序 综合以下证据后，再给出根因候选： - 告警原文事实 - 拓扑中的位置与上下游关系 - 同拓扑内异常的聚集情况 - API 补数得到的资源详情和绑定关系 - 监控时序中的同步异常或持续异常 最终至少要回答： - 哪个资源是本次故障分析的主节点 - 哪些告警被归并到同一问题 - 哪个节点最可能是根因，哪个只是传播结果 - 当前影响范围是什么 - 应优先处理哪个节点 ## 根因判断原则 ### 1. 不把最早出现的告警直接等同于根因 最早触发的告警不一定最接近故障源头，可能只是更敏感的入口信号。 ### 2. 优先找链路收敛点 如果多条异常路径最终都汇聚到同一个资源、同一层组件或同一个资源组，应优先把它列为高置信候选根因。 ### 3. 区分“原因”和“传播结果” 例如： - 上游域名报错可能只是结果 - 入口负载均衡健康检查异常可能只是中间信号 - 某个后端实例、服务器组或网络边界异常更可能接近真正根因 ### 4. 告警归并必须有证据 至少满足以下一项，才能高置信归并： - 拓扑上存在明确依赖关系 - 同一时间窗出现同步异常 - API 或监控状态能互相印证 ### 5. 根因候选必须带置信度 建议按以下级别表达： - `confirmed`：有明确链路和运行时证据支撑 - `high`：拓扑与监控高度一致，但仍缺少少量细节 - `medium`：链路可达，但证据不够完整 - `low`：只能定位到某一层，无法确认唯一节点 ## 回答结构 输出时优先使用以下结构： ```markdown 结论： - 当前最可能的根因候选是 ... - 置信度是 ... - 当前优先处理节点是 ... 告警归并结果： - 主告警: ... - 已归并的派生告警: ... - 识别为噪声的告警: ... 拓扑与影响： - 故障入口: ... - 中间链路: ... - 下游关键资源: ... - 当前影响范围: ... 根因候选排序： - 候选 1: ... | 证据: ... - 候选 2: ... | 证据: ... - 候选 3: ... | 证据: ... 事实 / 推断 / 待确认： - 已确认事实: ... - 高置信推断: ... - 待确认项: ... 建议动作： - 先处理 ... - 再验证 ... - 如需升级，交接摘要如下 ... ``` ## 预期产出 使用这个 Skill 时，最终输出应尽量覆盖以下内容： - 根因候选排序与证据链 - 告警归并结果与影响拓扑视图 - 当前故障影响范围、优先处理节点和建议修复动作 - 可用于升级交接的结构化诊断摘要 ## 结构化诊断摘要要求 如果用户需要快速升级或交接，至少应给出： - 故障标题 - 主要受影响业务或入口 - 当前主根因候选 - 已归并告警数量 - 当前影响范围 - 优先处理节点 - 已验证证据 - 待确认项 - 下一步建议动作 ## 排查建议生成规则 排查建议至少覆盖三类内容： ### 1. 立即核查项 - 当前主根因候选是否仍持续异常 - 同拓扑内是否仍有更多资源同步异常 - 优先处理节点是否已经出现健康检查失败、状态异常或容量下降 ### 2. 链路核查项 - 上游入口是否仍可达 - 中间转发、监听器、后端组或实例绑定关系是否异常 - 是否存在链路单点或冗余失效 ### 3. 止血与交接项 - 是否可以绕过当前疑似故障节点 - 是否可以临时摘除异常节点或回切备用入口 - 如需升级，先交接主根因候选、影响范围和已验证证据 ## 失败回退策略 ### 情况 1：无法识别产品或资源 处理方式： - 先从域名、IP、资源 ID、实例 ID 中反推候选资源 - 再调用 `byted-volcengine-api-assistant` 补产品与接口信息 - 若仍无法确认，明确标注“当前无法唯一定位资源类型” ### 情况 2：拓扑缺失或命中失败 处理方式： - 调用 `byted-volcengine-topology-builder` 重新构建 - 若仍无命中，说明当前拓扑未覆盖目标资源 - 不要硬编上下游，直接说明链路证据不足 ### 情况 3：无法完整拉取同时间窗告警 处理方式： - 回退到会话中已有告警和当前实时证据做局部归并 - 明确说明“当前无法完整获取同时间窗所有告警，归并结果可能不完整” ### 情况 4：监控或 API 补数失败 处理方式： - 回退到已有拓扑和原始告警文本做保守判断 - 明确说明缺失的是哪类动态证据 - 下调根因候选的置信度 ## 不适用场景 以下场景不要把这个 Skill 当成完整解决方案： - 用户只想单独查一个监控指标 - 用户只想查询某个产品支持哪些 OpenAPI - 用户只想构图，不关心告警归并和根因定位 - 缺少账号权限，导致拓扑、监控、API 都无法查询 - 用户明确要求执行预案，但当前未进入授权模式且没有自动执行能力 ## 示例场景 ```text 监控平台连续产生多条告警： - 域名 5xx 升高 - CLB 监听器后端异常个数 > 0 - 单台 ECS 探活失败 值班人员在群里补充： - mysite 首页访问报错 - 发生时间与告警时间一致 ``` 建议处理顺序： 1. 先提取域名、入口资源、实例 ID、监听器 ID 和时间窗 2. 围绕主资源展开上下游拓扑 3. 检查同拓扑内是否存在同步异常 4. 区分根告警、派生告警和噪声告警 5. 对最可能的根因候选排序 6. 输出影响范围、优先处理节点和结构化诊断摘要 ## 最终回答约束 使用这个 Skill 时，最终回答必须遵守以下约束： - 先给结论，再给证据 - 明确区分“事实 / 推断 / 待确认” - 不虚构业务名、域名、服务名 - 不把静态拓扑推断说成实时事实 - 不把时间接近但链路无关的告警强行归并 - 如果归并范围不完整，要明确承认边界