signoz-investigating-alerts

告警调查

诊断 SigNoz 告警触发的原因。此技能会将告警自身的信号与触发时间窗口附近的信号进行关联，并按可能性排序列出原因，同时提供支持证据。它是 signoz-explaining-alerts 的配套技能：explain 会静态解读规则；investigate 则会诊断具体事件。

前提条件

此技能会大量调用 SigNoz MCP 服务工具（signoz_get_alert、signoz_get_alert_history、signoz_execute_builder_query、signoz_query_metrics、signoz_search_traces、signoz_search_logs、signoz_get_trace_details 等）。运行工作流之前，请确认 signoz_* 工具可用。如果不可用，则表示 SigNoz MCP 服务尚未安装或配置；请先运行 signoz-mcp-setup，以初始化或修复 MCP 连接。

适用场景

用户希望进行以下操作时，请使用此技能：

• 了解特定告警触发的原因。
• 找出近期由告警触发的事件的根本原因。
• 将告警信号与相关指标、追踪和日志关联起来。
• 区分由“真实信号”触发的告警与抖动或阈值设置不当的告警。

用户希望进行以下操作时，请勿使用此技能：

• 了解告警配置监控的内容 → signoz-explaining-alerts。
• 创建新告警 → signoz-creating-alerts。
• 修改告警（提高阈值、添加迟滞）→ 直接调用 signoz_update_alert。
• 在没有告警作为切入点的情况下进行自由形式的临时调查 → signoz-generating-queries。

必需输入

输入	必需	缺失时的来源
告警标识符（规则 ID 或名称）	是	$ARGUMENTS[0] 或近期上下文
时间窗口	否	默认使用 signoz_get_alert_history 返回的最近一次触发时间

如果告警名称不明确，此技能将尽力处理（只读）：

1. 调用 signoz_list_alert_rules，逐页获取结果，并对名称进行模糊匹配。
2. 说明所采用的解释：“正在调查 UTC 时间 14:32 触发的 ‘High Error Rate - Checkout’（ID 42）。如果你指的是其他告警或触发事件，请告诉我。”
3. 继续调查。

如果在查询的回溯窗口内，完整历史记录（已获取所有分页，且没有调用失败）中没有触发状态转换，请停止：没有可供调查的触发时间窗口。请回复：

“过去 7d 内未返回告警 ‘[name]’ 的触发事件，因此没有可供调查的触发时间窗口。请使用 signoz-explaining-alerts 逐步了解规则，或检查告警是否已启用。”

切勿将此简写为“尚未触发”：保留期限或使用新 ID 重新创建规则，都可能导致完整历史记录为空。如果历史记录调用失败或分页提前停止，请说明无法完整读取历史记录。分别报告触发历史、当前 state、disabled 和投递情况（没有告警工具会返回此信息）。

工作流

调查分为三个层级，并设有严格的提前停止关卡。 始终运行第 1 层。只有第 1 层确认确实发生了触发，才运行第 2 层。 只有第 2 层发现相关异常，才运行第 3 层。跳过这些关卡，会对没有异常的告警执行数百次不必要的追踪/日志查询。

步骤 1：解析告警和触发窗口（Tier 0）

1. 如果未提供告警 ID，通过 signoz_list_alert_rules（分页）解析。
2. 调用 signoz_get_alert 获取完整规则配置，以了解该告警评估的查询、阈值和资源范围。
3. 首先调用 signoz_get_alert_history，设置 timeRange: "7d" 和 order: "desc"；省略 state，以便时间线包含触发和非活动状态的转换。只有在存在 data.nextCursor 时才继续（完整性说明中也会报告 hasMore: true）。将其作为 cursor 传入，用说明中的解析后绝对时间 start 和 end 替换 timeRange，并保留相同的状态/筛选条件（包括省略该参数）和排序。若不存在 nextCursor / 说明报告 hasMore: false，则停止；绝不要使用 offset 或页面是否已满作为判断依据。如果之后有意使用状态筛选“resolved” / “recovered”，请使用 inactive。枚举值为 inactive|pending|recovering|firing|nodata|disabled；recovering 是一种暂时的持续触发状态，并不代表已解决。 模式分析需要完整的状态转换集合。每行按标签组 fingerprint 输出；不要将不同组的行交错排列。根据响应：
   • 构建规则级事件窗口：根据 overallStateChanged: true 的不同记录构建：overallState: "firing" 转换表示事件开始；之后的 overallState: "inactive" 表示事件结束。对匹配的时间戳去重，并按 unixMilli 升序排序后再配对。默认选择最近的事件，除非 $ARGUMENTS[1] 指定其他事件。
   • 按 fingerprint 划分受影响的序列，并保留每行的标签。仅使用 stateChanged: true 的记录来判断该组何时触发和解决，以及确定哪个组应作为 Tier 1–3 查询的范围。
   • 根据规则级状态转换或某个具名 fingerprint 记录触发模式：
     • one-off → 单次触发，前后都有较长的平静期。
     • sustained → 持续触发时间达到或超过 1 个评估周期。
     • flapping → 在 1 小时窗口内触发至少 3 次，并在触发/解决状态间交替。
     • recurring → 按固定间隔触发（类似 cron，例如每小时一次）。
   • 绝不要根据不同的 fingerprint 推断为 flapping。该模式用于指导第 2/3 层分析。

