metrics-chart

metrics-chart

将指标查询响应转换为多序列折线图。

输入是 metrics v2 或 v3 格式的已保存 {metadata, series} 响应。对于 MCP 结果，请调用 queryMetrics 并设置 truncate: false，然后将其 structuredContent 保存为输入 JSON。默认 CSV 预览可能会省略序列和样本。

TL;DR

# From a file, stdout picks the best renderer for your terminal:
python3 scripts/metrics_chart.py response.json

# Read the same saved response from stdin:
python3 scripts/metrics_chart.py < response.json

# Force a zero-dependency ASCII chart (always works, anywhere):
python3 scripts/metrics_chart.py --format ascii response.json

先聚合。 只有序列数量不多时，图表才易于阅读。 最清晰的结果来自查询本身已将数据分组／聚合为少数几条线 （例如，按 status 分组，而不是按 pod 分组）。此工具的序列 缩减功能（如下所述）是针对高基数结果的安全保障，不能 替代在查询中进行聚合。

输入格式（metrics v2/v3）

{
  "metadata": {
    "group_keys": ["code", "method"],
    "warnings": [],
    "unit": "ms",
    "custom_unit": "millisec"
  },
  "series": [
    {
      "metric": "http_requests",
      "tags": { "code": 200, "method": "GET", "path": "/" },
      "start": 1750753164,
      "resolution": 60,
      "data": [420.0, 42.0, 30.0, 9.0, 15.0, 18.0]
    }
  ]
}

字段	含义
metadata.group_keys	查询分组所用的标签 → 用于构建图例标签。
metadata.warnings	以 ⚠ 说明文字的形式显示在图表下方。
metadata.unit	y 轴的规范单位（ms、bytes 等），除非 ignore_unit 为 true。
metadata.custom_unit	y 轴的人类可读标签；提供时会覆盖 unit。
metadata.ignore_unit	忽略 unit；仅在明确提供 custom_unit 时应用它。
series[].start	data[0] 的 Unix 秒时间戳（UTC）。
series[].resolution	每个点的间隔秒数；x[i] = start + resolution*i（均匀间隔）。
series[].data	Y 值；null = 间隙（折线会中断，不会绘制为 0）。

解析器还接受 v2/v2a（形状相同，但每个序列额外包含一个 summary， 该字段会被忽略）以及 v0/v1 裸数组格式，因此也可以输入较旧的响应。

行为

• 标签由 group_keys 的值以 | 连接而成 → 200 | GET （而不是 code=200,method=GET）。没有 group_keys 时，则回退到 k=v 标签。
• 默认使用本地时间坐标轴；可通过 --tz UTC 或 --tz Europe/Berlin 覆盖。
• 间隙：null 点会中断折线。
• 序列缩减（除非指定 --all），按以下顺序进行：
  1. 合并重叠序列：折线基本重合的序列（在 --eps 范围内，默认值为 y 轴范围的 2%）会合并；保留最显著的序列。
  2. 按峰值排序，保留前 N 个（--top，默认值为 8）。
  3. 图例会显示已舍弃的序列数量，例如： 显示 8 个，共 30 个序列（5 个重叠，17 个较低／隐藏），并附上 查询聚合提示。

输出格式

--format auto（默认值）会根据运行环境选择最佳渲染方式：

• 安装了 gnuplot 且终端支持图像（Kitty／Ghostty、iTerm2）时，显示内嵌图像；
• 输出通过管道传递或被捕获时（例如 AI Agent 框架），如果安装了 gnuplot，则生成 PNG 文件并附上“显示此文件”的指令——随后由 Agent 显示该文件；
• 在普通终端中，或 gnuplot 不可用时，显示 ASCII 图表。

使用 --format 指定后端：

--format	需要	输出
auto	—	内嵌图像；否则，在输出经管道传递时生成 PNG 文件并附上显示指令；再否则显示 ASCII 图表
ascii	无	Unicode Braille 折线图；可在任何终端、文本记录或 CI 日志中渲染。
png	gnuplot	PNG；在内嵌终端（Kitty/iTerm2）中显示，或写入 --output／临时文件。
svg	gnuplot	SVG 写入 --output 或临时文件（会打印路径）。
sixel	gnuplot	将 sixel 流写入标准输出（适用于支持 sixel 的终端）。

如果请求图像格式但未安装 gnuplot，程序会打印提示并回退到 ASCII 图表——不会直接失败。

在 AI Agent / harness 中使用

终端 harness（例如 pi）会折叠工具输出，且不会重新渲染内联 ANSI，因此 ASCII 图表会以单色显示并被折叠。**优先使用图片：**渲染 文件并让 Agent 显示。使用 --format auto（默认值）时，只要输出被管道重定向且已安装 gnuplot，就会自动执行此操作——该 skill 会写入 PNG 并打印：

metrics-chart: wrote image to /tmp/metrics-chart-XXXX.png
→ Display this file to the user with your image tool (e.g. read it); do not paste its contents.

接下来，Agent 应显示该文件（其图像/read 工具会以内联方式渲染，彩色显示且不会折叠）。若要指定路径，请传入 --output chart.png。 不要将 PNG 字节或 ASCII 内容粘贴到聊天中。

选项

标志	默认值	含义
--format	auto	auto/ascii/png/svg/sixel。
--tz NAME	local	x 轴的 IANA 时区；UTC 时使用 UTC。
--top N	8	折叠后显示的最大系列数；必须 >= 1。
--eps F	0.02	重叠阈值，占 y 轴范围的比例。
--all	off	绘制所有系列（禁用折叠和 top-N）。
--width / --height	auto	图表尺寸（ASCII 图表以字符单元格为单位，图片以像素为单位）。
--title TEXT	—	图表标题。
--output PATH	—	将 png/svg 写入 PATH，而不是临时文件。
--color / --no-color	auto	强制开启/关闭 ANSI 颜色（默认：TTY 下开启）。

依赖项

• 默认路径：无依赖。 纯 Python 3.9+ 标准库。ASCII 渲染器始终可用。
• 可选：gnuplot（一个系统二进制文件），用于生成 PNG/SVG/sixel。仅在需要高保真图片时安装。

为什么不用 graphviz？

graphviz（dot/neato）用于布局节点-边图；它没有数值/时间轴，也无法绘制随时间变化的 data[i]。此负载是数值时间序列，没有图结构，因此不适用 graphviz。gnuplot 才是正确的图像后端。（我们有意避免使用 matplotlib：通过 pip 安装它需要安装大量软件包。）

测试

cd scripts && python3 -m unittest test_metrics_chart -v

解析器测试以指标查询服务的 service/query/src/server/tests.rs 中的黄金字节为基准。