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

まず集約してください。 グラフは、系列が少数の場合にのみ読みやすくなります。 最も見やすい結果を得るには、クエリの段階で数本の線にグループ化／集約してください （例：pod ごとではなく、status でグループ化します）。このスキルによる 系列の削減（以下を参照）は、カーディナリティの高い結果に対する安全策であり、 クエリでの集約の代わりにはなりません。

入力形式（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. 凡例には、削除された系列数が次のように表示されます。 showing 8 of 30 series (5 overlapping, 17 low/hidden)。クエリで集約するためのヒントも表示されます。

出力形式

--format auto（デフォルト）は、実行環境に最適なレンダラーを選択します。

• gnuplot がインストールされており、ターミナルが画像に対応している場合（Kitty/Ghostty、iTerm2）は、インライン画像を表示します。
• 出力がパイプに渡されるかキャプチャされる場合（AI エージェントのハーネスなど）は、gnuplot がインストールされていれば PNG ファイルと「このファイルを表示してください」という指示を出力します。エージェントはそのファイルを表示します。
• 通常のターミナルでは、または gnuplot が利用できない場合は、ASCII を使用します。

--format でバックエンドを指定できます。

--format	必要なもの	出力
auto	—	インライン画像。パイプ経由の場合は PNG ファイルと表示指示。それ以外は ASCII。
ascii	なし	Unicode の点字折れ線グラフ。あらゆるターミナル、トランスクリプト、CI ログで表示できます。
png	gnuplot	PNG。インライン表示（Kitty/iTerm2）するか、--output／一時ファイルに書き込みます。
svg	gnuplot	SVG を --output または一時ファイルに書き込みます（パスを表示します）。
sixel	gnuplot	stdout に Sixel ストリームを出力します（Sixel 対応ターミナル向け）。

画像形式が要求されたときに gnuplot が見つからない場合は、メッセージを表示して ASCII に切り替えます。エラーで終了することはありません。

AI エージェント／ハーネスからの使用

ターミナルハーネス（pi など）はツールの出力を折りたたみ、インラインの ANSI を再描画しないため、ASCII グラフはモノクロで折りたたまれて表示されます。**画像を優先してください。**ファイルをレンダリングし、エージェントに表示させます。--format auto（デフォルト）を使うと、出力がパイプに渡され、gnuplot がインストールされている場合は自動的に実行されます。スキルは 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.

その後、エージェントはそのファイルを表示してください（画像をレンダリングする image／read ツールを使うと、カラーで折りたたまれずにインライン表示されます）。パスを指定するには、--output chart.png を渡します。PNG のバイト列や ASCII をチャットに貼り付けないでください。

オプション

フラグ	デフォルト	意味
--format	auto	auto／ascii／png／svg／sixel。
--tz NAME	ローカル	x 軸に使う IANA タイムゾーン。UTC には UTC を指定します。
--top N	8	折りたたみ後の系列の最大数。1 以上を指定してください。
--eps F	0.02	y 範囲に対する割合で指定する重なりのしきい値。
--all	オフ	すべての系列を描画します（折りたたみと上位 N 件への制限を無効化）。
--width / --height	自動	グラフのサイズ（ASCII はセル単位、画像はピクセル単位）。
--title TEXT	—	グラフのタイトル。
--output PATH	—	一時ファイルの代わりに PATH に PNG／SVG を書き込みます。
--color / --no-color	自動	ANSI カラーのオン／オフを強制します（デフォルトは TTY の場合オン）。

依存関係

• デフォルトの方法：なし。 Python 3.9 以降の標準ライブラリのみを使用します。ASCII レンダラーは常に動作します。
• オプション：gnuplot（システムバイナリ 1 つ）。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 の正解バイト列に固定されています。