步骤 2：Tier 1（触发情况与触发程度）

此层级始终运行。它用于确认触发是真实的（而非短暂越过阈值或抖动），并量化触发幅度。

1. 在以触发开始时间为中心的时间窗口内重新运行告警的主查询：[fire_start - 30m, fire_start + 30m]。
   • 对告警已保存的构建器、公式、PromQL 或 ClickHouse 查询封装，使用 signoz_execute_builder_query。
   • 按原样重现已保存的查询。如果规则在分组查询中带有 limit 和 order，本次运行也要保留：评估的只是它们选出的前 N 个时间序列（按整个时间窗口排序），因此重现时必须使用相同的子集。将该上限记录为一项发现：排名在前 N 之外的违规分组从未被评估；按降序排列的 below 规则可能会排除所有违规时间序列。建议的修复方式是更新规则，移除 limit/order，除非原本就是要对前 N 项触发告警。
   • 如果已保存的查询没有边界条件，告警评估了所有时间序列，但 signoz_execute_builder_query 仍会应用自身的显示 limit。要检查步骤 1 中的特定指纹，应将其标签添加到筛选条件中，而不是提高 limit；要对分组排序，应使用 v5 order（指标/公式使用 __result desc，日志/追踪使用主聚合降序），绝不能使用仪表板 orderBy；如果返回的分组数量恰好等于 limit，请明确说明。
2. 计算：
   • 峰值：触发窗口内的峰值。
   • 阈值超限幅度：对于 “above” 告警，计算 (peak - threshold) / threshold * 100；对于 “below” 告警，则反向计算。
   • 触发时长：规则从触发到停止触发的总时长；如果调查范围限定为某个分组，则使用所选指纹的时长。请说明使用的是哪一种。
   • 触发前基线：触发开始前 30 分钟内的平均值。
3. 提前停止条件：如果超限幅度 < 阈值的 10%，且触发时长 < 1 个评估窗口，则归类为“临界触发”；该告警可能过于敏感。跳过 Tier 2 和 Tier 3，转到步骤 5，并仅提出一个假设：“阈值可能过紧，建议调整”。

步骤 3：Tier 2（相邻信号与基线对比）

仅在 Tier 1 确认存在真实违规时运行。提取与告警资源范围相同的相关信号，并将触发窗口与基线窗口进行比较。

1. 选择基线窗口。使用前一天的同一时段（fire_start - 24h, fire_start - 24h + fire_duration）。如果告警在已知异常时段（部署、每周任务）触发，请在输出中注明，但仍要继续分析。

2. 查找相邻信号，依据告警的资源类型进行选择。请参阅 references/neighbor-signals.md 中的查找表。常见情况：

   • 服务级告警（service.name = X）：提取错误率、p95/p99 延迟、请求吞吐量；如果有追踪数据，还要提取依赖项错误率。
   • 主机 / VM 告警（host.name = X）：CPU、内存、磁盘 I/O、网络 I/O。
   • K8s Pod / 命名空间告警：Pod 重启次数、容器 CPU/内存限制、节点压力、近期滚动发布。

3. 对每个相邻信号：

   • 使用 signoz_execute_builder_query 或 signoz_query_metrics 查询两个窗口（触发窗口 + 基线窗口）。
   • 计算变化幅度（触发窗口相对于基线的变化百分比）。
   • 按绝对变化幅度排序。

