Terminal
Terminal/Skill
Guidance for writing and reading Honeycomb queries on traces and events, such as percentiles over averages and relational fields.
By Honeycomb
Works with
npx skills add honeycombio/agent-skill --skill query-patternsOpinionated 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.
COUNT, P99(duration_ms), HEATMAP(duration_ms) in a single query reduces API calls and gives a complete picture.find_queries before writing new queries. Someone may have already answered the question.| 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) |
Use relational prefixes to ask cross-span questions within a trace:
any.service.name to find traces where that service participates, group by root.http.route to see which user-facing endpoints are affected.any.error = true, group by root.name to see which entry points have errors somewhere in their trace tree.none.service.name = "health-check" removes traces containing health checks.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:
error_pct)Common patterns:
MUL(IF($error, 1, 0), 100) → use AVG(error_pct) to get percentageIF(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 instead of IF(EQUALS(...)) chains — same expression, more efficientKey guardrails:
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.For full syntax, operator reference, and extended anti-pattern examples, consult
${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/calculated-fields.md.
is_root when measuring user-facing latency — without it, internal spans inflate the numbers"24h", "-6h") — epoch timestamps are error-prone and hard to reviewfind_columns before querying — confirms field names exist and prevents empty resultsAfter 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:
▁▂▃▄▅▆▇█ = density from low to high; two bands = two populationsrun_bubbleup for outlier analysis${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)