query-metrics

docs：修复过时的 SRE 设置说明

fix(query-metrics)：在 metrics-spec 中恢复请求超时 无参数重写退化为裸 curl，丢失了 axiom-api 应用的 --connect-timeout/--max-time 保护，因此停滞的边缘可能无限期挂起调用方。重新应用相同的可通过环境变量覆盖的默认值（AXIOM_CONNECT_TIMEOUT=10，AXIOM_MAX_TIME=120）。 Co-authored-by: pi

feat(query-metrics)：通过 $__interval 实现自适应分辨率 为 metrics-query 添加 -w/--chart-width 和 --pixel-per-point，转发到请求体的 queryOptions 下，以便 metrics 服务可以根据查询的时间范围和目标图表宽度将 $__interval 系统参数解析为合适的步长。在 SKILL.md 中记录该工作流。 将仅存在于已安装 skill 副本中的自适应分辨率工作移植到仓库；保留仅仓库的指导（单引号和高基数警告）。 Co-authored-by: pi

refactor(query-metrics)：使 metrics-spec 无参数 MPL 规范是语言级别的，而非数据集特定的，并且 OPTIONS /v1/query/_mpl 端点在边缘上无需认证即可提供。移除必需的 参数，直接从固定的边缘 URL 获取规范，这样它也能以零配置、无需每次调用推理的方式回答一般 MPL 问题。 Co-authored-by: pi

feat(metrics)：加固 metrics 脚本并修正发现时间文档 axiom-api： - 添加 --connect-timeout（10s）和 --max-time（120s），可通过 AXIOM_CONNECT_TIMEOUT / AXIOM_MAX_TIME 覆盖，使请求快速失败而 不是挂起。 metrics-info： - 对数据集、指标和标签名称以及时间参数进行 URL 编码（jq @uri）， 以便 OTel 名称和 RFC3339 偏移量在保留字符下仍能存活。 - 接受相对 --start/--end（now、now-[smhdw]）；在客户端解析为 RFC3339 UTC，因为 info 端点只解析 RFC3339。 - 在 `describe` 中并发获取每个标签的值；收集、检查所有失败，然后 解析，这样失败的获取会中止而不是输出部分 JSON。 - 传播类型探测查询失败而不是吞掉它们，这样失败的查询永远不会 被误报为标签“不存在”。 query-metrics/SKILL.md： - 记录超时、单引号 MPL、限制 `group by` 基数以及 429 退避。 - 修正相对时间文档：metrics-info 只处理 now / now-[smhdw]，而 metrics-query 将时间转发到服务器， 服务器接受更广泛的集合（例如 now-1y）。已针对 axiom 部署验证。 两个 metrics-info 副本（query-metrics、building-dashboards）保持同步。 Co-Authored-By: Claude Opus 4.8 (1M context)

feat(dashboards)：添加图表/仪表板组装脚本并收紧 skill 文档 引入 chart-add、dashboard-assemble、layout-pack 和 mpl-validate-chart，以端到端支持 building-dashboards 工作流。 围绕新工具重构 SKILL.md 和参考文档（chart-config、layout-recipes、 metrics-mpl、promql-to-mpl、design-playbook、grafana-migration）并移除冗余文字。将更新后的 metrics-info 辅助脚本同步到 query-metrics。 Co-authored-by: Claude Opus 4.7 (1M context)

docs(dashboards)：添加 Grafana 迁移指南和 PromQL→MPL 翻译规则 向 building-dashboards skill 添加两份新的参考文档以及安全使用它们的 支持机制： - reference/grafana-migration.md：规范规范投影（jq）、顶层 字段映射、可视化类型表、名称映射（Prom→OTel 重命名 规则）、缺失标签的反向标签发现以及检查清单。 - reference/promql-to-mpl.md：PromQL 选择器、 分组、rate、直方图、比率、布尔步进函数的机械翻译，以及 反向标签发现；包括“选择器值不在数据集中 的是别名——引用来源”规则。 Skill 级别新增内容： - 新增“计算所要求的内容，或用阻塞项推迟”规则，带有 Note 面板 推迟机制。 - 新增“必需的图表单位配置”矩阵，涵盖每种图表类型不对称的 单位/自定义单位要求。 - 收紧内联时间范围规则，以澄清每面板时间覆盖 仅限 UI（无 API 字段）——overrideDashboardTimeRange 在数据图表上会被静默 丢弃，在 Note 上会被拒绝。 - chart-config / chart-cookbook / design-playbook 更新以支持 新规则。 工具： - scripts/metrics/resolve-url 和 scripts/dashboard-validate 获得 AXIOM_URL_OVERRIDE 支持，与 axiom-api 保持一致，因此单个环境变量 即可将整个辅助工具集路由到非默认边缘（staging 所需）。 - resolve-url 切换到 /v2/datasets。 - dashboard-validate：对每种图表类型的单位/自定义单位进行更严格的检查。 模板： - org-usage-cost-control.json 更新为当前 schema。 - controlling-costs/templates/dashboard.json 小幅清理。 Co-authored-by: Claude Opus 4.7 (1M context)

