query-patterns — скилл для Claude Code: запросы Honeycomb и разбор
Скилл query-patterns учит агента писать запросы к трейсам, логам и событиям Honeycomb и читать выдачу: процентили вместо среднего, HEATMAP, реляционные поля.
MIT 125 установок ★ 28 обновлён 2026-10-09
npx skills add honeycombio/agent-skill --skill query-patterns -a claude-codeЧто делает query-patterns
Скилл дополняет MCP-инструменты Honeycomb: у тех уже описаны параметры, а здесь — когда какой вид запроса уместен. По латентности он сразу разворачивает от среднего: AVG сглаживает хвост, поэтому в ход идут P99 или P95, а AVG остаётся для величин вроде размера ответа. Если одного числа мало, агент строит HEATMAP и смотрит, одна популяция или две.
Реляционные префиксы any., none., root. и parent. дают вопросы поперёк спанов одного трейса: отфильтровать трейсы с участием конкретного сервиса и сгруппировать по маршруту, который видит пользователь. Вычисляемые поля считаются на лету и живут в трёх областях — запрос, датасет, окружение. Сохранять их на уровне датасета стоит не для разведки, иначе поле всплывёт в схеме у всех.
Перед запросом скилл велит проверить типы через find_columns: EQUALS сравнивает строго, и строка вместо числа молча даст false. Регулярка по exception.stacktrace или целой строке лога тормозит — сначала ищите более узкое поле OTel. Для датасетов с dataset_type=metrics это не тот скилл, там нужен metrics-queries. Внутри ещё пять справочников: операции VISUALIZE, реляционные поля, сборник примеров запросов, разбор результатов и синтаксис вычисляемых полей.
Какие задачи решает
- посчитать P99 латентности вместо среднего
- увидеть через HEATMAP, что распределение двугорбое
- найти эндпоинты, которые тормозят из-за конкретного сервиса
- собрать процент ошибок вычисляемым полем
- разобрать сырой JSON результата, а не ASCII-таблицу
Примеры запросов агенту
- Покажи латентность по маршрутам за
24h, только спаны сis_root. - Построй
HEATMAPпоduration_msи скажи, две там популяции или одна. - Скачай
query_result_jsonи посчитай отношение P99 к P50.
Как установить query-patterns
1Через Skills CLI (Vercel)
npx skills add honeycombio/agent-skill --skill query-patterns -a claude-code2Вручную: положить файлы
~/.claude/skills/query-patterns/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/query-patterns/
1Через Skills CLI (Vercel)
npx skills add honeycombio/agent-skill --skill query-patterns -a codex2Вручную: положить файлы
.agents/skills/query-patterns/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add honeycombio/agent-skill --skill query-patterns -a cursor2Вручную: положить файлы
.cursor/skills/query-patterns/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install honeycombio/agent-skill honeycomb/skills/query-patterns2Вручную: положить файлы
.github/skills/query-patterns/SKILL.md1Через Skills CLI (Vercel)
npx skills add honeycombio/agent-skill --skill query-patterns -a gemini-cli2Командой платформы
gemini skills install https://github.com/honeycombio/agent-skill --path honeycomb/skills/query-patternsВручную: положить файлы
.devin/skills/query-patterns/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add honeycombio/agent-skill --skill query-patterns -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о query-patterns
Как установить query-patterns в Claude Code?
Выполните npx skills add honeycombio/agent-skill --skill query-patterns -a claude-code. Файл скилла окажется по пути ~/.claude/skills/query-patterns/SKILL.md.
Что делает query-patterns?
Подсказывает агенту, какой операцией отвечать на вопрос: COUNT для трафика, P99 для хвоста латентности, HEATMAP для формы распределения. И как потом читать то, что вернул инструмент.
Сработает ли он на датасетах метрик Honeycomb?
Нет. Для датасетов с dataset_type=metrics нужен отдельный скилл metrics-queries.
Исходный текст
SKILL.md · MIT
---
name: query-patterns
description: >
Constructing and interpreting Honeycomb queries on trace, log and event datasets:
operation selection (percentiles not AVG, HEATMAP for distributions), relational fields
(root., parent., any., none.), calculated fields, query math, and reading results (P99/P50
ratios, heatmap bands, TOTAL/OTHER rows, raw JSON via query_result_json). Trigger phrases:
"show me latency", "error rate", "find slow requests", "find outliers", "interpret
results", "relational fields", "calculated fields", "download raw results". For metrics
datasets (dataset_type=metrics) use metrics-queries.
metadata:
version: "1.1.0"
---
# Honeycomb Query Patterns
Opinionated guidance for writing effective Honeycomb queries. The MCP tools already
document their parameters and schemas — this skill focuses on *when* and *why* to
use each pattern, not *how* to call the tools.
## Key Principles
1. **Never use AVG for latency** — AVG hides tail latency. Use P99 (or P95/P90) to see what slow users experience. Reserve AVG for non-latency metrics like payload size.
2. **Use HEATMAP for distributions** — Single-number aggregates hide bimodal patterns. HEATMAP reveals whether you have one population or two.
3. **Combine calculations in one query** — `COUNT, P99(duration_ms), HEATMAP(duration_ms)` in a single query reduces API calls and gives a complete picture.
4. **Start broad, narrow with WHERE** — Begin with a COUNT/GROUP BY to understand shape, then add filters to focus.
5. **Check for prior work** — Call `find_queries` before writing new queries. Someone may have already answered the question.
## Choosing the Right Operation
| Question | Use |
|----------|-----|
| How much traffic? | `COUNT` grouped by route or service |
| How many unique users/IPs? | `COUNT_DISTINCT(field)` |
| How fast for most users? | `P50(duration_ms)` |
| How fast for the worst-off users? | `P99(duration_ms)` |
| Is there a bimodal pattern? | `HEATMAP(duration_ms)` |
| What's the worst case? | `MAX(duration_ms)` |
| How many concurrent operations? | `CONCURRENCY` |
| Is it getting worse over time? | `RATE_AVG(duration_ms)` |
## Relational Field Strategy
Use relational prefixes to ask cross-span questions within a trace:
- **"Show me slow endpoints caused by a specific downstream"**: Filter with `any.service.name` to find traces where that service participates, group by `root.http.route` to see which user-facing endpoints are affected.
- **"What's different about errored traces?"**: Filter with `any.error = true`, group by `root.name` to see which entry points have errors somewhere in their trace tree.
- **Exclude noise**: `none.service.name = "health-check"` removes traces containing health checks.
## Calculated Fields
Calculated fields are per-event expressions evaluated at query time. They transform,
classify, and combine existing fields without re-instrumenting code.
**Three scopes** — choose the narrowest that fits the need:
- **Query-scoped** (not saved): exploratory, one-off analysis
- **Dataset-level** (saved): reusable within one service's dataset
- **Environment-level** (saved): reusable across all datasets (e.g., `error_pct`)
**Common patterns:**
- **Error rate**: `MUL(IF($error, 1, 0), 100)` → use `AVG(error_pct)` to get percentage
- **Status classification**: `IF(GTE($http.status_code, 500), "5xx", GTE($http.status_code, 400), "4xx", "ok")`
- **Latency bucketing**: `BUCKET($duration_ms, 500, 0, 3000)`
- **Prefix routing**: `IF(STARTS_WITH($url, "/admin"), "admin", STARTS_WITH($url, "/api"), "api", "other")`
- **Exact-match classification**: use `SWITCH` instead of `IF(EQUALS(...))` chains — same expression, more efficient
**Key guardrails:**
- **Don't create presentational (alias-only) fields** — a field that just renames another field adds no analytical value and clutters the schema. Only save a calculated field when it does real computation (classification, extraction, math).
- **Avoid regex on large/complex fields** — running `REG_MATCH`, `REG_VALUE`, or `REG_COUNT` on `exception.stacktrace`, `db.statement`, or full log lines can be very slow. Check whether a more targeted OTel field exists first (`exception.type`, `exception.message`, `db.operation`). If you must regex a long field, guard it with a `CONTAINS` check first.
- **`EQUALS` has strict type matching** — `EQUALS($http.status_code, 200)` silently returns false if the field is stored as a string. Use `find_columns` to verify the field type before comparing.
- **`FORMAT_TIME` is expensive** — avoid in high-volume queries.
- **Save query-scoped, not dataset-level, for one-off work** — saved fields show up in everyone's schema.
For full syntax, operator reference, and extended anti-pattern examples, consult
`${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/calculated-fields.md`.
## Before Every Query
- **Filter on `is_root`** when measuring user-facing latency — without it, internal spans inflate the numbers
- **Use human-readable time ranges** (`"24h"`, `"-6h"`) — epoch timestamps are error-prone and hard to review
- **Validate columns with `find_columns` before querying** — confirms field names exist and prevents empty results
## Interpreting Results
After running a query, the MCP tool returns formatted markdown plus metadata.
The most important metadata field is `query_result_json` — a signed URL to the raw
JSON result. For precise analysis, download it and parse with jq or python rather
than relying solely on the ASCII rendering.
Key interpretation rules:
- **P99/P50 > 10x** — bimodal distribution likely; run HEATMAP to confirm
- **TOTAL row** in breakdown results = aggregate across all groups
- **OTHER row** = groups beyond the query limit (increase limit if OTHER is large)
- **ASCII heatmap** `▁▂▃▄▅▆▇█` = density from low to high; two bands = two populations
- **query_run_pk** in metadata — feed directly to `run_bubbleup` for outlier analysis
## Additional Resources
### Reference Files
- **`${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/visualize-operations.md`** — Complete VISUALIZE operation reference with examples
- **`${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/relational-fields.md`** — Detailed relational field guide with cross-service patterns
- **`${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/query-examples.md`** — Extensive query cookbook organized by use case
- **`${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/result-interpretation.md`** — Guide to interpreting query results, raw JSON access, and statistical heuristics
- **`${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/calculated-fields.md`** — Calculated field syntax, full operator reference, common patterns, and anti-patterns (presentational fields, expensive string ops, type mismatches)
### Cross-References
- For the structured investigation workflow that uses these query patterns: **production-investigation** skill
- For SLO interpretation and burn alert design: **slos-and-triggers** skill
© honeycombio · MIT · honeycombio/agent-skill