cloud-monitoring-chart-generation

Cloud Monitoring Chart Generation スキル（cloud-monitoring-chart-generation）

PromQL または ListTimeSeries JSON リクエストのペイロードとメトリクスのメタデータを、Server-Driven UI（SDUI）の有効な google.monitoring.dashboard.v1.Widget Protocol Buffer テキストプロトコルに変換します。生成されたテキストプロトコルは、Cloud Monitoring Dashboards API、gcloud CLI、または宣言型ダッシュボードプロビジョニングのパイプラインに取り込むことを想定しています。

重要

推奨 API と相互排他的なクエリ：

• API の優先順位：ユーザーが明示的に PromQL を要求した場合、またはメトリクスの計算に厳密に必要な場合を除き、ウィジェットには PromQL よりも ListTimeSeries（time_series_filter）設定を常に優先して生成してください。
• 相互排他：ウィジェットのデータセット time_series_query には、time_series_filter または prometheus_query のどちらか一方を含める必要があります。同じデータセットで両方のフィールドを同時に設定してはいけません。
• 厳密な引き継ぎ：指定された PromQL クエリまたは ListTimeSeries JSON の正確なフィルター文字列を、1 文字も変えずにコピーしてください。どのような場合でも、クエリを作成、書き換え、変更してはいけません。

注意

重要な実行規則と作業ディレクトリ規則：

• 作業ディレクトリを変更しないでください：作業ディレクトリはワークスペースのルートに保ってください。スキルのサブディレクトリに cd しないでください。
• 探索・検索禁止の規則：メトリクス記述子、PromQL クエリ、ListTimeSeries JSON ペイロード、単位、リソースタイプは、常に会話のコンテキスト内に存在します。メトリクスのメタデータを探したり、リポジトリの構造を調べたりするために、grep、find、ディレクトリ一覧、コードベースへのクエリなどのファイル検索ツールを決して実行しないでください。
• スクリプトの実行：同梱の Python スクリプトは、python3 を使用して直接実行してください。
• 出力の生成：assemble_widget_proto スクリプトは、並列実行時の衝突を防ぐため、一意の UUID ベースのファイル名を自動生成します。生成されたファイル名は、標準エラーに「Wrote widget textproto to:」という明確なプレフィックス付きで出力されます。Stage 4 での検証に使用する生成パスを抽出するため、この正確なプレフィックスをログから解析する必要があります。

帰属表示

必ずお読みください：gcloud、REST API、または MCP のコマンドを実行する前に、Usage Attribution を必ず読んでください。ターミナルで直接実行するコマンド（生成スクリプト、Terraform、ユーザーコード内での実行は除く）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-chart-generation)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:cloud-monitoring-chart-generation) を追加してください。

前提条件：環境のセットアップ

環境またはサンドボックスに必要な依存関係をインストールします。

pip install -r scripts/requirements.txt

ワークフローパイプラインに従う

[ Stage 1: compute_labels ]  --->  [ Stage 2: LLM Synthesis ]  --->  [ Stage 3: assemble_widget_proto ]
  Generates candidate labels         Formulates SemanticPlotSpec       Emits validated widget textproto

Stage 1：ベースライン候補の生成

Stage 1 を python3 で実行します。

# For PromQL:
python3 scripts/compute_labels.py \
  --metric_display_name "METRIC_DISPLAY_NAME" \
  --resource_type "RESOURCE_TYPE" \
  --metric_unit "UNIT" \
  --promql_query 'PROMQL_QUERY'

# For ListTimeSeries:
python3 scripts/compute_labels.py \
  --metric_display_name "METRIC_DISPLAY_NAME" \
  --resource_type "RESOURCE_TYPE" \
  --metric_unit "UNIT" \
  --filter_string 'metric.type="m"...' \
  --per_series_aligner "ALIGN_RATE" \
  --cross_series_reducer "REDUCE_SUM"

Stage 2：SemanticPlotSpec の予測（LLM）

ユーザーのプロンプト、PromQL または LTS クエリの構造、Stage 1 のベースライン候補を確認し、キーが 4 つの SemanticPlotSpec JSON オブジェクトを作成します。

1. title：titleCandidate を整え、簡潔で人が読みやすく、80 文字未満になるようにします。
2. yAxisLabel："Utilization"、"Bytes"、"Bytes Rate" のような、簡潔で人が読みやすい定量的な説明またはメトリクスの概念を設定します。単位は unitOverride によって自動的に表示されるため、"(%)"、"(/s)"、"(By)" などの単位記号や接尾辞をラベルに追加しないでください。
3. plotType：デフォルトは LINE です。ユーザーから要求された場合、または分布クエリの場合は STACKED_AREA を使用します。
4. unitOverride：以下の対応する規則を適用して求めた、Unified Code for Units of Measure（UCUM）の単位文字列を設定します。

時系列リスト（LTS）の単位戦略：

• 候補を信頼する：時系列リストのフローでは、Stage 1 が生成した unitOverrideCandidate をそのまま設定します。Stage 1 は ALIGN_RATE を数理的に処理して、たとえば By/s を生成し、ALIGN_PERCENT_CHANGE では % を強制し、ネイティブの正規化値を常に正しく出力します。

PromQL の単位戦略（LLM による手動オーバーライド）：

PromQL の式は、たとえば histogram_quantile(..., rate(...)) のように複数の演算を組み合わせられるため、最終的な単位は独自の意味的推論に基づいて決定してください。