feat(metrics)：在 query-metrics 中暴露指标类型/时间性/单位元数据 `metrics-info ... metrics` 列表在 `Accept: application/vnd.metrics-info.v2+json` 下已经返回每个指标的 `type`（Gauge | CounterMonotonic | CounterNonMonotonic | Histogram）、 `temporality`（Cumulative | Delta | null）和 `unit`（UCUM 字符串 | null），但该 skill 忽略了这三者。Agent 只能猜测查询形态，并 经常产生语义错误的查询（例如对累积单调计数器求平均，而不是先对其求 rate）。 在不添加任何新服务器契约的情况下，使元数据成为一等公民： scripts/metrics-info： - 添加 `metrics --by-type` 标志，按指标类型对列表进行分组。 - 添加 `metrics --type T` 标志（可重复，OR 语义），将列表过滤为特定类型。可与 --by-type 组合。 - 添加 `metrics info` 子命令，仅返回一个指标的 {type, temporality, unit} 块。在客户端从批量列表派生，因为没有按指标的元数据 端点（已验证：GET /metrics/ 返回 404）。当指标在给定时间范围的列表中不存在时， 以非零退出并给出清晰错误。 - 这三者都是纯客户端 jq 重塑；没有额外的服务器调用。 - 默认 `metrics` 调用不变（原始 v2 负载），因此 现有调用方和快照不受影响。 - 更新了头部文档、show_usage() 和 case 分派。 skills/query-metrics/SKILL.md： - 工作流第 3 步重命名为“发现并分类指标”，并指向 新的元数据部分。 - 新增“根据指标元数据选择查询形态”部分，包含每种 类型/时间性组合的经验规则。故意不 枚举具体 MPL 操作符名称——指向 `metrics-spec` 作为事实来源（最近观察到的 Option 规范漂移 支持保持 SKILL.md 与操作符无关）。 - “报告结果”指导：附加 `unit`，在单位不匹配时警告。 - 发现部分记录了新标志和子命令。 - find-metrics 部分促使 agent 在组合查询之前为每个 候选获取元数据。 skills/building-dashboards/scripts/metrics/metrics-info： - 从规范副本逐字节相同地重新 vendored。 已针对实时部署验证（axiom / homeassistant-metrics，23 个指标覆盖全部四种类型值）： - 默认列表输出保持不变（除了非确定性的服务器 键排序，这本来就是如此）； - --by-type 返回预期的 4 个桶； - --type 过滤并按文档与 --by-type 组合； - info 对已知指标返回正确的元数据块，并且 对未知指标以非零退出并给出“metric not found in listing”错误； - 所有 5 个既有子命令（`tags`、`tags values`、 `metrics tags`、`metrics tags values`、`find-metrics`） 返回与之前相同的形态和内容。 已知缺口：`Delta` 时间性在 SKILL.md 中基于 OTel 数据模型记录，但在验证数据集中未观察到； Cumulative 和 null 是唯一见到的值。 Co-authored-by: Claude

