| name | query-metrics |
| description | Runs metrics queries against Axiom MetricsDB via scripts. Discovers available metrics, tags, and tag values. Use when asked to query metrics, explore metric datasets, check metric values, or investigate OTel metrics data. |
CRITICAL: ALL script paths are relative to this skill's folder. Run them with full path (e.g., scripts/metrics-query).
Querying Axiom Metrics
Query OpenTelemetry metrics stored in Axiom's MetricsDB.
Setup
Run scripts/setup to check requirements (curl, jq, ~/.axiom.toml).
Config in ~/.axiom.toml (shared with axiom-sre):
[deployments.prod]
url = "https://api.axiom.co"
token = "xaat-your-token"
org_id = "your-org-id"
The target dataset must be of kind otel:metrics:v1.
Discovering Datasets
List all datasets in a deployment:
scripts/datasets <deployment>
Filter to only metrics datasets:
scripts/datasets <deployment> --kind otel:metrics:v1
This returns each dataset's name, edgeDeployment, and kind. Use the dataset name in subsequent metrics-info and metrics-query calls.
Edge Deployment Resolution
Datasets can live in different edge deployments (e.g., us-east-1 vs eu-central-1). The scripts automatically resolve the correct regional edge URL before querying. No manual configuration is needed — metrics-info and metrics-query detect the dataset's edge deployment and route requests to the right endpoint.
| Edge Deployment | Edge Endpoint |
|---|
cloud.us-east-1.aws | https://us-east-1.aws.edge.axiom.co |
cloud.eu-central-1.aws | https://eu-central-1.aws.edge.axiom.co |
If resolution fails or the edge deployment is unknown, requests fall back to the deployment URL in ~/.axiom.toml.
Learning the Metrics Query Syntax
CRITICAL: You MUST run metrics-spec before composing your first query in a session. NEVER guess MPL syntax — it changes over time and the spec is the only source of truth.
scripts/metrics-spec <deployment> <dataset>
Re-consult the spec when using an unfamiliar operator, when a query returns a syntax error, or when constructing histogram/multi-metric queries.
Workflow
- List datasets: Run
scripts/datasets <deployment> to see available datasets and their edge deployments
- Fetch the spec: Run
scripts/metrics-spec <deployment> <dataset> — this step is mandatory before writing any query
- Discover metrics: List available metrics via
scripts/metrics-info <deployment> <dataset> metrics
- Explore tags: List tags and tag values to understand filtering options. If metrics listing fails, use tags and tag values to identify relevant entities, then use those to list metrics for specific tags.
- Write and execute query: Compose a metrics query and run it via
scripts/metrics-query
- Iterate: Refine filters, aggregations, and groupings based on results
If the user provides a specific service, host, or entity name to search for, use find-metrics to locate matching metrics:
scripts/metrics-info <deployment> <dataset> find-metrics "frontend"
Do NOT use find-metrics as a general discovery step — it requires a known search value.
Query Metrics
Execute a metrics query against a dataset:
scripts/metrics-query <deployment> '<mpl>' '<startTime>' '<endTime>'
Examples:
scripts/metrics-query prod \
'`my-dataset`:`http.server.duration` | align to 5m using avg' \
'2025-06-01T00:00:00Z' \
'2025-06-02T00:00:00Z'
scripts/metrics-query prod \
'`my-dataset`:`http.server.duration` | where `service.name` == "frontend" and method == "GET" | align to 5m using avg | group by status_code using sum' \
'now-1d' \
'now'
| Parameter | Required | Description |
|---|
deployment | Yes | Name from ~/.axiom.toml (e.g., prod) |
mpl | Yes | Metrics query string. Dataset is extracted from the query itself. |
startTime | Yes | RFC3339 (e.g., 2025-01-01T00:00:00Z) or relative expression (e.g., now-1h, now-1d) |
endTime | Yes | RFC3339 (e.g., 2025-01-02T00:00:00Z) or relative expression (e.g., now) |
Discovery (Info Endpoints)
Use scripts/metrics-info to explore what metrics, tags, and values exist in a dataset before writing queries. Time range defaults to the last 24 hours; override with --start and --end.
List metrics in a dataset
scripts/metrics-info <deployment> <dataset> metrics
List tags in a dataset
scripts/metrics-info <deployment> <dataset> tags
List values for a specific tag
scripts/metrics-info <deployment> <dataset> tags <tag> values
List tags for a specific metric
scripts/metrics-info <deployment> <dataset> metrics <metric> tags
List tag values for a specific metric and tag
scripts/metrics-info <deployment> <dataset> metrics <metric> tags <tag> values
Find metrics matching a tag value
scripts/metrics-info <deployment> <dataset> find-metrics "<search-value>"
Custom time range
All info commands accept --start and --end for custom time ranges:
scripts/metrics-info prod my-dataset metrics \
--start 2025-06-01T00:00:00Z \
--end 2025-06-02T00:00:00Z
Error Handling
HTTP errors return JSON with message, code, and optional detail fields:
{"message": "description", "code": 400, "detail": {"errorType": 1, "message": "raw error"}}
Common status codes:
- 400 — Invalid query syntax or bad dataset name
- 401 — Missing or invalid authentication
- 403 — No permission to query/ingest this dataset
- 404 — Dataset not found
- 429 — Rate limited
- 500 — Internal server error
On a 500 error, re-run the failing script call with curl -v flags to capture response headers, then report the traceparent or x-axiom-trace-id header value to the user. This trace ID is essential for debugging the failure with the backend team.
Scripts
| Script | Usage |
|---|
scripts/setup | Check requirements and config |
scripts/datasets <deploy> [--kind <kind>] | List datasets (with edge deployment info) |
scripts/metrics-spec <deploy> <dataset> | Fetch metrics query specification |
scripts/metrics-query <deploy> <mpl> <start> <end> | Execute a metrics query |
scripts/metrics-info <deploy> <dataset> ... | Discover metrics, tags, and values |
scripts/axiom-api <deploy> <method> <path> [body] | Low-level API calls |
scripts/resolve-url <deploy> <dataset> | Resolve dataset to edge deployment URL |
Run any script without arguments to see full usage.
