Axiom Metrics Query Skill
Lets an AI agent query Axiom MetricsDB through scripts, discovering metrics, tags and values and running MPL queries against OpenTelemetry data.
Skill only queries Axiom APIs via curl/jq with clear data flow; README advises minimal-scope API tokens and avoiding PATs; config lives in ~/.axiom.toml; no destructive defaults. Deducted because the actual scripts are not in evidence, least privilege cannot be verified, axiom-api exposes arbitrary authenticated calls, and there is no rollback or sensitive-data redaction guidance.
Docs are self-consistent with full parameter tables, documented error codes, and a 500-error trace-ID debugging flow. Deducted because script bodies are absent so key paths cannot be confirmed, dependency failure feedback rests on a thin setup check, edge cases are thin, and there are no tests for this skill.
Clear trigger conditions (query metrics, explore OTel datasets), layered workflow, and explicit non-fit guidance for find-metrics. Deducted because the skill depends entirely on overseas Axiom endpoints with no statement on mainland-China reachability and no Chinese-language support.
Well-layered SKILL.md and README with rich examples, prerequisites, related skills; MIT license and lint/release CI in the repo. Deducted for missing per-skill versioning, changelog, and maintenance ownership, plus an install path (axiomhq/skills) inconsistent with the assessed repository (pinchbench/skill).
Claims plausible: structured JSON output, edge-deployment auto-resolution, mandatory spec fetch reducing syntax errors. Deducted because static review offers no execution evidence; result correctness and cost/benefit remain unverified, capping at 7.
Auditable primary documentation with consistent examples. Deducted because the skill has no tests of its own (the shell tests belong to building-dashboards), CI is lint-only, and there is no third-party execution evidence, so the static cap of 5 applies.
- The skill depends entirely on overseas Axiom endpoints; mainland-China reachability is undeclared — verify connectivity before use.
- The script sources were not provided in this evidence set; least-privilege and data-handling behavior are unverified.
- axiom-api allows arbitrary authenticated API calls; configure a minimal-scope API token for automated use.
- No per-skill versioning or changelog, and the install source (axiomhq/skills) differs from the reviewed repository (pinchbench/skill) — track updates carefully.
- Static review only; no scripts were executed, and all reliability conclusions are inferred from documentation.
What does this skill do, and when should you use it?
This skill gives an AI agent the ability to query OpenTelemetry metrics stored in Axiom's MetricsDB. A set of scripts (datasets, metrics-spec, metrics-info, metrics-query, etc.) handles dataset discovery, metric/tag exploration, and query execution. Scripts automatically resolve which regional edge deployment a dataset lives in and route requests accordingly, with a fallback to the configured deployment URL. The skill mandates fetching the current MPL query spec before writing any query, so syntax is never guessed from memory. Configuration comes from ~/.axiom.toml (url, token, org_id), and the target dataset must be of kind otel:metrics:v1.
Runs scripts/setup to verify requirements (curl, jq, ~/.axiom.toml); lists datasets in a deployment, optionally filtered to otel:metrics:v1; automatically resolves a dataset's edge deployment to the correct regional endpoint (e.g. us-east-1.aws.edge.axiom.co); fetches the MPL query specification via scripts/metrics-spec; discovers metrics, tags, and tag values via scripts/metrics-info, or locates metrics by a known search value with find-metrics; executes MPL queries via scripts/metrics-query with RFC3339 or relative time ranges (e.g. now-1d); interprets HTTP error codes and, on a 500, re-runs with curl -v to capture the traceparent/x-axiom-trace-id header for backend debugging.
- An SRE asks the agent to investigate latency or error-rate changes for a service over a time window
- A developer wants to browse what metrics, tags, and tag values exist in a dataset before writing a query
- A team needs to filter and group OTel metrics by tags like service.name or status_code
- Only a service name (e.g. 'frontend') is known, so find-metrics locates the matching metrics
- The agent hits an Axiom 500 error and collects the trace ID so the backend team can debug
What are this skill's strengths and limitations?
- Mandates fetching the live MPL spec before the first query, avoiding errors from syntax drift
- Automatically resolves regional edge deployments — no manual multi-region configuration
- Full discovery-oriented workflow: datasets, metrics, tags, and tag values explored layer by layer
- Clear error-handling guidance with common status codes and a concrete trace-ID reporting procedure for 500s
- Depends on an external Axiom account and ~/.axiom.toml; unusable without credentials
- Target datasets must be kind otel:metrics:v1 — not applicable to other dataset types
- No test suite or platform-compatibility evidence is provided in the source
- No guidance on avoiding cost or rate limits (only the meaning of the 429 status code)
How do you install this skill?
Clone the repository: git clone https://github.com/pinchbench/skill.git. The skill lives at .agents/skills/query-metrics/. Prerequisites: curl, jq, and a ~/.axiom.toml with your deployment's url, token, and org_id — run scripts/setup to self-check. Critical: invoke scripts using the full path relative to the skill folder. The exact mechanism for registering the skill in your agent's skill directory (e.g. symlinking) is not documented in the source.
How do you use this skill?
Typical flow: 1) run scripts/setup to check the environment; 2) scripts/datasets <deployment> to list datasets; 3) scripts/metrics-spec <deployment> <dataset> to fetch the syntax spec (mandatory); 4) scripts/metrics-info <deployment> <dataset> metrics|tags to explore available metrics and tags; 5) scripts/metrics-query <deployment> '<mpl>' '<startTime>' '<endTime>' to execute, e.g.: scripts/metrics-query prod 'my-dataset:http.server.duration | where service.name == "frontend" | align to 5m using avg' 'now-1d' 'now'. You can also trigger it naturally: "query frontend's HTTP latency over the last day".