Hyperdx

HyperDX Log Querying

MANDATORY: Always use hdx_query.sh to query logs and traces. Do not use curl, raw API calls, or any other method — even if it seems simpler. If the script fails, fix the script — do not work around it.

Three failures are environment, not bugs — do not edit the script for these:

Anything else that fails is a real defect: fix the script rather than working around it.

hdx_query.sh ships in this skill's bin/ directory, which is on the Bash tool's PATH whenever the skill is installed. Invoke it by bare name — never by an absolute path. The bare form is the only spelling that works on both install routes, and it is what the permission rule matches.

The script supports two modes: cloud (HyperDX REST API) and local (ClickHouse via docker exec into a local HyperDX container).

Per-Project Configuration (.agent.env)

Each project should have the following in its .agent.env file at the project root:

HYPERDX_MODE: local # or: cloud
OTEL_SERVICE_NAME: your-service-name
HYPERDX_LOCAL_API_KEY: your-personal-api-key
HYPERDX_CONTAINER: hdx-local

• HYPERDX_LOCAL_API_KEY is the Personal API Key from HyperDX account settings — not the Ingestion API Key.
• HYPERDX_CONTAINER is the Docker container name for local mode (default: hdx-local). Omit if using cloud mode only.
• OTEL_SERVICE_NAME is the default service to filter on. Multi-service projects (e.g. a pipeline + an API) instead define one key per service — OTEL_SERVICE_NAME_<SERVICE> (e.g. OTEL_SERVICE_NAME_PIPELINE, OTEL_SERVICE_NAME_API). When those are present, pick the key matching what you're querying and pass it as -s; omit -s to sweep all services. Treat the bare OTEL_SERVICE_NAME as optional in that case.

If a required value (mode, API key, container) is missing from .agent.env, ask the user to add it before proceeding. The service name is optional — without one, query without -s (all services).

Mode Detection (read this before every query)

Before running the script, read .agent.env and apply this logic:

if HYPERDX_MODE == "local"
    → add --local --container <HYPERDX_CONTAINER>
    → do NOT pass --api-key or --url
else (HYPERDX_MODE == "cloud" or not set)
    → pass --api-key <HYPERDX_LOCAL_API_KEY>
    → do NOT pass --local

Never guess the mode — always derive it from HYPERDX_MODE in .agent.env. If HYPERDX_MODE is missing, ask the user to add it before proceeding.

Permissions

This script is meant to be pre-approved, via this rule:

Bash(hdx_query.sh:*)

That rule is not installed by either install route — it lives in the toolkit's project-files/.claude/settings.json template and the user merges it into a project's .claude/settings.json (or their user settings) themselves. So:

• If the rule is present, run the script directly and do not ask for approval.
• If every call prompts, the rule is simply absent. Say so once and continue — that is unfinished setup, not a malfunctioning skill, and not a reason to reach for curl.

Note the rule approves the command name. It matches whatever PATH resolves hdx_query.sh to, which is why the name is unusual enough not to collide.

Dependencies: curl and jq (both standard on most dev machines). Local mode also requires docker.

Arguments

Multi-term Queries

Pass each search term as its own --query flag. The script OR's them together automatically — no shell quote escaping needed:

# DO THIS
hdx_query.sh --query "request completed" --query "job finished" --query "status:500"

# NOT THIS — triggers shell obfuscation warning in Claude Code
hdx_query.sh --query "\"request completed\" OR \"job finished\""

Lucene Field Reference

Local mode matches field:value exactly and case-sensitively (it builds col = 'value'). SeverityText is stored lowercase, so use level:warn / level:error / level:info — level:WARN matches nothing. When unsure of a field's stored values, drop the filter and grep Body with free text instead.

Workflow

1. Read .agent.env — extract the service name(s) (OTEL_SERVICE_NAME, or per-service OTEL_SERVICE_NAME_<SERVICE> keys), HYPERDX_LOCAL_API_KEY, and HYPERDX_CONTAINER. For a multi-service project, pick the key matching what you're querying; omit -s to sweep all services.
2. Determine mode — use --local if the user is debugging a local run; use cloud (default) for deployed services.
3. Construct the query — use one --query flag per term, never escape quotes inside a single flag value.
4. Run the script — default to --minutes 5 --limit 10 for quick checks.
5. Interpret output — summarize patterns, highlight repeated errors, suggest next steps.
6. Iterate — broaden query or increase --minutes / --limit if needed.

Common Patterns

Cloud — quick error check:

hdx_query.sh \
  -k "your-key" -s "your-service" -q "level:error"

Cloud — multi-term OR search:

hdx_query.sh \
  -k "your-key" -s "your-service" \
  --query "request completed" \
  --query "job finished" \
  -t 30 -l 50

Local — recent logs:

hdx_query.sh \
  --local --container hdx-local -s "your-service" \
  -q "level:error" -t 10 -l 20

Local — trace lookup:

hdx_query.sh \
  --local --table traces -s "your-service" \
  -q "TraceId:abc123"

Local — self-hosted URL:

hdx_query.sh \
  -k "your-key" -q "level:error" --url http://localhost:8080

Error Handling