building-dashboards

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

合并拉取请求 #54，来自 axiomhq/improve-metrics-skill feat(metrics): 加固指标脚本并修正发现时间文档

同步查询 Signed-off-by: Heinz N. Gies

同步规范逻辑 Signed-off-by: Heinz N. Gies

skills/building-dashboards: 当拆分存在歧义时保持查询不变 引号跨度正则只跟踪普通的 '...'/"..." 字面量。APL 还接受 反斜杠转义、@-逐字字面量（其中 `\` 不是转义）以及 // 注释，而其中任何一个内部的 `|` 都可能被拆分为阶段边界， 从而静默地重写一个有效的查询。 没有正则能覆盖所有四种形式，而一个能感知转义的正则会破坏逐字 字面量。改为放弃处理：任何有歧义的内容都按原样存储。格式化是 表面性的，所以对奇特查询格式化不足总好过破坏它。

skills/building-dashboards: 在每个管道符前用换行符格式化 chart-add 管道 chart-add 原样存储 --apl/--mpl 字符串，因此单行查询在仪表板中 也以单行形式出现。在存储时于每个管道 `|` 前换行。能感知引号， 因此字符串字面量内部的 `|` 保持不变。

feat(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)

审查反馈 Signed-off-by: Heinz N. Gies

feat(dashboards): 添加图表/仪表板组装脚本并收紧技能文档 引入 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 技能添加两份新参考文档以及安全使用它们的 配套机制： - reference/grafana-migration.md：规范规范投影（jq）、顶层 字段映射、可视化类型表、名称映射（Prom→OTel 重命名 规则）、针对缺失标签的反向标签发现以及检查清单。 - reference/promql-to-mpl.md：PromQL 选择器、分组、rate、直方图、 比率、布尔阶跃函数的机械翻译，以及反向标签发现；包含“不在数据集中的 选择器值是别名——引用来源”规则。 技能级新增： - 新增“计算所要求的内容，或用阻塞项推迟”规则，带 Note 面板 推迟机制。 - 新增“必需的图表单位配置”矩阵，涵盖每种图表类型不对称的 单位/customUnits 要求。 - 收紧内联时间范围规则，澄清每面板时间覆盖 仅限 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：按图表类型对 unit/customUnits 进行更严格的检查。 模板： - org-usage-cost-control.json 更新到当前 schema。 - controlling-costs/templates/dashboard.json 小幅清理。 Co-authored-by: Claude Opus 4.7 (1M context)

docs(dashboards): 禁止图表查询中的内联时间范围；记录 $__interval 测试模式 将针对 k8s-metrics-staging 的一次真实误用会话中学到的两条规则 编入文档： - 仪表板图表查询绝不能包含内联 MPL 时间范围（`[1h..]`、 `[30d..]` 等）。仪表板运行时总是通过 API 提供 `start`/`end`， 因此任何内联范围都会冲突，后端返回 `AST Error (Time is provided both in the query and as a parameter)`。 对于指标图表，`overrideDashboardTimeRange: true` 不会抑制 API 范围。 将其添加为硬性规则，附正确/错误的 MPL 示例，紧邻现有的对齐规则。 - 替换“例外”段落，该段落告诉代理在使用 `metrics-query` 预验证时 替换为固定时长。该指导掩盖了已部署图表是否真正有效。 仪表板运行时同时注入 `param $__interval: Duration;` 及其值； `metrics-query` 不会自动注入二者，但它接受 `-p name=value` 以通过 API 转发参数。新指导：前置参数声明并传入 `-p __interval=5m` 以模拟运行时，附正确/错误的 bash 示例。 - 向常见陷阱添加两行：一行针对 AST 时间冲突错误 （原因：内联范围），一行针对来自 `metrics-query` 的 `The param $__interval is not defined` （原因：忘记像仪表板运行时那样注入参数）。 Co-authored-by: Claude

docs(dashboards): 收紧单位处理文档并修复 unit-for "%" 测试 对来自 c8b064b 的仪表板技能变更进行清理。 正确性： - tests/unit-for.sh："%" 断言期望 {"unit":"Percent100"}，但 脚本（按其自身文档字符串是正确的）同时输出 `unit` 和 `customUnits`，因为仅 Percent100 不会绘制 % 后缀。 更新测试以匹配已发布行为。34/34 通过。 - reference/metrics-mpl.md：`unit-for "%"` 的工作流示例显示了 错误的返回值；更正为 {"unit":"Percent100","customUnits":"%"}。 - scripts/metrics/unit-for：从公开脚本头部删除 "Verified May 2026" / "unverified" 注释（与已进行的 markdown 清理保持同样的卫生）。 去重： - chart-config.md 现在是图表级 单位语义的唯一事实来源（跨图表支持矩阵、Statistic 单位+customUnits 配对、Percent 与 Percent100 陷阱）。 - 从 chart-config.md 的 "Available Units" 小节中移除重复的 Percent/Percent100 引用块；替换为 一行项目符号，链接到规范的单位配置表。 - metrics-mpl.md 的单位处理部分从完整重述相同规则缩减为 仅指标特定的工作流（指标 元数据然后 unit-for 然后拼接）。跨图表关注点链接到 chart-config。 - metrics-mpl.md 的百分比和比率部分类似缩减：保留 MPL `| map * 100` 步骤（指标特定部分）并链接出去 以了解图表渲染规则。 - 从 metrics-mpl.md 删除 "When to Use What" 表；它 重复了 chart-config 的单位配置表。 自包含性： - metrics-mpl.md 中新增 "Choosing a Query Shape" 小节，内联 Gauge/CounterMonotonic/Histogram 预聚合规则。创作检查清单的第 4 步 不再为此指向 query-metrics 技能；building-dashboards 读者不再需要加载第二个技能 来从指标元数据塑造 MPL 管道。 SKILL.md 表面： - Metrics/MPL Blueprint Snapshots 小节：将两个密集的 单位处理项目符号合并为一个简短项目符号，链接到 参考。Trends 小节同样。理由存在于 参考中，而不是 SKILL 项目符号列表中。 - 故障排除表：将两个新的百分比行各缩减为一行。 净变化：5 个文件 +46/-77。metrics-mpl.md 因 内联查询形状小节而增长，但单位内容整体缩减。 Co-authored-by: Claude

docs(dashboards): 添加单位处理指导和 unit-for 辅助脚本 基于指标的仪表板图表需要其单位配置匹配 指标的 UCUM/OTel 单位元数据，但该技能没有关于 如何将二者相互转换的指导，且图表级单位字段 （`unit` 枚举与 `customUnits` 后缀）在不同图表 类型中行为不同，而这些差异未被记录。 scripts/metrics/unit-for: - 新辅助脚本，将 UCUM/OTel 单位字符串映射到图表单位 JSON 块（`{"unit": "..."}` 或 `{"unit": "Auto", "customUnits": "..."}`）， 可直接拼接到图表对象中。 - 识别常见的时间、字节、字节速率、百分比和货币 代码；其他任何内容（包括 故意有歧义的 `m`、`B` 和 `1`）回退到 `customUnits`。 - tests/unit-for.sh 中的测试覆盖已识别的映射和 回退行为。 reference/metrics-mpl.md: - 新增 "Unit Handling" 小节，描述工作流： metrics-info -> unit-for -> 拼接到图表。 - 映射参考表和 "deliberately not auto-mapped" 说明。 - "Percentages and ratios" 小节，涵盖 OTel 0-1 分数 陷阱：`Percent` 枚举不会自动相乘，因此在 MPL 中乘以 100 并使用 `Percent100` + `customUnits: "%"` 代替。 - 添加工作流步骤，用于预先读取指标元数据。 reference/chart-config.md: - 新增 "Unit Configuration (Cross-Chart)" 小节，记录哪些 图表类型接受 `unit`（仅 Statistic）与 `customUnits`（所有 数据图表），以及 Statistic 需要两个字段一起才能 渲染带后缀的值（例如 `99.5%`）。 - Statistic 选项表澄清 `unit` 仅适用于 Statistic。 - TimeSeries / Pie / Heatmap 小节注明 `customUnits` 支持并 交叉链接到单位配置表。 SKILL.md: - Snapshots 和 Trends 小节增加项目符号，指向新的单位 工作流和百分比 / 非 Statistic 图表注意事项。 - 故障排除表增加两行，针对两种常见的百分比 渲染失败模式。 Co-authored-by: Claude

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），但该技能忽略了这三者。代理只能猜测查询形状， 并经常产生语义错误的查询（例如对累积单调计数器求平均 而不是先对其求速率）。 在不添加任何新服务器契约的情况下使元数据成为一等公民： 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 步重命名为 'Discover and classify metrics' 并指向 新的元数据小节。 - 新增 'Choosing a query shape from metric metadata' 小节，包含 每种类型/时间性组合的经验规则。故意不 枚举具体 MPL 操作符名称——指向 `metrics-spec` 作为事实来源（最近观察到的 Option 规范漂移 支持保持 SKILL.md 与操作符无关）。 - 'Reporting results' 指导：附加 `unit`，在单位不匹配时警告。 - 发现小节记录新标志和子命令。 - find-metrics 小节促使代理在组合查询前为每个 候选获取元数据。 skills/building-dashboards/scripts/metrics/metrics-info: - 从规范副本逐字节相同地重新供应。 已针对实时部署验证（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 的新 'Passing parameter values' 小节中记录 API 契约、请求正文形状和 CLI 调用。注意 可选参数（声明语法参见 `metrics-spec`）可以 省略，而必需参数缺失会引发 HTTP 400。在 building-dashboards/reference/metrics-mpl.md 中添加 一个指向新小节的指针（无内容重复）。将 metrics-query 逐字节相同地重新供应到 building-dashboards/scripts/metrics/。 已针对实时 MPL 规范和实时部署验证： - 键命名和原样字面量转发与规范匹配（查询 参数小节）； - JSON `params` 正文形状端到端工作（参数化与字面量 对照返回相同序列）； - 必需参数缺失返回 HTTP 400 并给出清晰消息； - 示例中的类型名称匹配规范的小写 `string` 和大写 `Duration` / `Dataset` / `Regex` 约定。 Co-authored-by: Claude

合并拉取请求 #51，来自 axiomhq/add-agent-user-agent 添加 User-Agent 头以识别技能驱动的代理流量

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

docs: 精简仪表板补丁 README

building-dashboards: 添加图表补丁辅助脚本

docs(dashboards): 要求使用 $__interval 进行指标图表对齐 指标仪表板面板必须对齐到仪表板提供的 $__interval 变量，而不是固定窗口。仪表板运行时 根据活动时间范围和面板宽度替换 $__interval， 因此单个图表从 5 分钟到 30 天视图都保持可用；固定的 'align to 1m' 对长时间范围过度解析，对短时间范围解析不足。 变更： - SKILL.md：在 Metrics/MPL Blueprint 中添加醒目的 ALIGNMENT RULE 提示，附 do/don't 示例，记录在 query.apl 中 不需要 'param $__interval: Duration;' 声明 （运行时注入它），并划出两个明确例外 （通过 scripts/metrics/metrics-query 预验证，以及真正 稀疏的指标，此时固定更宽窗口是合适的）。更新 Trends 和 Entity State 项目符号以及规范 JSON 示例。 - reference/metrics-mpl.md：更新规范 JSON 形状并添加 强制该规则的检查清单步骤。 - reference/chart-config.md：更新 Metrics Query 示例。 证据： - MPL 规范（axiom/mpl/spec.md）将 'param $__interval: Duration;' 记录为规范查询参数模式。 - Grafana 数据源（axiomhq-metrics-datasource）注入一个 声明 $__interval 和 $__rate_interval 的前导。 - 实时 staging 仪表板 9e80ba6f-bf5a-4852-ba40-96346967e7ae 在 13/16 个指标图表中使用 'align to $__interval'，且渲染时存储的 query.apl 中没有任何可见的 'param' 声明，证明 Axiom 原生仪表板运行时会自动注入该参数。 - 裸 _apl 端点在没有 'param' 声明时拒绝 $__interval， 这证明了文档化的预验证例外。 Co-authored-by: Claude

fix(dashboards): 指标 mpl 图表查询需要 'apl' 和 'metricsDataset'

更新 Signed-off-by: Heinz N. Gies

修复仪表板链接并避免 jq 保留字

处理审查反馈：将供应的 resolve-url 与上游缓存同步 向 building-dashboards/scripts/metrics/resolve-url 添加 1 小时基于文件的缓存 以匹配上游 query-metrics/scripts/resolve-url 实现。 这避免了 metrics-info、metrics-query 和 metrics-spec 每次调用时 对 /v1/datasets 的额外 HTTP 往返。 Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-019cffcd-a1b4-741c-aa0d-53acb1b289bd

fix(building-dashboards): 向供应的 axiom-api 添加 HTTP 错误处理 与上游 query-metrics/scripts/axiom-api 同步：添加 -w 标志以 捕获 HTTP 状态码并在非 2xx 响应时以错误退出。 没有这个，API 错误会静默变成 stdout，导致下游 jq 解析失败令人困惑。 处理 PR #36 上的 cursor[bot] 审查反馈。 Thread: https://ampcode.com/threads/T-019cffb7-8034-739c-93e8-5c6647c6b19b Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-019cffb7-8034-739c-93e8-5c6647c6b19b

fix(building-dashboards): 从供应的 axiom-api 中移除内部 API 路径引用 从注释和守卫子句中移除 /internal/dashboards 和 /v2/user 引用。 这些是与数据/指标 API 脚本无关的内部路由，会泄露内部实现细节。 处理 PR #36 上的 cursor[bot] 审查反馈。 Thread: https://ampcode.com/threads/T-019cffb7-8034-739c-93e8-5c6647c6b19b Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-019cffb7-8034-739c-93e8-5c6647c6b19b

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

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

feat(building-dashboards): 添加带 Accept 头 内容协商的指标脚本 将指标脚本（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

移除私有仪表板