К основному содержанию
скилл CX Codex

query-patterns — скилл для Claude Code: запросы Honeycomb и разбор

Скилл query-patterns учит агента писать запросы к трейсам, логам и событиям Honeycomb и читать выдачу: процентили вместо среднего, HEATMAP, реляционные поля.

MIT 125 установок ★ 28 обновлён 2026-10-09

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add honeycombio/agent-skill --skill query-patterns -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/query-patterns/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/query-patterns/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «DevOps и инфраструктура» →
observability-and-instrumentation addyosmani Скилл observability-and-instrumentation для Claude Code учит ИИ добавлять в код логи, метрики, трейсинг и корреляционные ID. Включается при добавлении фич в продакшн для наблюдения за поведением системы. CX Codex +1 70 700установок groundcover-cli paymog Скилл groundcover-cli учит агента дёргать Go-утилиту groundcover: смотреть логи, трейсы, метрики и события k8s, а ещё управлять мониторами и silences. CX Codex +1 10 400установок dt-obs-tracing Dynatrace Скилл dt-obs-tracing для Claude Code и других агентов: анализирует распределённые трейсы Dynatrace — медленные запросы, упавшие спаны, зависимости между сервисами. Копает вглубь одного запроса по trace.id. CX Codex +1 3 000установок agent-skills datadog-labs Скилл agent-skills для Claude Code: логи, трейсы, мониторы и подключение AWS, Azure и GCP через Datadog. Агент разбирается с observability самостоятельно. CX Codex +1 2 700установок sentry-otel-exporter-setup getsentry Скилл sentry-otel-exporter-setup помогает агенту собрать OpenTelemetry Collector, который отправляет трейсы и логи в Sentry, с маршрутизацией по нескольким проектам. CX Codex +1 2 500установок sentry-go-sdk getsentry Скилл sentry-go-sdk сканирует Go-проект и ведёт по шагам подключения Sentry: ошибки, трейсинг, логи, метрики, кроны. CX Codex +1 2 300установок

Из того же набора4

Спонсоры проекта

Компании, которые помогают держать аналитику открытой