feat(hyperdx): full API coverage + DISCOVER_DATA with hints and automation suggestions#327
Merged
JonasJesus42 merged 8 commits intomainfrom Mar 25, 2026
Merged
Conversation
… + prompt resources New tools (12 added, 3 existing): - QUERY_SPANS: traces/spans with p50/p95/p99 latency defaults - QUERY_METRICS: infrastructure/app metrics with metricDataType guidance - GET_SERVICE_HEALTH: single-call multi-series (error rate + throughput + p95 latency) - COMPARE_TIME_RANGES: ratio-mode period comparison for regression detection - LIST/GET/CREATE/UPDATE/DELETE_ALERT: full alerts CRUD with all channel types - LIST/GET/CREATE/UPDATE/DELETE_DASHBOARD: full dashboards CRUD with chart grid config Bug fix: - Fix URL: /api/v1/charts/series → /api/v1/chart/series Types: - Add rate AggFn variants: avg_rate, max_rate, min_rate, p50_rate–p99_rate, sum_rate Prompts (MCP resources): - HYPERDX_SEARCH_SYNTAX: complete search query syntax guide - HYPERDX_QUERY_GUIDE: practical guide for all tools with examples - HYPERDX_FIELD_REFERENCE: field names for logs, spans, metrics, K8s Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
The runtime expects prompts to be either a function (env) => prompts[] or an array of factory functions — not plain objects. Wrapping in () => prompts satisfies the runtime's typeof check. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
… findings, add expert system prompt DISCOVER_DATA tool: - Runs 6 parallel queries to introspect the HyperDX instance - Returns: active services, log levels, top errors, span operations, cloud providers, dashboards - Designed as the "start here" tool for agents unfamiliar with the data Prompt improvements based on real data exploration: - CRITICAL warnings about non-standard levels (ok/log/info/warn/error/debug) - CRITICAL warnings about body field containing span names for spans - service vs process.serviceName distinction documented - Real query patterns from existing dashboards - Common error patterns documented with their services New HYPERDX_SYSTEM_PROMPT resource: - Complete system prompt for an expert agent on this HyperDX instance - Service taxonomy (storefronts, platform services, CF Workers apps) - Field reference organized by domain (HTTP, infra, deco-chat, build, cache) - Query strategy guide with 7 actionable tips - All 15 dashboards documented with their focus areas Also reverts /chart/series back to /charts/series (plural) — the docs were wrong Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…entPrompt DISCOVER_DATA is now fully instance-agnostic: - Accepts `hints` param with domain keywords/field names - Keywords (e.g., "section", "loader", "vtex") search errors for that term - Field names (e.g., "cloud.provider", "build.step") query field existence + values - Extracts fieldsUsed from dashboard chart configs (groupBy, where, field) - Generates `agentPrompt` text summarizing the full data landscape - All hint queries run in parallel with core queries Prompts cleaned up: - Removed hardcoded Deco-specific HYPERDX_SYSTEM_PROMPT - DISCOVER_DATA now generates instance-specific prompts dynamically - Search syntax and query guide are generic HyperDX knowledge only Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Shows the full input/output of running DISCOVER_DATA with domain hints against the Deco.cx HyperDX instance. Demonstrates how hints surface section rendering errors, loader failures, cloud providers, VTEX/Shopify integration issues, build steps, and dispatch namespaces. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
DISCOVER_DATA now generates suggestedAutomations based on discovered patterns: - Error spike alerts for top-erroring services (prioritized by count) - P95 latency alerts for highest-traffic services - Service Health Overview dashboard suggestion - Error Analysis dashboard suggestion - Hint-based monitoring dashboards Also adds an "Onboarding Flow" section to the agentPrompt guiding users through: discover → create agent → set up dashboards → configure alerts Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
5 issues found across 9 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="hyperdx/examples/discover-data-deco.md">
<violation number="1" location="hyperdx/examples/discover-data-deco.md:41">
P3: The reported total event count is inconsistent with the per-level counts shown below it.</violation>
</file>
<file name="hyperdx/server/tools/alerts.ts">
<violation number="1" location="hyperdx/server/tools/alerts.ts:136">
P2: CREATE_ALERT does not enforce the source-specific required fields it documents, so invalid requests are accepted by the tool schema.</violation>
</file>
<file name="hyperdx/server/tools/hyperdx.ts">
<violation number="1" location="hyperdx/server/tools/hyperdx.ts:308">
P2: QUERY_SPANS does not filter to spans when query is empty, so it can return logs instead of span data.</violation>
<violation number="2" location="hyperdx/server/tools/hyperdx.ts:554">
P1: COMPARE_TIME_RANGES ignores the current/prior period boundaries, so it does not actually compare the two requested ranges.</violation>
<violation number="3" location="hyperdx/server/tools/hyperdx.ts:921">
P2: totalEvents is computed from only the top 30 services, which makes generated level percentages inaccurate.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
1. QUERY_SPANS: add `duration:>0` filter to ensure only spans are returned, even when query is empty 2. COMPARE_TIME_RANGES: query each period separately with parallel Promise.all instead of relying on a single wide-window ratio query that didn't respect period boundaries 3. DISCOVER_DATA totalEvents: compute from levels array (not sliced) instead of top-30 services, fixing inflated percentages 4. CREATE_ALERT: add Zod .refine() to enforce source='chart' requires dashboardId+chartId and source='search' requires savedSearchId 5. Example doc: fix total event count to match sum of per-level counts (was 19.5M, correct is 20.1M — caused by old top-30 bug) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
1 issue found across 3 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="hyperdx/server/tools/hyperdx.ts">
<violation number="1" location="hyperdx/server/tools/hyperdx.ts:587">
P1: `COMPARE_TIME_RANGES` no longer returns the promised `current/prior` ratio, only raw `current` and `prior` arrays.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
The tool description promised ratio analysis but the previous fix only returned raw current/prior arrays. Now computes a summary per group with currentValue, priorValue, ratio (current/prior), and change (%). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="hyperdx/server/tools/hyperdx.ts">
<violation number="1" location="hyperdx/server/tools/hyperdx.ts:607">
P2: `summary` incorrectly sums time buckets for non-additive aggregations (`avg`/percentiles/`max`), which makes ratio comparisons inaccurate.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| JSON.stringify((item.group as string[]) ?? []); | ||
| const val = (item: RawItem) => (item["series_0.data"] as number) ?? 0; | ||
|
|
||
| const priorMap = new Map<string, number>(); |
Contributor
There was a problem hiding this comment.
P2: summary incorrectly sums time buckets for non-additive aggregations (avg/percentiles/max), which makes ratio comparisons inaccurate.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At hyperdx/server/tools/hyperdx.ts, line 607:
<comment>`summary` incorrectly sums time buckets for non-additive aggregations (`avg`/percentiles/`max`), which makes ratio comparisons inaccurate.</comment>
<file context>
@@ -582,11 +595,52 @@ export const createCompareTimeRangesTool = (_env: Env) =>
+ JSON.stringify((item.group as string[]) ?? []);
+ const val = (item: RawItem) => (item["series_0.data"] as number) ?? 0;
+
+ const priorMap = new Map<string, number>();
+ for (const item of priorData) {
+ // Aggregate across time buckets for the same group
</file context>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
New Tools
Query & Analysis (4 new)
groupBy: ["span_name", "service"]metricDataTypeguidance (Gauge/Sum/Histogram)Alerts CRUD (5 new)
Dashboards CRUD (5 new)
Discovery & Onboarding (1 new)
hintsparam with domain keywords (e.g.,"section loader cloud.provider vtex") to run targeted queries. Extracts field patterns from dashboard configs. Generates:agentPrompt— ready-to-use system prompt for an expert agentsuggestedAutomations— alerts and dashboards to set up based on discovered patternsOther Changes
avg_rate,max_rate,min_rate,p50_rate–p99_rate,sum_rate/chart/seriesback to/charts/series(docs were wrong)HYPERDX_SEARCH_SYNTAXandHYPERDX_QUERY_GUIDE(generic, instance-agnostic)examples/discover-data-deco.mdshowing DISCOVER_DATA with Deco.cx hints and outputOnboarding Flow
Test plan
bun build)🤖 Generated with Claude Code
Summary by cubic
Adds full HyperDX MCP API coverage with alerts and dashboards CRUD, spans/metrics queries, and a new
DISCOVER_DATAtool that maps an instance and generates anagentPromptwithsuggestedAutomations. Also adds MCP prompt resources and rate aggregation support.New Features
QUERY_SPANS,QUERY_METRICS,GET_SERVICE_HEALTH,COMPARE_TIME_RANGES.LIST/GET/CREATE/UPDATE/DELETE_ALERTwith email, Slack, PagerDuty, OpsGenie, and Slack webhook channels.LIST/GET/CREATE/UPDATE/DELETE_DASHBOARDwith grid layout and multi-series charts.DISCOVER_DATA: parallel introspection withhints; returnsagentPromptandsuggestedAutomations.HYPERDX_SEARCH_SYNTAXandHYPERDX_QUERY_GUIDEvia@decocms/runtimeprompts.avg_rate…p99_rate,sum_rate).Bug Fixes
@decocms/runtimecompatibility; correct charts API path to/charts/series.QUERY_SPANSenforcesduration:>0;COMPARE_TIME_RANGESqueries each period separately and now returns a per-group ratio/change summary;DISCOVER_DATAcomputestotalEventsfrom levels;CREATE_ALERTvalidatessource-specific fields; example doc totals corrected.Written for commit b121a3f. Summary will update on new commits.