investigate

调查

你正在开展跨产品调查。实际调查几乎总会涉及多个产品——日志错误会引出追踪，缓慢的追踪会暴露出故障 Span，故障 Span 又会与特定会话相关联。沿着证据逐步排查，直到找到明确的根因。

前提条件

此技能要求在你的环境中配置远程托管的 LaunchDarkly MCP 服务。

必需的 MCP 工具：

• query-logs — 获取分页日志条目
• query-traces — 获取分页追踪／Span 条目
• query-error-groups — 获取包含堆栈追踪和频次的错误组
• query-sessions — 获取包含用户详情的会话回放
• query-aggregations — 跨产品类型进行分桶聚合，以分析趋势和数量
• query-timeline-events — 获取会话中的按时间顺序排列的事件时间线
• get-keys — 发现产品类型的有效属性／分组键

工作流

1. 先制定计划。 在首次调用工具之前，先简要列出你打算查询的内容及原因，然后执行计划。只有简单查询才可跳过此步骤。
2. 从小范围开始。 选择一个聚焦的时间范围（用户未指定时默认为 24 小时），并使用你掌握的最具体标识符——追踪 ID、会话 ID、错误组 ID、标志键。宽泛查询会返回大量无关结果。
3. 根据每次结果调整后续查询。 不要只依赖一次工具调用。多次调用 query-logs、query-aggregations、query-traces、query-error-groups 和 query-sessions，并利用每次查询的发现来缩小后续查询范围。
4. 遵守 50 条条目的限制。 query-logs、query-traces、query-error-groups 和 query-sessions 工具每次调用最多返回 50 条条目。对于更大的数据集，先运行 query-aggregations 查询进行聚合，再通过定向查询缩小范围。
5. 积极交叉关联。 日志中的追踪 ID、错误中的会话 ID、会话回放中的错误消息——产品之间的连接点通常就是根因所在。
6. 持续更新检查清单。 定期总结已确认的内容和仍需验证的事项，避免调查偏离方向。
7. 最后给出可执行的结果。 清晰说明发现，并回答最初的问题；提供用户可直接点击查看的引用（日志摘录、追踪 ID、会话 ID、错误组 ID）；评估严重程度；至少给出一项具体的修复措施——配置变更、切换标志、附带文件和行号的代码级修复，或包含确切查询语句的诊断步骤。

在适用时加载配套文件

• logs.md — 调查涉及日志时（错误消息、level=error 筛选器、服务日志模式）
• traces.md — 分析请求流、延迟或 Span 关系时
• errors.md — 查看错误组、堆栈追踪、异常频次时
• sessions.md — 重建用户操作路径，或将前端行为与后端事件关联时
• metrics.md — 对大型数据集进行聚合或构建图表时

通用指南

• 优先聚合，而非分页。 如果要列出不重复的用户、统计不同值或进行汇总，请使用 query-aggregations 和 group_by，不要逐页遍历单条记录。先使用 get-keys 找到合适的分组维度。
• 使用属性筛选前先调用 get-keys。 不同产品类型和服务中的属性名称可能不同（spanName 与 span_name、hasErrors 与 has_errors）。先调用一次 get-keys，可避免因字段名称错误而浪费查询。
• 引用具体标识符。 每项建议都应引用从数据中获取的确切标记键、服务名称、会话 ID、跟踪 ID 或文件路径。这样用户无需重新调查，就能根据你的总结采取行动。
• 妥善处理大型工具输出。 如果工具结果已保存到文件（你会看到“Output too large ... Full output saved to: ”），不要使用 Read——它有相同的令牌限制。请使用 Bash 搭配 python3 或 jq 提取所需的具体内容。
• 工具调用失败时妥善降级处理。 如果工具调用失败（缓冲区溢出、超时、服务器错误），不要默默结束。尝试其他工具或方法。如果都不奏效，请提供目前已发现的信息，以及用户可以手动执行的明确后续步骤。
• 处理模糊请求。 “调查一下”或“这是怎么回事”意味着要深入调查，而不是做个总结。不断迭代调用工具，直到找到根本原因或用尽可用数据。

如果你的环境中没有某个工具，相应的 MCP 服务可能未连接——请明确说明，而不是尝试绕过。