• レート関数（rate(...)、irate(...)）：累積カウンターを秒あたりのレートに変換します。元のメトリック単位に /s を追加します。たとえば、元のメトリック単位が By の場合、rate(...) によって unitOverride: "By/s" になります。

  • 例外：rate() が histogram_quantile() の内部で評価される場合、出力はレートではなく、"s" のようなバケットの元の単位になります。

• 比率とパーセンテージ（100 * (A / B)）：同じメトリック単位同士の比率は、通常パーセンテージを表すため、unitOverride: "%" になります。

• 正規化：10^2.% は "%" に正規化します。

• 単位の保持：avg_over_time(...) や sum by (...) のような単純な集計関数では、基になるメトリック単位を変更せずに保持して出力します。

• 凡例テンプレート：legend_template フィールドは設定しないでください。意図的に省略されており、Cloud Monitoring のフロントエンドが実行時に複数列のテーブル凡例を動的にレンダリングします。

SemanticPlotSpec の例：

{
  "title": "VM CPU Utilization us-central1-a",
  "yAxisLabel": "Utilization",
  "plotType": "LINE",
  "unitOverride": "%"
}

Stage 3：Protobuf の組み立てと出力

Stage 3 を python3 で実行して、ウィジェットの textproto を生成して保存します。PromQL には --promql_query を、ListTimeSeries には --lts_request_json を使用します。

# For PromQL:
python3 scripts/assemble_widget_proto.py \
  --promql_query 'PROMQL_QUERY' \
  --spec_json 'SEMANTIC_PLOT_SPEC_JSON'

# For ListTimeSeries:
python3 scripts/assemble_widget_proto.py \
  --lts_request_json '{"filter": "...", "aggregation": {...}}' \
  --spec_json 'SEMANTIC_PLOT_SPEC_JSON'

重要

必須のファイル出力規約：出力ファイル名を推測したり、指定しようとしたりしないでください。スクリプトが重複しないことを保証したファイル名を自動生成し、標準エラー出力に表示します。標準エラー出力で明示的なプレフィックス「Wrote widget textproto to:」を検索して、このファイル名を確実に取得し、Stage 4 の検証でそのファイルを指定してください。

• 割り当てられたファイル名の確認：出力ファイルが保存されるたびに、スクリプトはファイルパスを標準エラー出力に記録します。Stage 4 の検証で指定できるよう、コマンド実行ログを確認して、作成された正確なファイル名を把握してください。
• テキストチャットの出力：生成された SDUI ウィジェットの textproto を、回答内の ```textproto コードブロックで囲んでください。

title: "..."
xy_chart {
  ...
}

検証と自動再試行

注意

ファイルの検証が通るまで、ターンを終了しないでください：1. 成果物を検証する：Stage 3 の生成ファイルに対して、検証スクリプトを実行します ：

   # PromQL グラフの場合：
   python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto" \
      --expected_promql_substring "SOME_IDENTIFYING_SUBSTRING_FROM_QUERY" \
      --expected_unit_override "UNIT_OVERRIDE_CANDIDATE"

   # ListTimeSeries（LTS）グラフの場合：
   python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto" \
      --expected_lts_filter_substring "SOME_IDENTIFYING_SUBSTRING_FROM_FILTER" \
      --expected_unit_override "UNIT_OVERRIDE_CANDIDATE"

   # データが変更されていないことを検証するため、識別用の部分文字列と Stage 1 の単位オーバーライド候補を必ず指定してください。
   
   # 重要：複数のメトリクスについて複数のグラフを生成した場合は、生成したファイルごとにこの検証スクリプトを必ず個別に実行し、すべてのグラフが正しいことを確認してください。

2. ファイルが見つからない場合、または検証に失敗した場合は自動再試行する：validate_chart がファイルの欠落または無効を報告した場合、スクリプトのパラメーターを確認して、Stage 3 を直ちに再実行します：

   python3 scripts/assemble_widget_proto.py \
     --promql_query 'PROMQL_QUERY' \
     --spec_json 'SEMANTIC_PLOT_SPEC_JSON'
   # 該当する場合は --lts_request_json を使用します
   

3. 検証と再試行：validate_chart を実行して、生成された textproto を検証します。スキーマまたは構文エラーが原因で検証に失敗した場合は、パラメーターを修正して最大 2 回まで再試行します。2 回再試行しても検証に失敗する場合は、再試行を中止し、検証エラーをユーザーに知らせて、可能な範囲で作成した textproto を提示します。

4. 実行エラーと検証エラー：validate_chart.py によるスキーマ／構文の検証エラーは、OS または環境による実行制限とは別のエラーです。後者は以下の サンドボックスでの適切なフォールバックで対処します。

サンドボックスで適切にフォールバックする

環境またはサンドボックスの制限により、compute_labels.py、assemble_widget_proto.py、または validate_chart.py を実行できない場合は、次の手順を実行します。

1. 実行できないスクリプトと、その理由をユーザーに伝えます。
2. 形式と単位に関するすべてのルールに従い、完全なウィジェット textproto を回答内に直接作成して出力します。
3. ユーザーが必要に応じてローカルでスキーマを実行・検証できるよう、単独で実行可能な python3 コマンドを含む **「ローカル検証」**セクションを用意します。

関連リンク

• ダッシュボード API
• Prometheus のドキュメント