使用 query-metrics Skill 查询 Axiom MetricsDB：从指标发现到 MPL 查询的完整实战指南

后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载导读本指南围绕开源仓库 .agents/skills/query-metrics 中的 query-metrics Skill 展开系统讲解如何基于一组 Bash 脚本对 Axiom MetricsDB 中的 OpenTelemetry 指标otel:metrics:v1数据集进行发现与查询。你将掌握完整的工作流先列出数据集、拉取 MPL 查询规范、按{type, temporality, unit}元数据选择查询形态再执行 MPL 查询并处理错误同时深入理解$__interval自适应分辨率、-p参数传递、边缘部署路由自动解析等底层实现原理。一、Skill 概览与定位query-metrics 是一套面向 Agent 的指标查询工具集核心能力包括数据集发现列出数据集及其边缘部署edge deployment信息自动解析区域边缘 URL指标查询对存储在 Axiom MetricsDB 中的 OpenTelemetry 指标执行 MPL 查询元数据发现在编写查询之前列出数据集内的指标、标签tag与标签值反向搜索通过已知标签值如服务名反查携带该值的指标查询规范拉取自描述式的 MPL 查询规范含语法、操作符与示例。与仓库中同族的 .agents/skills/axiom-sre/SKILL.md面向 APL 日志查询与 schema 发现和 .agents/skills/building-dashboards/SKILL.md面向含指标面板的仪表盘互为补充——query-metrics 专精于指标数据面的发现与查询。二、安装、前置条件与配置安装方式# Amp amp skill add axiomhq/skills/query-metrics # npxClaude Code、Cursor、Codex 等 npx skills add axiomhq/skills -s query-metrics前置条件目标数据集 kind 必须为otel:metrics:v1命令行工具jq、curlsetup 脚本 会逐一检查并给出缺失提示。配置~/.axiom.toml在~/.axiom.toml中声明你的 Axiom 部署[deployments.prod] url https://api.axiom.co token xaat-your-api-token org_id your-org-idorg_id从 Settings → Organization 获取token建议创建作用域 API TokenSettings → API Tokens按工作流所需最小权限配置自动化工具应避免使用 Personal Access Token。从源码看axiom-api 脚本 用 awk 解析该 TOML 中[deployments.name]段的url/token/org_id三个字段缺一即报错并会列出当前可用的部署名。运行scripts/setup可交互式完成检查与配置引导。三、核心工作流所有脚本路径均相对于 Skill 所在目录调用方式为scripts/name。标准流程共 5 步scripts/datasets deploy --kind otel:metrics:v1—— 列出指标数据集scripts/metrics-spec——编写任何查询前必做。MPL 规范持续演进该规范是权威来源也可用它回答通用的 MPL/指标问题scripts/metrics-info deploy dataset metrics—— 列出指标及其{type, temporality, unit}元数据写查询前先读见下文选择查询形态scripts/metrics-info deploy dataset tags [tag values]—— 探查过滤维度scripts/metrics-query deploy MPL start end—— 执行查询迭代调优。若用户点名某个具体实体服务、主机等用scripts/metrics-info deploy dataset find-metrics value反查携带该实体的指标。注意find-metrics搜索的是标签值而非指标名不要用它做通用指标发现列指标名请用metrics子命令。四、选择查询形态读透{type, temporality, unit}metrics-info返回的清单会给出每个指标的{type, temporality, unit}编写查询前必须阅读永远不要假设某个指标是简单标量。字段取值作用typeGauge、CounterMonotonic、CounterNonMonotonic、Histogram决定必须的前置聚合操作符temporalityCumulative、Delta、null决定计数是累计总值还是单区间增量Gauge 出现null属正常unitUCUM 字符串Cel、kW.h、s、%、[ppm]等或null展示单位上报结果时需保留各类型的查询规则操作符精确名称以metrics-spec为准因其会演进Gauge—— 瞬时值直接用avg/min/max/sum对齐即可。不要套用 rate否则等于在平均瞬时值的无意义增量CounterMonotonic Cumulative—— 运行总和忽略重置。原始值通常不是你要的先换算成每秒速率再做对齐/聚合CounterMonotonic Delta—— 已是单区间增量直接 sum/对齐无需 rate 步骤CounterNonMonotonic—— 可升可降队列深度、余额。意图模糊rate、delta 或当前值对不同的提问都合理应先询问用户再选择Histogram—— 不是标量。align using avg会产生无意义结果必须用bucket … using配合metrics-spec中的直方图函数分位数以浮点数形式作为这些函数的参数temporality决定变体Cumulative与Delta的插值方式不同具体签名查阅metrics-spectemporality: null—— 表示该仪器类型不适用Gauge 的常态不是数据缺失。上报数字时务必附带unitnull视为无单位若在算术中组合了单位不匹配的指标应发出警告而不是静默产生无意义数字。五、执行 MPL 查询metrics-query命令行参数scripts/metrics-query [-w pixels] [--pixel-per-point n] deploy MPL start end参数说明deploy~/.axiom.toml中的部署名如prodMPL查询管道字符串数据集从 MPL 自身解析start/endRFC33392025-01-01T00:00:00Z或相对时间now-1h、now-w/--chart-width px可选。目标图表宽度像素让服务端解析$__interval--pixel-per-point n可选。每点像素数服务端默认 10与-w共同决定桶数量从 metrics-query 源码 可见其内部行为先剥离 MPL 开头的param …;声明再从dataset:metric中提取数据集名调用resolve-url解析边缘部署 URL最后把{apl, startTime, endTime, params, queryOptions}组装成 JSON 体以Accept: application/jsonmetrics.v2发给POST /v1/query/_mpl。两个关键陷阱1. 必须用单引号包裹 MPL 字符串。MPL 中充满反引号若用双引号shell 会把反引号当作命令替换执行——要么静默篡改查询要么直接运行标识符命中的命令。2. 分组前先约束输出。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-pointpixel-per-point默认 10。省略-w时服务端以约 500 桶为目标适用于任何期望Duration的位置如bucket to $__interval using histogram(0.5, 0.95)将-w设为你渲染宽度如metrics-chartSkill 的绘图宽度即可实现一桶约等于一像素列。从源码看该值通过请求体的queryOptionschart-width、pixel-per-point转发边缘节点再转为x-axiom-chart-width/x-axiom-pixel-per-point请求头供指标服务解析。七、MPL 参数传递-p namevalueMPL 可以声明参数param $svc: string;用可重复的-p namevalue传值。脚本会为键加上param__前缀值原样作为 MPL 字面量转发字符串字面量需自带引号scripts/metrics-query \ -p svcfrontend \ -p window5m \ prod \ param $svc: string; param $window: Duration; otel-metrics:http.server.duration | where service.name $svc | align to $window using avg \ now-1h now必需参数必须提供可选参数可省略参考metrics-spec判定。最终请求体形态{ apl: param $svc: string; …, startTime: now-1h, endTime: now, params: { param__svc: \frontend\, param__window: 5m } }各类型的字面量语法见metrics-spec。从源码看metrics-query 会校验-p必须形如namevalue、名称不得带前导$缺失必填参数时服务端返回 HTTP 400。八、指标发现metrics-info全命令参考时间范围默认取最近 24 小时可用--start/--end覆盖。二者接受 RFC3339允许时区偏移或相对时间now/now-Nunitunit取s m h d w在客户端解析为 RFC3339 UTC——这比metrics-query更窄后者把时间原样转发给服务端还能接受now-1y等形态而metrics-info中凡不在now/now-N[smhdw]范围内的输入必须是 RFC3339否则请求会 400。对稀疏指标传感器、批处理任务建议用--start扩大范围如 7 天。命令返回内容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一次调用打包元数据 全部标签 标签值替代 11N 次往返。标志--no-values仅标签名、--values-limit N每个标签值数量上限默认 500 为不限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不存在返回absentmetrics-info d ds tags数据集内全部标签metrics-info d ds tags tag values某标签跨指标的全部取值metrics-info d ds find-metrics value携带该标签值而非指标名的指标几个实现细节见 metrics-info 源码metrics metric info没有专门的单指标元数据端点而是客户端从批量清单中提取describe则在拉取标签后并发抓取各标签值并用--values-limit客户端截断tags tag type探测的实现是分别用filter tag is int/float/string/bool跑metrics-query探针只有返回非空series的类型才算存在——因此对mixed类型要使用防御性写法(tag is int and tag 200) or (tag is string and tag 200)探针查询失败会直接传播错误而非吞掉避免把查询失败误报成标签不存在这种自信的错误答案。九、错误处理与排障HTTP 错误返回带code和message的 JSON部分带detail对象{code: 400, message: MPL syntax error: …}语法错误400会附带带注释的源码定位指针列出失败位置处合法可用的操作符——仔细读它通常直接指明了修复方式。错误码原因400查询语法无效或数据集名错误401认证缺失/无效403无权限404数据集不存在429触发限流——退避重试不要紧循环500内部错误超时约定见 axiom-api 源码请求客户端 120s 超时AXIOM_MAX_TIME覆盖连接 10s 超时AXIOM_CONNECT_TIMEOUT覆盖。遇 500 时用curl -v重跑以抓取traceparent/x-axiom-trace-id请求头并上报——后端团队正是靠这个 trace 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所有脚本不带参数运行即打印完整用法。边缘部署路由是自动的脚本读取每个数据集的edgeDeployment字段自动路由到对应区域端点无需手工配置。其原理见 resolve-url 源码先检查AXIOM_URL_OVERRIDE环境变量存在则原样返回再命中 1 小时 TTL 的本地缓存${TMPDIR:-/tmp}/axiom-resolve-url最后调用GET /v2/datasets取出edgeDeployment并映射为边缘 URL——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为空时回退到~/.axiom.toml中的部署 URL。metrics-query还会把边缘 URL 反推为queryEdgeDeployment如cloud.eu-central-1.aws一并写入请求体从而把查询精确投递到数据集所在的区域节点。十一、最小可运行示例# 1) 安装并配置 npx skills add axiomhq/skills -s query-metrics # 编辑 ~/.axiom.toml然后 scripts/setup # 2) 找到指标数据集 scripts/datasets prod --kind otel:metrics:v1 # 3) 拉取查询规范写任何查询前必做 scripts/metrics-spec # 4) 查看数据集内指标元数据与标签 scripts/metrics-info prod my-dataset metrics scripts/metrics-info prod my-dataset tags service.name values # 5) 按元数据选择查询形态并执行 scripts/metrics-query prod \ my-dataset:http.server.duration | align to 5m using avg | group by endpoint using sum \ 2025-06-01T00:00:00Z 2025-06-02T00:00:00Z结语query-metrics 把指标发现 → 形态决策 → MPL 查询 → 迭代调优的完整链路收敛为一组可组合的脚本metrics-spec保证查询语法始终对齐演进的规范metrics-info的{type, temporality, unit}元数据与describe/find-metrics让陌生指标也能快速上手$__interval与-w解决了缩放适配难题而resolve-url的边缘路由自动解析让跨区域部署透明化。这套工具既可作为 Agent 的即插即用技能也可作为理解 Axiom MetricsDB 查询体系的参考实现。赞分享后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载相关推荐408冲刺怎么安排历年真题和模拟卷最后45天三步把分数拉起来408冲刺怎么安排历年真题和模拟卷最后45天三步把分数拉起来 带着历年真题和模拟卷进408冲刺最容易在两个坑里耗掉两三周套卷顺序不对和限时做不成习文档教育教程Relay 交互查询实战从 Query Variables 到 Preloaded Queries 的完整指南Relay 交互查询实战从 Query Variables 到 Preloaded Queries 的完整指南 Relay 的核心哲学是一次用户交互最多只发前端开发工具MS-SWIFT 中的 Mcore-Bridge让 Megatron 高性能训练像 transformers 一样简单地操作 safetensors 权重MS SWIFT 中的 Mcore Bridge让 Megatron 高性能训练像 transformers 一样简单地操作 safetensors 权重 M后端前端AI 技能AI 插件搜索引擎上一篇三步轻松搞定Python B站视频下载器终极指南下一篇3分钟掌握B站成分检测器终极自动标注工具完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考