4. 提前停止条件：如果没有任何相邻信号相对于基线偏离 ≥ 25%，则归类为“孤立触发：告警自身的信号发生了变化，但其他信号没有变化”。这种情况并不常见，值得特别指出。跳过 Tier 3，转到步骤 5，并围绕告警自身的查询提出假设（可能原因：数据源变更、插桩变更、仅在该指标中显现的下游静默故障）。

第 4 步：第 3 层（故障窗口的追踪和日志）

仅当第 2 层发现相关的邻近异常时才运行。深入检查具体的失败操作。

1. 追踪（如果告警针对特定服务且有可用追踪数据）：

   • 使用故障窗口调用 signoz_search_traces，筛选条件为： service.name = <scope> AND has_error = true。最多返回前 20 条。
   • 按 name 和 status_message 分组。列出样本中排名前 3 的结果，每项附一个追踪 ID；不要把 20 条样本的计数当作整个窗口的频次。
   • 可选择调用 signoz_get_trace_details 获取 span 属性。将搜索结果行中的 trace_id 作为 traceId 传入，并传入相同的绝对故障窗口 start 和 end；否则默认的 6h 时间范围会遗漏较早的事件。

2. 日志（故障窗口）：

   • 使用筛选条件 <scope_filter> AND severity_text IN ('ERROR', 'FATAL') 调用 signoz_search_logs。最多返回最近的前 20 条。
   • 按 body 模式（或存在时按 exception.type）分组。列出样本中排名前 3 的不同消息及其计数。

3. 交叉比对：追踪和日志是否指向同一个下游服务、依赖项或代码路径？如果是，这就是首要假设。

请参阅 references/baseline-comparison.md，其中提供了可将故障窗口和基线窗口调用清晰配对的查询模板。

第 5 步：构建结构化输出

严格按照以下顺序组织内容。开头先给出 TL;DR，因为承受压力的工程师会先浏览顶部，找到所需信息后就停止阅读。每项结论都要引用得出该结论的 MCP 查询，不要加入泛泛的“检查日志 / 验证连接”之类的填充内容。

1. TL;DR：最多一到两句话。给出首要假设、总体置信度、影响范围，以及最有用的一项后续操作。例如：

“checkoutservice 的错误率在 14:32 UTC 达到 12.4%（阈值为 5%），持续 8 分钟；最可能的原因是 payments-api 超时（高置信度）。打开跟踪 7af3a09b… 查看失败调用。”

2. 触发情况 告警（ID、名称）、触发时间窗口（UTC 绝对时间 + 相对时间）、峰值幅度（“错误率达到 12.4%，阈值为 5%，超出 148%”）、触发持续时间，以及触发模式（one-off / sustained / flapping / recurring / marginal）。

3. 调查过程 用便于浏览的列表说明检查了哪些内容；已确认的信号前加 ✅，已排除的前加 ❌，每项后跟一行调查结果；失败或超时的查询应标记为“未检查”，并注明错误。目的是让读者了解 AI 做了哪些调查，以及发现了什么。 例如：

• ✅ Tier 1：峰值错误率为 12.4%，告警确实触发（并非临界触发）。
• ✅ Tier 2：payments 错误率 +8900%，p99 +1180%；存在下游级联。
• ❌ CPU / 内存压力：在触发时间窗口内保持平稳。
• ✅ Tier 3：30 条错误跟踪都指向 payments-api，且错误消息相同。

4. 可能的原因（按可能性排序，最多 3 项） 每项原因包含以下三部分：

• 假设：用一句话具体说明。不佳：“服务状态不佳”。较佳：“checkout 调用 payments-api 时发生超时”。
• 证据：给出来自 Tier 1/2/3 的支持数据，并附上底层查询，方便用户重新运行。说明相邻信号、相对基线的变化幅度，以及支持该判断的跟踪 / 日志模式。
• 置信度：high 要求以下信号中至少满足 2 项：时间先后关系、拓扑 / 依赖边、共享服务或实体、相关指标 / 日志 / 跟踪证据、近期部署或配置变更。medium 表示有一个 Tier 的证据，且至少有上述一项信号。low 表示只有单一信号发生变化，且没有佐证；此时应将其标记为“同时出现的信号”，而非原因。

