query-metrics

查询 Axiom 指标

所有脚本路径均相对于此技能文件夹；请以 scripts/<name> 的形式调用。目标数据集的类型必须为 otel:metrics:v1。

有关设置、先决条件和 ~/.axiom.toml 配置，请参阅 README.md。边缘部署路由会自动处理——脚本会读取每个数据集的 edgeDeployment，并在无需配置的情况下路由到正确的区域端点。

工作流

1. scripts/datasets <deploy> --kind otel:metrics:v1 — 列出指标数据集。
2. scripts/metrics-spec — 编写任何查询前都必须先运行。MPL 会不断演进；规范是唯一可信来源。也请用它回答一般的 MPL／指标问题。
3. scripts/metrics-info <deploy> <dataset> metrics — 列出带有 {type, temporality, unit} 元数据的指标。编写查询前请先查看（参见选择查询形式）。
4. scripts/metrics-info <deploy> <dataset> tags [<tag> values] — 探索筛选维度。
5. scripts/metrics-query <deploy> '<MPL>' <start> <end> — 执行查询并迭代调整。

如果用户指定了某个实体（服务、主机等），scripts/metrics-info <deploy> <dataset> find-metrics "<value>" 可查找包含该实体的指标。find-metrics 搜索的是标签值，而不是指标名称——不要用它进行常规发现。

选择查询形式

metrics-info 列表会返回每个指标的 {type, temporality, unit}。编写查询前请先查看这些信息——切勿假定指标是简单的标量。

字段	值	用途
type	Gauge、CounterMonotonic、CounterNonMonotonic、Histogram	确定所需的预聚合运算符。
temporality	Cumulative、Delta、null	确定计数器值是累计总量还是每个时间间隔的增量。对于 Gauge，null 是正常情况。
unit	UCUM 字符串（Cel、kW.h、s、%、[ppm] 等）或 null	显示单位；报告结果时请保留。

各类型的规则（确切的运算符名称请查阅 metrics-spec——这些名称会不断演进）：

• Gauge — 瞬时值。直接用 avg／min／max／sum 对齐。不要应用速率；对瞬时值的无意义增量取平均毫无意义。
• CounterMonotonic + Cumulative — 累计总量（重置情况除外）。原始值通常不是你想要的结果。先转换为每秒速率，然后再对齐／聚合。
• CounterMonotonic + Delta — 已是每个时间间隔的增量。求和／对齐即可，无需进行速率转换。
• CounterNonMonotonic — 值可能上升或下降（队列深度、余额）。意图并不明确：不同问题可能需要速率、增量或当前值。选择之前请询问用户。
• Histogram — 不是标量。使用 align using avg 会产生无意义的结果。请结合 metrics-spec 中的直方图函数使用 bucket … using；分位数是这些函数的浮点数参数，temporality 决定使用哪种变体（Cumulative 或 Delta 插值）。确切的函数签名请查阅 metrics-spec。
• temporality: null — 表示“此类仪器不适用”（Gauge 通常如此），而非“缺少数据”。

展示数值时，请附上 unit（将 null 视为无单位）。如果在算术运算中组合单位不匹配的指标，请发出警告，而不要默默生成无意义的数值。

查询指标

scripts/metrics-query [-w pixels] [--pixel-per-point n] <deploy> '<MPL>' <start> <end>

参数	说明
deploy	~/.axiom.toml 中的名称（例如 prod）。
MPL	管道字符串。数据集从 MPL 本身解析。
start / end	RFC3339（2025-01-01T00:00:00Z）或相对时间（now-1h、now）。
-w / --chart-width <px>	可选。目标图表宽度（像素）；可让服务解析 $__interval。
--pixel-per-point <n>	可选。每个点占用的像素数（服务默认值为 10）；与 -w 配合使用时可设置分桶数量。

在 shell 中始终用单引号括起 MPL 字符串。 MPL 中有很多反引号；在双引号内，shell 会将其作为命令替换执行，从而悄悄篡改查询（或运行标识符所指向的内容）。

先限制输出，再进行分组。 group by <tag> 会针对每个标签值返回一个序列，且不设上限——对于高基数标签，这会导致输出过多。请先检查基数（使用 describe 或 tags <tag> values），并在探索时优先使用普通的 group using <agg>。

示例：

scripts/metrics-query prod -w 1200 \
  '`my-dataset`:`http.server.duration` | align to $__interval using avg' \
  now-1h now

scripts/metrics-query prod -w 1200 \
  '`my-dataset`:`http.server.duration`
   | where `service.name` == "frontend" and method == "GET"
   | align to $__interval using avg
   | group by status_code using sum' \
  now-1d now

自适应分辨率（$__interval）

硬编码步长（align to 5m）会导致图表在不同缩放级别下显示异常——放大时过于稀疏，缩小时过于密集。对于需要 Duration 的位置，优先使用系统参数 $__interval，并传入图表宽度，让服务选择步长：

scripts/metrics-query prod -w 1200 \
  '`my-dataset`:`http.server.duration` | align to $__interval using avg' \
  now-7d now

