Opinionated guidance for constructing and interpreting Honeycomb queries on trace and event datasets — operation selection (percentiles not AVG, HEATMAP for distributions), relational field patterns (root., parent., any., none.), calculated fields, query math, and result interpretation (P99/P50 ratios, heatmap bands, TOTAL/OTHER rows, raw JSON via query_result_json). Use this skill when the user wants to query spans, traces, or log/event data in Honeycomb — requests like "show me latency", "error rate", "find slow requests", "find outliers", "interpret results", "relational fields", "calculated fields", or "download raw results". This skill covers all dataset types except metrics datasets (dataset_type=metrics) — for those, use metrics-queries instead.
From honeycombnpx claudepluginhub honeycombio/agent-skill --plugin honeycombThis skill uses the workspace's default tool permissions.
references/calculated-fields.mdreferences/query-examples.mdreferences/relational-fields.mdreferences/result-interpretation.mdreferences/visualize-operations.mdExecutes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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.
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)