如果只运行了 Tier 1（告警临界触发 / 没有相邻异常），则减少假设数量，使用 low 置信度，并明确指出这一限制。

5. 已排除的原因 简明但明确地列出证据排除的候选原因及排除理由。若没有值得排除的内容，则跳过此部分；但如果考虑过某个原因后又排除了，就在这里说明，避免用户浪费时间重新检查。

6. 建议的后续步骤 列出用户可以采取的行动。内容要具体，并使用 SigNoz 原生操作入口，让用户可以立即执行：

• 指明要打开的跟踪、仪表板或告警 （例如：“在 SigNoz UI 中打开跟踪 7af3a09b…”）。
• 指明要通过 signoz-generating-queries 运行的具体查询：粘贴确切的过滤条件和时间窗口。
• 如果触发属于临界触发，建议“调整此告警”：指出字段（matchType、target、recoveryTarget）以及要通过 signoz_update_alert 做出的更改。
• 如果原因涉及多个服务，建议“创建事件”或“通知负责团队”。

将建议镜像为导航快捷项。 将“建议的后续步骤”中最多 3 项转为宿主环境中的后续操作意图：优先选择最可执行且与告警直接相关的操作。其余内容保留在报告正文中，以便用户了解全貌。快捷项数量有限；正文不受此限制。

不在范围内（v1）

• 部署／配置变更关联：SigNoz MCP 不提供部署工具；不要虚构此类工具。如果用户提到最近有部署，请将其作为背景信息，但没有信号证据时，不要声称部署导致了故障。
• 跨服务影响范围追踪：调查告警所涉及服务的下游调用方。为控制上下文范围，此项不在支持范围内。
• 长期历史基线：第 2 层只会与前一天的一个时间窗口进行比较，不会分析每周／每月的季节性规律。如果用户问“周五下午出现这种情况正常吗”，建议使用异常告警（signoz-creating-alerts 中的 anomaly_rule）。

防护措施

• 必须执行三层提前停止机制。 跳过这些关卡会在告警较平静时拉取数百条跟踪记录／日志，导致上下文急剧膨胀。这些关卡并非可选的优化措施。
• 每项结论都必须有 MCP 查询结果作为依据。 不要推测。缺少证据时，应降低置信度并如实说明。
• 读取失败或不完整不能排除任何情况。 查询出错或超时都表示“尚未检查”。有数量上限的跟踪记录或日志样本，只能支持针对样本行的结论；要判断窗口内“没有”“全部”或总数，必须有完整结果。
• 为每个假设展示支持它的查询，以便用户复现并深入调查。
• 简短且以证据为依据。 TL;DR 最多一到两句话；完整报告应是一张分诊卡片，而不是事后复盘。承受压力的工程师应能快速浏览要点并采取行动。每个章节都必须提供用户无法直接从告警负载中看到的证据，才值得保留。
• 相关性 ≠ 因果关系。 只有以下至少两项相互吻合时，才能将某项因素标记为原因：时间先后关系（信号在症状出现前发生变化）、拓扑／依赖关系边、共享服务或实体、相关的指标／日志／跟踪证据，或近期部署／配置变更。单个时间吻合的异常只是“同时发生的信号”，不是原因；请明确说明。
• 不要复述告警，也不要给出显而易见的建议。 “检查日志”“验证连通性”“调查仪表板”等建议没有帮助，因为阅读此输出的人已经知道需要做这些事。请改用具体的查询、跟踪记录或筛选条件，让他们可以立即运行。
• 不得虚构标识符。 跟踪 ID、span 名称、告警规则 ID、频道名称、部署 ID：输出中的每个标识符都必须来自真实的 MCP 响应。不要编造看似合理的占位符。
• 如实说明不确定性。 如果没有任何假设达到中等置信度，答案应为“未找到明确的根本原因；以下是我们检查过的内容及已排除的情况。”不要为了显得有帮助，就把低置信度猜测提升为首要假设。误报比漏报更浪费正在处理事件的时间。
• 在每个深入调查查询中优先使用资源属性筛选条件。 这是 SigNoz MCP 的指南，而且会直接影响大规模场景下的查询速度。
• 不要修改任何告警。 调查只能读取数据。如果用户说“顺便收紧此告警”，请将其列为后续建议；不要调用 signoz_update_alert。
• 遵守范围。 静态规则说明属于 signoz-explaining-alerts。没有告警锚点的原因分析属于 signoz-generating-queries。
• 时区。 始终在相对时间旁标明 UTC 时间的故障窗口（“14:32 UTC，2 小时前”），以确保自主和交互式使用方对时间窗口的理解一致。

