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

,

region

, and

kind

. Use the dataset name in subsequent

metrics-info

and

metrics-query

calls.

Region Resolution

Datasets can live in different regions (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 region and route requests to the right endpoint.

Dataset Region

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 region is unknown, requests fall back to the deployment URL in

~/.axiom.toml

.

Learning the Metrics Query Syntax

The query endpoint is self-describing. Before writing any query, fetch the full specification:

scripts/metrics-spec

<

deployment

>

<

dataset

>

This returns the complete metrics query specification with syntax, operators, and examples. Read it to understand query structure before composing queries.

Workflow

List datasets

Run

scripts/datasets

to see available datasets and their regions

Learn the language

Run

scripts/metrics-spec

to read the metrics query spec

Discover metrics

If possible use the find-metrics command, otherwise list available metrics via the info scripts

Explore tags

List tags and tag values to understand filtering options

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 you are unsure what to query, start by searching for metrics that match a relevant tag value: scripts/metrics-info < deployment

< dataset

find-metrics "frontend" This finds metrics associated with a known value (e.g., a service name or host), giving you a starting point for building queries. Query Metrics Execute a metrics query against a dataset: scripts/metrics-query < deployment

'' '' '' Example: scripts/metrics-query prod \ 'my-dataset:http.server.duration | align to 5m using avg' \ '2025-06-01T00:00:00Z' \ '2025-06-02T00:00:00Z' 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 "" 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 [--kind ] List datasets (with region info) scripts/metrics-spec Fetch metrics query specification scripts/metrics-query Execute a metrics query scripts/metrics-info ... Discover metrics, tags, and values scripts/axiom-api [body] Low-level API calls scripts/resolve-url Resolve dataset to regional edge URL Run any script without arguments to see full usage.

query-metrics

安装