query-metrics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CRITICAL: ALL script paths are relative to this skill's folder. Run them with full path (e.g.,
scripts/metrics-query
).

重要提示： 所有脚本路径均相对于此skill的文件夹。请使用完整路径运行它们（例如：
scripts/metrics-query
）。

Querying Axiom Metrics

查询Axiom指标

Query OpenTelemetry metrics stored in Axiom's MetricsDB.

查询存储在Axiom MetricsDB中的OpenTelemetry指标。

Setup

配置步骤

Run

scripts/setup

to check requirements (curl, jq, ~/.axiom.toml).

Config in

~/.axiom.toml

(shared with axiom-sre):

toml

[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

运行

scripts/setup

以检查依赖项（curl、jq、~/.axiom.toml）。

配置文件位于

~/.axiom.toml

（与axiom-sre共享）：

toml

[deployments.prod]
url = "https://api.axiom.co"
token = "xaat-your-token"
org_id = "your-org-id"

目标数据集的类型必须为

otel-metrics-v1

。

Learning the Metrics Query Syntax

学习指标查询语法

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

bash

scripts/metrics-spec <deployment>

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

查询端点是自描述的。在编写任何查询之前，请获取完整的规范：

bash

scripts/metrics-spec <deployment>

该命令会返回包含语法、运算符和示例的完整指标查询规范。在编写查询前请先阅读该规范以理解查询结构。

Workflow

工作流程

Learn the language: Run
```
scripts/metrics-spec <deployment>
```
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:

bash

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.

学习查询语法：运行
```
scripts/metrics-spec <deployment>
```
以阅读指标查询规范
发现指标：如果可以，使用find-metrics命令，否则通过info脚本列出可用指标
探索标签：列出标签和标签值以了解过滤选项
编写并执行查询：编写指标查询并通过
```
scripts/metrics-query
```
运行
迭代优化：根据结果调整过滤器、聚合和分组方式

如果不确定要查询什么，可以先搜索与相关标签值匹配的指标：

bash

scripts/metrics-info <deployment> <dataset> find-metrics "frontend"

该命令会找到与已知值（例如服务名称或主机）关联的指标，为你构建查询提供起点。

Query Metrics

查询指标

Execute a metrics query against a dataset:

bash

scripts/metrics-query <deployment> '<apl>' '<startTime>' '<endTime>'

Example:

bash

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` )
`apl`	Yes	Metrics query string. Dataset is extracted from the query itself.
`startTime`	Yes	RFC3339 timestamp only (e.g., `2025-01-01T00:00:00Z` ). Relative expressions like `now-1h` are not supported.
`endTime`	Yes	RFC3339 timestamp only (e.g., `2025-01-02T00:00:00Z` ). Relative expressions like `now` are not supported.

对数据集执行指标查询：

bash

scripts/metrics-query <deployment> '<apl>' '<startTime>' '<endTime>'

示例：

bash

scripts/metrics-query prod \
  'my-dataset:http.server.duration | align to 5m using avg' \
  '2025-06-01T00:00:00Z' \
  '2025-06-02T00:00:00Z'

参数	是否必填	描述
`deployment`	是	`~/.axiom.toml` 中配置的名称（例如： `prod` ）
`apl`	是	指标查询字符串。数据集会从查询本身中提取。
`startTime`	是	仅支持RFC3339格式的时间戳（例如： `2025-01-01T00:00:00Z` ）。不支持 `now-1h` 这类相对表达式。
`endTime`	是	仅支持RFC3339格式的时间戳（例如： `2025-01-02T00:00:00Z` ）。不支持 `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

在编写查询前，使用

scripts/metrics-info

探索数据集中存在的指标、标签和值。时间范围默认为过去24小时；可通过

--start

和

--end

参数覆盖默认值。

List metrics in a dataset

列出数据集中的指标

bash

scripts/metrics-info <deployment> <dataset> metrics

bash

scripts/metrics-info <deployment> <dataset> metrics

List tags in a dataset

列出数据集中的标签

bash

scripts/metrics-info <deployment> <dataset> tags

bash

scripts/metrics-info <deployment> <dataset> tags

List values for a specific tag

列出特定标签的取值

bash

scripts/metrics-info <deployment> <dataset> tags <tag> values

bash

scripts/metrics-info <deployment> <dataset> tags <tag> values

List tags for a specific metric

列出特定指标的标签

bash

scripts/metrics-info <deployment> <dataset> metrics <metric> tags

bash

scripts/metrics-info <deployment> <dataset> metrics <metric> tags

List tag values for a specific metric and tag

列出特定指标和标签的取值

bash

scripts/metrics-info <deployment> <dataset> metrics <metric> tags <tag> values

bash

scripts/metrics-info <deployment> <dataset> metrics <metric> tags <tag> values

Find metrics matching a tag value

查找匹配标签值的指标

bash

scripts/metrics-info <deployment> <dataset> find-metrics "<search-value>"

bash

scripts/metrics-info <deployment> <dataset> find-metrics "<search-value>"

Custom time range

自定义时间范围

All info commands accept

--start

and

--end

for custom time ranges:

bash

scripts/metrics-info prod my-dataset metrics \
  --start 2025-06-01T00:00:00Z \
  --end 2025-06-02T00:00:00Z

所有info命令都支持通过

--start

和

--end

参数设置自定义时间范围：

bash

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

and

error

fields:

json

{"message": "description", "error": "detail"}

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

x-axiom-trace-id

header value to the user. This trace ID is essential for debugging the failure with the backend team.

HTTP错误会返回包含

message

和

error

字段的JSON：

json

{"message": "description", "error": "detail"}

常见状态码：

400 — 查询语法无效或数据集名称错误
401 — 缺少身份验证或身份验证无效
403 — 无权限查询/摄入该数据集
404 — 未找到数据集
429 — 触发速率限制
500 — 服务器内部错误

当出现500错误时，添加

curl -v

标志重新运行失败的脚本调用以捕获响应头，然后将

traceparent

或

x-axiom-trace-id

头的值告知用户。此跟踪ID对于与后端团队一起调试问题至关重要。

Scripts

脚本列表

Script	Usage
`scripts/setup`	Check requirements and config
`scripts/metrics-spec <deploy>`	Fetch metrics query specification
`scripts/metrics-query <deploy> <apl> <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

Run any script without arguments to see full usage.

脚本	用途
`scripts/setup`	检查依赖项和配置
`scripts/metrics-spec <deploy>`	获取指标查询规范
`scripts/metrics-query <deploy> <apl> <start> <end>`	执行指标查询
`scripts/metrics-info <deploy> <dataset> ...`	发现指标、标签和值
`scripts/axiom-api <deploy> <method> <path> [body]`	底层API调用

运行任何不带参数的脚本即可查看完整使用说明。