示例

用户：“结账错误率告警为什么触发？” Agent：

1. 解析告警："High Error Rate - Checkout"（id 42）。

2. signoz_get_alert_history → 最近一次触发发生在 2h 前的 14:32 UTC， 持续了 8m，单次触发（并非反复触发）。

3. 第 1 层：在 [14:02, 15:02] 时间范围内重新运行错误率公式。峰值 错误率为 12.4%（阈值为 5%，超出 148%）。触发前基线 为 0.3%。这是真实触发，并非临界情况。

4. 第 2 层：提取 service.name = checkout 的相邻信号：

   • p99 延迟：4.1s，基线为 320ms（+1180%）。
   • 吞吐量：−42%（下降）。
   • 下游 payments 错误率：18%，基线为 0.2%（+8900%）。
   • CPU/内存：平稳（没有资源压力）。

5. 第 3 层：触发时间范围内 service.name = checkout, has_error = true 的跟踪：最高频操作为 POST /checkout/submit，最高频 错误消息为 "context deadline exceeded calling payments-api"。 抽样的 20 条错误跟踪全部命中同一个下游 URL；抽样的 20 条错误日志中有 17 条显示 "payments client timeout"。

6. 输出：

   简要总结：checkoutservice 错误率在 14:32 UTC 达到 12.4%（阈值为 5%）， 持续了 8m。最可能的原因：payments-api 超时 （置信度高；跟踪、日志和相邻信号的证据相互印证）。 打开跟踪 7af3a09b… 查看失败的调用。

   • 触发情况：告警 42 于 2h 前的 14:32 UTC 触发，持续 8m。错误率峰值为 12.4%（超出阈值 148%）。
   • 调查过程：
     • ✅ 第 1 层：峰值为 12.4%，阈值为 5%，触发前基线为 0.3%。 确属真实触发。
     • ✅ 第 2 层：payments 错误率 +8900%，p99 延迟 +1180%， 吞吐量 −42%。
     • ❌ checkout 的 CPU/内存压力：平稳。
     • ✅ 第 3 层：抽样的 20 条错误跟踪全部命中 payments-api，并出现 context deadline exceeded；抽样的 20 条日志中有 17 条为超时。
   • 可能原因（置信度高）：payments 服务错误 级联到 checkout。拓扑结构（checkout → payments 边）、 时间先后关系（payments 错误先于 checkout p99 升高）和共享实体（每条抽样的 错误跟踪都指向 payments-api URL）方面的证据相互印证。
   • 排除的原因：checkout 侧资源压力（CPU/内存 平稳）；上游流量激增（吞吐量下降，并未 激增）。
   • 后续步骤：在 SigNoz UI 中打开跟踪 7af3a09b…；如果 payments 有自己的告警，就对其运行 signoz-explaining-alerts； 否则，运行 signoz-generating-queries 查询过去 4h 的 payments 错误 率。

---

用户：“调查 prod-api-3 上反复触发的 CPU 告警”

Agent：

1. 解析告警（id 88，host.name = prod-api-3）。

2. 历史记录：过去 1h 内触发了 7 次，每隔 8–12 分钟便交替触发/恢复一次，呈反复触发模式。

3. 第 1 层：峰值为 84%（阈值为 80%，仅超出 5%）。每次触发 持续 2–4 分钟。属于临界情况：数值徘徊在阈值附近。 matchType = at_least_once 导致每次短暂波动都会触发。

4. 提前停止条件生效。跳过第 2/3 层。