docs(metrics)：在 metrics-query 中支持并记录 MPL 参数值 向 scripts/metrics-query 添加 `-p name=value`（可重复），以便调用方可以 提供 MPL 参数值。该脚本将每个值原样转发到 POST /v1/query/_mpl 的 JSON 体中的 `params.param__` 下，应用 `param__` 前缀并去除 `$`。数据集提取器现在 跳过开头的 `param ...;` 声明，这样声明中的冒号 不会遮蔽 `dataset:metric` 分隔符。 在 query-metrics/SKILL.md 的新“传递参数值”小节中记录 API 契约、请求体形态和 CLI 调用。注意 可选参数（声明语法推迟到 `metrics-spec`）可以 省略，而必需参数如果缺失会引发 HTTP 400。在 building-dashboards/reference/metrics-mpl.md 中添加一个指向新 小节的单一指针（不重复内容）。将 metrics-query 逐字节相同地重新 vendored 到 building-dashboards/scripts/metrics/。 已针对实时 MPL 规范和实时部署验证： - 键命名和原样字面量转发与规范匹配（Query Parameters 部分）； - JSON `params` 体形态端到端工作（参数化与字面量 控件返回相同的序列）； - 必需参数缺失返回 HTTP 400 并带有清晰消息； - 示例中的类型名称与规范的小写 `string` 和大写 `Duration` / `Dataset` / `Regex` 约定匹配。 Co-authored-by: Claude

添加 User-Agent 头以识别 skill 驱动的 agent 流量 这些 skill 的所有 Axiom API 调用现在发送 `axiom-skills/1.0 (agent)` 作为 User-Agent，使其在 axiom-traces-prod 中可与 MCP 流量（`axiom-mcp-server (hosted)`）一起被识别。 Co-Authored-By: Claude Sonnet 4.6

从 main 移植改进 Signed-off-by: Heinz N. Gies

还原 metrics

将分支 'main' 合并到 feat/metrics-dashboard-support

feat(building-dashboards)：添加带 Accept 头 内容协商的 metrics 脚本 将 metrics 脚本（axiom-api、metrics-spec、metrics-query、 metrics-info） 从 query-metrics 移植到 building-dashboards，使用 AXIOM_ACCEPT 环境变量模式 进行内容协商： - axiom-api：Accept 头使用 ${AXIOM_ACCEPT:-application/json} - metrics-spec：发送 Accept: text/markdown - metrics-query：发送 Accept: application/json+metrics.v2（替代 ?format 查询参数） - metrics-info：为列表指标发送 Accept: application/vnd.metrics-info.v2+json Thread： https://ampcode.com/threads/T-019ce12e-9c87-74c6-9074-380907177017 Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-019ce12e-9c87-74c6-9074-380907177017

将分支 'main' 合并到 aisha/edge-auto-resolve

还原 metrics

将 region 替换为 edgeDeployment

更新 skills/query-metrics/SKILL.md Co-authored-by: Heinz N. Gies

fix(query-metrics)：添加 MPL 语法参考以防止无效查询 Claude 生成了无效的 MPL 查询（未转义的点分标识符 如 host.name、使用已弃用的 filter 关键字以及无效的 && 操作符）， 因为 SKILL.md 没有内联语法参考，完全 依赖先运行 metrics-spec。 添加： - MPL 快速参考部分，包含标识符转义规则和 filter 示例 - 强制在组合查询之前必须运行 metrics-spec 的 CRITICAL 说明 - 查询部分中的 filter 示例，展示反引号转义的标签名 - 明确说明 && 和 || 不是有效的 MPL Co-Authored-By: Claude Opus 4.6

使用 edgeDeployment

使用边缘 URL

fix：更新 setup 用法以包含 metrics-spec 所需的 参数 metrics-spec 脚本需要两个参数（ 和 ）， 但 setup 用法文本只显示了一个参数，导致用户复制示例时 验证失败。 Thread: https://ampcode.com/threads/T-019cb7bc-7a65-773c-832c-24c636d73dea Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-019cb7bc-7a65-773c-832c-24c636d73dea

fix(query-metrics)：修复 TOML 解析和 metrics-spec 端点路由 - 修复 axiom-api、 resolve-url 和 setup 脚本中 TOML 节头解析的正则 bug。将 /^\[deployments\./ 改为 /^[[:space:]]*\[deployments\./，以便匹配缩进的节头。 - 修复 metrics-spec：现在需要 dataset 参数以解析 正确的区域边缘 URL（OPTIONS /v1/query/_mpl 仅存在于 边缘端点）。委托给 axiom-api 以获取正确的认证头， 而不是使用裸 curl。 - 更新 SKILL.md 以反映新的 metrics-spec 用法。 Thread: https://ampcode.com/threads/T-019cb7aa-4e1e-74cf-939c-04686b7b58ac Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-019cb7aa-4e1e-74cf-939c-04686b7b58ac

添加数据集区域的自动检测和动态区域 URL 解析

chore(query-metrics)：在示例查询中为 id 包含反引号

使 metrics skill 与现有 skills 保持一致