query-patterns

Honeycomb 查询模式

编写有效 Honeycomb 查询的实用指南。MCP 工具已记录其参数和架构——本技能侧重于每种模式的使用时机和原因，而非如何调用工具。

核心原则

1. 切勿使用 AVG 计算延迟——AVG 会掩盖尾部延迟。使用 P99（或 P95/P90），了解慢速用户的体验。AVG 应用于负载大小等非延迟指标。
2. 使用 HEATMAP 查看分布——单一数值的聚合会掩盖双峰模式。HEATMAP 可以揭示数据属于一个群体还是两个群体。
3. 在一个查询中组合多项计算——在单个查询中使用 COUNT, P99(duration_ms), HEATMAP(duration_ms) 可以减少 API 调用次数，并提供完整的概况。
4. 先从整体入手，再用 WHERE 缩小范围——先使用 COUNT/GROUP BY 了解整体形态，再添加筛选条件聚焦。
5. 检查已有成果——编写新查询前，先调用 find_queries。可能已经有人回答了这个问题。

选择合适的操作

问题	使用
流量有多大？	按路由或服务分组的 COUNT
有多少独立用户/IP？	COUNT_DISTINCT(field)
大多数用户的速度有多快？	P50(duration_ms)
体验最差的用户的速度有多慢？	P99(duration_ms)
是否存在双峰模式？	HEATMAP(duration_ms)
最坏情况是什么？	MAX(duration_ms)
有多少个并发操作？	CONCURRENCY
情况是否在随时间恶化？	RATE_AVG(duration_ms)

关系字段策略

使用关系前缀，在一次追踪中提出跨 Span 问题：

• “找出由特定下游服务导致的慢速端点”：使用 any.service.name 进行筛选，找到该服务参与的追踪；再按 root.http.route 分组，查看哪些面向用户的端点受到影响。
• “出错的追踪有什么不同？”：使用 any.error = true 进行筛选，再按 root.name 分组，查看哪些入口点在其追踪树中的某处发生了错误。
• 排除噪声：none.service.name = "health-check" 可移除包含健康检查的追踪。

计算字段

计算字段是按事件计算、并在查询时求值的表达式。它们可以转换、分类和组合现有字段，而无需重新插桩代码。

三个作用范围——选择满足需求的最小范围：

• 查询级（不保存）：探索性分析、一次性分析
• 数据集级（已保存）：可在一个服务的数据集中重复使用
• 环境级（已保存）：可在所有数据集中重复使用（例如，error_pct）

常见模式：

• 错误率：MUL(IF($error, 1, 0), 100) → 使用 AVG(error_pct) 获取百分比
• 状态分类：IF(GTE($http.status_code, 500), "5xx", GTE($http.status_code, 400), "4xx", "ok")
• 延迟分桶：BUCKET($duration_ms, 500, 0, 3000)
• 前缀路由：IF(STARTS_WITH($url, "/admin"), "admin", STARTS_WITH($url, "/api"), "api", "other")
• 精确匹配分类：使用 SWITCH 代替 IF(EQUALS(...)) 链——表达式相同，但效率更高

关键注意事项：

• 不要创建仅用于展示（仅别名）的字段——只重命名其他字段不会增加分析价值，反而会让架构变得杂乱。只有在进行实际计算（分类、提取、数学运算）时，才保存计算字段。
• 避免对大型或复杂字段使用正则表达式——对 exception.stacktrace、db.statement 或完整日志行运行 REG_MATCH、REG_VALUE 或 REG_COUNT 可能会非常慢。先检查是否存在更有针对性的 OTel 字段（exception.type、exception.message、db.operation）。如果必须对长字段使用正则表达式，请先用 CONTAINS 检查进行保护。
• EQUALS 会严格匹配类型——如果字段以字符串形式存储，EQUALS($http.status_code, 200) 会静默返回 false。比较前请使用 find_columns 验证字段类型。
• FORMAT_TIME 开销较大——避免在高吞吐量查询中使用。
• 一次性操作应保存为查询级，而非数据集级字段——已保存字段会显示在所有人的架构中。

完整语法、运算符参考以及更多反模式示例，请参阅 ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/calculated-fields.md。

每次查询前

• 测量面向用户的延迟时，按 is_root 过滤——否则内部 span 会抬高数值
• 使用易读的时间范围（"24h"、"-6h"）——epoch 时间戳容易出错，也难以审核
• 查询前使用 find_columns 验证列——确认字段名称存在，避免结果为空

解读结果

运行查询后，MCP 工具会返回格式化的 Markdown 和元数据。 最重要的元数据字段是 query_result_json——它是原始 JSON 结果的签名 URL。要进行精确分析，请下载该结果，并使用 jq 或 python 解析，而 不要只依赖 ASCII 渲染结果。

关键解读规则：

• P99/P50 > 10x——可能存在双峰分布；运行 HEATMAP 以确认
• 分组结果中的 TOTAL 行 = 所有组的聚合结果
• OTHER 行 = 超出查询限制的组（如果 OTHER 占比很大，请提高限制）
• ASCII 热力图 ▁▂▃▄▅▆▇█ = 从低到高的密度；两条带状区域 = 两个群体
• 元数据中的 query_run_pk——直接传给 run_bubbleup 进行异常值分析

更多资源

参考文件

• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/visualize-operations.md — 完整的 VISUALIZE 操作参考，附带示例
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/relational-fields.md — 详细的关系字段指南，包含跨服务模式
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/query-examples.md — 按使用场景整理的详尽查询手册
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/result-interpretation.md — 查询结果解读、原始 JSON 访问和统计启发式方法指南
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/calculated-fields.md — 计算字段语法、完整运算符参考、常见模式和反模式（展示字段、开销较大的字符串操作、类型不匹配）

交叉引用

• 关于使用这些查询模式的结构化调查工作流：production-investigation 技能
• 关于 SLO 解读和消耗告警设计：slos-and-triggers 技能