5. 输出：

   简要总结：告警 88 在 prod-api-3 上反复触发：过去 1h 内触发 7 次， 每次持续 2–4m，且都在 80% 阈值的 5% 范围内。 没有明确的根本原因；这是阈值调优问题，而非事故。 将 matchType 切换为 on_average，或添加滞回机制，以消除 噪声。

   • 触发情况：告警 88，主机 prod-api-3，触发模式为 flapping。过去 1 小时触发了 7 次，每次持续 2–4 分钟。峰值为 84%（比 80% 的阈值高 5%）。
   • 调查过程：
     • ✅ 第 1 级：每次触发值都在阈值的 5% 范围内；持续时间 较短；基线本来就在 70–75%。属于边缘触发；触发提前停止， 跳过第 2/3 级调查。
   • 可能原因（置信度低／仅有共现信号）：阈值设得过紧，或 matchType 过于敏感。证据： 每次触发值都在阈值的 5% 范围内；基线本来就在 70–75%。未认定为“原因”：只有单一信号，缺少佐证。
   • 排除的原因：真实的 CPU 饱和事故（峰值过低且持续时间过短；基线本来就接近阈值）。
   • 后续步骤：将 matchType 改为 on_average（平滑瞬时尖峰），或将阈值提高到 85%，并设置滞回 （recoveryTarget: 75）。使用 signoz_update_alert 应用更改。

---

用户：“调查昨晚触发的日志量告警的根因”

Agent：

1. 解析告警：“Error Log Volume Spike”（ID 14，无服务筛选条件；按 service.name 分组）。

2. 历史记录：于 03:12 UTC 触发，持续 22 分钟；告警注释中按服务细分： service.name = inventory 是触发的时间序列。

3. 第 1 级：重新查询触发时段内 inventory 的日志计数。峰值为 每分钟 3,400 条错误，阈值为每分钟 1,000 条（高出 240%）。触发前 基线为每分钟 12 条。属于真实的大幅触发。

4. 第 2 级：service.name = inventory 的相邻信号：

   • 请求错误率：+600%。
   • p99 延迟：+30%（轻微）。
   • CPU：-80%（骤降）。内存：-60%。
   • Pod 重启（k8s）：触发时段内 4 次。

5. 第 3 级：触发时段内 inventory 的日志。20 条样本中的首要消息为 “OOMKilled restarting”（14 条）。首要跟踪错误： 优雅关闭异常。

6. 输出：

   简要结论：日志量告警 14 于 03:12 UTC 触发，针对 service.name = inventory，持续 22 分钟，超过阈值 240%。 最可能的原因：inventory Pod 因 OOM 被终止并重启了 4 次 （高置信度）。请检查 inventory 部署的容器内存限制。

   • 触发情况：告警 14 于 03:12 UTC 触发，针对服务 inventory，持续 22 分钟，超过阈值 240%。
   • 调查过程：
     • ✅ 第 1 级：峰值为每分钟 3,400 条错误，阈值为每分钟 1,000 条； 触发前基线为每分钟 12 条。属于真实触发。
     • ✅ 第 2 级：请求错误率 +600%；CPU/内存骤降 （−80%/−60%）；触发时段内 Pod 重启 4 次。
     • ❌ p99 延迟：仅 +30%，并非由延迟引发的事故。
     • ✅ 第 3 级：采样日志中的首要消息为“OOMKilled restarting”（20 条中有 14 条）； 首要跟踪错误：优雅关闭异常。
   • 可能原因（高置信度）：inventory Pod 在该时段内因 OOM 被终止并重启了 4 次。证据来自拓扑（单一服务）、时间先后关系（错误激增前内存已降至零）、共享实体（所有日志行均来自 service.name = inventory）以及单一连贯模式（OOM → 重启 → 优雅关闭噪声），彼此吻合。
   • 排除的原因：上游流量激增（吞吐量未变）。尚未排除：请求路径故障（20 条采样日志中有 6 条与重启无关）；请统计重启相关日志与所有错误日志的数量，以区分两者。
   • 后续步骤：检查 inventory Pod 的容器内存限制；查看近期部署；考虑告警是否应排除与重启相关的错误模式，或真正需要关注的是底层 OOM 问题。

其他资源

• references/neighbor-signals.md：将资源类型 （service / host / k8s）映射到 Tier 2 中要拉取的邻近信号的查找表。
• references/baseline-comparison.md：用于配对调用 fire-window 和 baseline-window 的查询模板，并说明如何为两者 格式化 signoz_execute_builder_query。
• signoz-explaining-alerts 技能：如果用户不熟悉此告警监控的内容，可在调查前用于解读规则。
• signoz-generating-queries 技能：用于针对相同资源范围进行临时后续查询。