production-investigation

Honeycomb 生产问题排查

用于调试生产问题的结构化工作流。MCP 工具会说明自身参数；本技能侧重于工具调用的顺序，以及如何解读结果以找到根本原因。

核心分析循环

此工作流实现了 observability-fundamentals 技能中的核心分析循环（定义 → 可视化 → 调查 → 评估）。如果 BubbleUp 没有返回有用结果，问题通常出在埋点缺失——补充缺少的属性（参见 otel-instrumentation 技能）后再试一次。

调查工作流

第 1 步：了解情况

1. get_workspace_context → 环境和数据集
2. get_slos → 是否有 SLO 违规？（判断严重程度）
3. get_triggers → 是否有告警触发？（缩小范围）
4. find_queries → 之前是否有人调查过这个问题？

第 2 步：描述问题特征

运行宽泛查询，了解问题的表现：

• 延迟激增：按服务或路由分组，计算 P99(duration_ms)、HEATMAP(duration_ms)
• 错误激增：按服务／路由／类别统计失败操作跨度（error=true），然后单独统计使用 event.name=exception 和 exception.type exists 的异常事件行；使用采样的 trace.trace_id 值深入查看有代表性的跟踪
• 未知问题：按 service.name 分组进行 COUNT，找出流量异常的服务

还要调用 get_service_map——它会显示服务之间的 P95 持续时间，并能立即揭示哪个依赖项较慢。

异常数据有两个查询入口： 操作失败应在跨度上查询（error=true、跨度状态、低基数的 exception.slug／错误类别）；完整的异常诊断信息可能位于与跟踪相关的 Logs API 事件行中。不要假设包含异常事件的跨度上存在 exception.*。调查异常时，先发现数据集架构，再使用 event.name=exception 和 exception.type exists、trace.trace_id exists 进行查询，获取样本，然后将其 trace.trace_id 传给 get_trace(show_events=true)。对于旧版跨度事件异常，也要检查 name=exception 和 meta.signal_type=trace；Logs API 事件使用 event.name／body 和 meta.signal_type=log。

如果服务使用了可将异常提升至跨度的 LogRecordProcessor，某些 exception.* 字段也可能出现在包含该事件的跨度上。应将此视为明确的客户端兼容性功能，而不是 Honeycomb 的保证：事件行仍是完整诊断信息的权威来源；父跨度上没有字段，并不代表缺少异常事件。

第 3 步：使用 BubbleUp 找出差异因素

这是价值最高的一步。获得显示异常情况的查询后：

1. 对查询结果运行 run_bubbleup，选择离群区域
2. BubbleUp 会自动比较离群值与基线在所有列上的分布
3. 找出分布差异显著的字段

如何解读 BubbleUp 结果：

• 分类字段（维度）：离群值中占比过高的值可能指向原因（例如，deployment.version=v2.3.1 占慢请求的 90%，但在基线中只占 20%）
• 数值字段（度量）：分布偏移显示相关指标（例如，离群值中的 db.query_duration 高得多）
• 常见的根本原因：部署版本、区域、用户群组、特定端点、功能标志

第 4 步：深入查看跟踪

BubbleUp 找出可疑因素后：

1. 将 BubbleUp 的发现作为 WHERE 筛选条件，以缩小结果范围
2. 选择一个有代表性的跟踪 ID
3. 调用 get_trace 获取完整跟踪

跟踪瀑布图中需要留意的内容：

• 持续时间与父跨度相比明显过长的跨度（瓶颈）
• 可并行执行的连续跨度（N+1 查询模式）
• 错误跨度——检查跨度事件中的堆栈跟踪
• 子跨度之间的间隙（缺少埋点或空闲等待）
• 服务边界（跟踪跨越服务的位置）

步骤 5：验证假设

根据 BubbleUp 和链路分析提出假设，然后进行确认：

• 查询时包含筛选出的可疑原因
• 查询时不包含该原因（作为对照）
• 如果指标出现分歧，你就找到了问题

步骤 6：记录发现

调用 create_board，并提供：

• 一个总结根本原因的文本面板（Markdown）
• 定位问题时运行的关键查询 PK
• 相关的 SLO（如适用）

调查模式

延迟尖峰

先看 HEATMAP → 对慢速区域使用 BubbleUp → 跟踪一个慢请求 → 使用筛选后的查询进行验证

错误激增

按服务／路由／类别统计失败的操作 span → 按 event.name=exception 和 exception.type 统计 Logs API 异常事件 → 抽取 trace.trace_id → get_trace(show_events=true) → 使用筛选后的查询进行验证。不要只在父 span 上使用 exception.message 来搜索异常。

部署回归

按 deployment.version 分组查看 P99 → 使用 BubbleUp 比较新旧版本 → 跟踪新版本中的请求 → 验证

依赖故障

get_service_map → 查看慢速依赖的 P99 → 使用关系查询（any.service.name）衡量对用户的影响 → 跟踪一个受影响的请求

按流程执行

如果你发现自己在进行以下任何一种推理，请仍然遵循工作流：

• “原因很明显，可以跳过 BubbleUp”——BubbleUp 经常会找出事后看来显而易见、但并非最初猜测的原因。它还能发现你可能完全忽略的次要原因。
• “我已经知道这是部署问题”——使用步骤 5 进行验证。事件期间最容易产生确认偏误。分别查询包含和不包含可疑原因的情况。
• “链路已经确认了，不需要验证”——单条链路只是一个个例。验证查询可以证明这一模式适用于所有流量，而不只是某一个请求。
• “这是个简单问题，完整工作流太繁琐”——工作流只需几分钟；事件期间误判原因却会耗费数小时。

结果为空或不明确时

• 没有结果：使用 find_columns 检查字段名称，扩大时间范围，并确认环境／数据集
• BubbleUp 未显示信号：尝试其他时间范围，添加筛选条件以更清晰地隔离异常，或选择其他计算方式
• 链路缺少 span：可能是采样、埋点缺失或跨环境链路拆分导致的

更多资源

参考文件

• ${CLAUDE_PLUGIN_ROOT}/skills/production-investigation/references/investigation-playbooks.md — 延迟尖峰、错误激增、部署回归、依赖故障、SLO 预算消耗和健康检查的分步操作手册
• ${CLAUDE_PLUGIN_ROOT}/skills/production-investigation/references/bubbleup-guide.md — BubbleUp 详细用法：选择类型、时间规格、分页和结果解读
• ${CLAUDE_PLUGIN_ROOT}/skills/production-investigation/references/trace-exploration.md — 链路结构、get_trace 参数和视图模式、瀑布图分析、span 事件和链接

交叉引用

• 有关核心分析循环的概念基础，请参阅 observability-fundamentals 技能
• 有关查询构建模式，请参阅 query-patterns 技能
• 有关调查期间的 SLO／触发器背景信息，请参阅 slos-and-triggers 技能