指标服务会根据查询的时间范围和目标图表宽度计算 $__interval，然后将其向上取整为以下级别中的合适分辨率：1s, 5s, 10s, 15s, 30s, 1m, 5m, 10m, 15m, 30m, 1h, 12h, 1d, 1w, 1M, 1Y。它不会低于指标的存储分辨率。

• 无需声明——服务会自动注册 $__interval；不要添加 param $__interval: Duration;（边缘服务会原样转发查询，指标服务会注入该参数）。
• 分桶数量 ≈ chart-width / pixel-per-point（pixel-per-point 默认值为 10）。省略 -w 时，服务会以约 500 个分桶为目标。
• 任何接受 Duration 的位置都可以使用，例如 bucket to $__interval using histogram(0.5, 0.95)。
• 将 -w 设为渲染宽度（例如 metrics-chart 技能的绘图宽度），使每个分桶约占一列像素。该值会通过请求正文的 queryOptions（chart-width、pixel-per-point）转发。

参数

MPL 可以声明参数（param $svc: string;）。使用重复的 -p name=value 传入值。脚本会添加 API 所需的 param__ 前缀；值会作为 MPL 字面量原样转发（字符串字面量包含引号）。

scripts/metrics-query \
  -p svc='"frontend"' \
  -p window='5m' \
  prod \
  'param $svc: string; param $window: Duration;
   `otel-metrics`:`http.server.duration` | where `service.name` == $svc | align to $window using avg' \
  now-1h now

必须提供必需参数；可省略可选参数。生成的请求正文结构：

{
  "apl": "param $svc: string; …",
  "startTime": "now-1h",
  "endTime": "now",
  "params": { "param__svc": "\"frontend\"", "param__window": "5m" }
}

各类型对应的字面量语法见 metrics-spec。

发现（metrics-info）

时间范围默认为最近 24h；可使用 --start / --end 覆盖。两者均接受 RFC3339（允许偏移量）或相对时间 now / now-<N><unit>，其中 <unit> 为 s m h d w，并在客户端解析为 RFC3339 UTC。此范围比 metrics-query 更窄，后者会将时间原样转发给服务端，因此也接受 now-1y 这类形式；在 metrics-info 中，now / now-<N>[smhdw] 之外的任何形式都必须已是 RFC3339，否则请求会返回 400。

命令	返回内容
metrics-info <d> <ds> metrics	所有指标，以名称为键，包含 {type, temporality, unit}。
metrics-info <d> <ds> metrics --by-type	相同的列表，按 type 分组（客户端重排）。
metrics-info <d> <ds> metrics --type Gauge --type Histogram	筛选后的列表（可重复指定，采用 OR 语义；可与 --by-type 组合）。
metrics-info <d> <ds> metrics <metric> info	单个指标的 {type, temporality, unit}。指标不存在时返回非零退出码。
metrics-info <d> <ds> metrics <metric> describe	捆绑返回：一次调用获取元数据、所有标签及标签值（替代 1+1+N 次往返）。标志：--no-values（仅标签名称）、--values-limit N（限制每个标签的值数量；默认 50，0 = 不限）。
metrics-info <d> <ds> metrics <metric> tags	特定指标携带的标签。
metrics-info <d> <ds> metrics <metric> tags <tag> values	该指标对应的标签值。
metrics-info <d> <ds> metrics <metric> tags <tag> type	探测标签是否为 int/float/string/bool。返回 {type, present_types}；多种类型共存时为 mixed，标签不存在时为 absent。
metrics-info <d> <ds> tags	数据集中的所有标签。
metrics-info <d> <ds> tags <tag> values	标签的所有值（跨指标）。
metrics-info <d> <ds> find-metrics "<value>"	携带给定标签值的指标（而非指标名称）。

错误处理

HTTP 错误会返回包含 code 和 message 的 JSON；有些还包含 detail 对象：

{"code": 400, "message": "MPL syntax error: …"}

语法错误（400）会附带带注释的源码指针，并列出失败位置的有效运算符——请仔细查看，它通常会指出修复方法。

代码	原因
400	查询语法无效或数据集名称错误
401	缺少或无效的身份验证信息
403	无权限
404	未找到数据集
429	请求过多 — 请退避后重试；不要紧密循环重试
500	内部错误

请求在客户端于 120s 后超时（可通过 AXIOM_MAX_TIME 覆盖；AXIOM_CONNECT_TIMEOUT 用于设置 10s 连接超时）。

遇到 500 时，使用 curl -v 重新运行以捕获 traceparent / x-axiom-trace-id 标头并报告该信息——后端团队需要跟踪 ID 来排查问题。

脚本

脚本	用法
scripts/setup	检查依赖项和配置。
scripts/datasets <deploy> [--kind <kind>]	列出边缘部署中的数据集。
scripts/metrics-spec	获取 MPL 查询规范。
scripts/metrics-query [-w px] [--pixel-per-point n] <deploy> <mpl> <start> <end>	执行查询；使用 $__interval + -w 实现自适应分辨率。
scripts/metrics-info <deploy> <dataset> ...	探索指标、标签和值。
scripts/axiom-api <deploy> <method> <path> [body]	调用底层 API。
scripts/resolve-url <deploy> <dataset>	解析为边缘部署 URL。

不带参数运行任意脚本即可查看完整用法。