cloud-monitoring-promql-query

Cloud Monitoring PromQL ジェネレーター

このスキルを使用すると、あらゆる Cloud Monitoring 指標タイプから有効な PromQL クエリを生成できます。このガイドでは、Cloud Monitoring の指標とリソースの記述子を PromQL の構造に対応付けることで、すべての Cloud Monitoring 指標タイプに対応します。

クレジット表記

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

ワークフロー

プロジェクト ID の解決（重大かつ処理をブロックします）

他の操作（コードの検索、リファレンスの読み取り、検証の実行など）を行う前に、Google Cloud プロジェクト ID を利用できるか必ず確認してください。

1. プロンプト／ペイロードを確認：ユーザーのプロンプトまたは入力にプロジェクト ID が含まれているか確認します。
2. 環境を確認：プロンプトにプロジェクト ID が含まれていない場合、環境から解決するために、必ず gcloud config get-value project を実行してください。
3. 確認を求める（処理をブロックします）：プロンプトにプロジェクト ID が含まれておらず、gcloud コマンドが失敗する、空の文字列を返す、または利用できない場合は、ただちに停止してください。PromQL クエリを生成したり、検証スクリプトを実行したり、プレースホルダー（YOUR_PROJECT_ID など）を使用したりしないでください。処理を続行せず、ユーザーにプロジェクト ID の提示を求めてください。

指標とリソースの記述子を調査

1. 提供された記述子を優先して使用：ユーザーのプロンプトに指標の記述子の詳細（metric.type、metricKind、valueType、monitoredResourceTypes など）や、特定のリソースフィルター値がすでに含まれている場合は、Cloud Monitoring API を呼び出さず、それらの値を直接使用してください。
2. 不足している記述子を調べる：正確な指標の記述子（metric.type、metricKind、valueType）が不足している、または具体性に欠ける場合は、次のいずれかの方法で対象の指標タイプの記述子を解決してください。
   • 曖昧なクエリ：プロンプトが曖昧な場合（例："VM CPU usage"）は、まず cloud-monitoring-metric-selection スキルを使用して、具体的な指標タイプを特定します。
   • 既知の指標タイプ：具体的な指標タイプ名（例：compute.googleapis.com/instance/cpu/utilization）がすでに分かっているものの、その記述子が必要な場合は、google-cloud-monitoring:list_metric_descriptors MCP ツールを呼び出します。このツールがない場合は、Cloud Monitoring MCP サーバーの設定について cloud-monitoring-metric-selection スキルを参照してください。
   • 代替手段：MCP ツールを設定できない場合は、Cloud Monitoring API を直接呼び出してください。
3. 主要なフィールドを特定：取得した記述子から、スキーマの主要な属性を4つ特定します。
   • type：Cloud Monitoring の指標タイプ文字列。
   • metricKind：GAUGE、DELTA、または CUMULATIVE。
   • valueType：INT64、DOUBLE、DISTRIBUTION、または BOOL。
   • monitoredResourceTypes：リソースのスコープ指定とグループ化に必要な、互換性のある resource.type 文字列。

リソースフィルターと検出プロトコルの解決

特定のリソースインスタンスでデータをフィルタリングするには、次のリソースルールと検出プロトコルを適用します。

1. 監視対象リソースのフィルター: サービス間でメトリクス名が重複するのを防ぐため、クエリには必ず monitored_resource="<type>" フィルターを含めてください。

   • 例: monitored_resource="gae_app"

2. ユーザー指定のリテラルを保持（重要）: ユーザーのプロンプトで指定されたリソース名、名前空間、IDを必ずそのまま使用してください。ユーザーがアクティブなリソースの検索を明示的に依頼していない限り、Cloud Monitoring の検出で見つかったアクティブなリソース名でこれらの値を上書きまたは置き換えないでください。テレメトリーの検出は、メトリクス型名とラベルキーの特定にのみ使用し、ユーザー入力の上書きには使用しないでください。

3. リソース識別子のマッピング:

   • 直接的で具体的なキー: 利用可能な中で最も具体的なリソース識別子を使用してください。例: version_id、cluster_name。
   • 名前から ID への解決: ユーザーがリソースの名前（例: "instance-1"）でフィルタリングしている一方、リソーススキーマが数値 ID（例: instance_id）を使用している場合は、数値 ID ラベルではなく、PromQL の文字列名ラベルを使用してください。例: instance_name、metadata_system_name。
   • 複合識別子: 階層型識別子を持つリソース（Cloud SQL データベースなど）の場合は、フィルターを単一の複合キーとして指定してください。これらを個別の project_id とサブリソースラベルに分割しないでください。例: database_id="{project_id}:{instance_name}"。

4. リソースラベルの検出: google-cloud-monitoring:list_metric_descriptors ツールが返すのは、メトリクス固有のラベルのみです。監視対象リソースのラベルスキーマが不明な場合は、Cloud Monitoring v3 REST API（projects.monitoredResourceDescriptors.get）からリソース記述子を直接取得してください。

   TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null || gcloud auth print-access-token)
   curl -s -H "Authorization: Bearer ${TOKEN}" \
   "https://monitoring.googleapis.com/v3/projects/{project_id}/monitoredResourceDescriptors/{monitored_resource_type}"
   

   HTTP 200 OK の応答では、そのリソースに正確に対応するリソースラベルキーを含む labels 配列を持つ MonitoredResourceDescriptor オブジェクトが返されます。

集約構造とデフォルトの選択

クエリ構造と集約関数（rate、histogram_quantile、sum、avg など）は、メトリクスの型と可視化方法によって異なります。

1. リファレンスを参照: Cloud Monitoring のプロパティ（Metric Kind、Value Type、Aligner、Reducer）を PromQL の構造に対応付けるための唯一の信頼できる情報源として、 Cloud Monitoring から PromQL への基本集約リファレンス を参照してください。
2. SRE の集約と可視化のルール:
   • 比率／パーセンテージの使用率メトリクス（CPU % やメモリ上限使用率など）を、リソースインスタンス間で合計または平均しないでください。代わりに、集約せず（生のメトリクスのまま）にするか、インスタンスごとにグループ化するか、topk(30, avg_over_time(...)) でラップしてください。
   • 状態ラベルのフィルタリング（重要）: {state!="free"} が必要なのは、agent.googleapis.com/memory/percent_used と agent.googleapis.com/disk/percent_used のメトリクスのみです。{state="used"} ではフィルタリングしないでください。

クエリの形式と検証

PromQL クエリを提示する前に、リンターを使用して検証してください。

Python の依存関係

検証スクリプト（scripts/validate_promql.py）を実行する前に、必要な Python 依存関係をインストールしてください。

python3 -c "import promql_parser" || pip install promql-parser

検証手順

1. 形式の制約:
   • メトリクス名の正規化: 次の手順で、Cloud Monitoring のメトリクスタイプを PromQL のメトリクス名に変換します。
     1. ドメインとパスを分割する: Cloud Monitoring のメトリクスタイプを最初のスラッシュ（/）で分割し、ドメインとパスを分けます。
        • 例: storage.googleapis.com/network/received_bytes_count -> ドメイン storage.googleapis.com、パス network/received_bytes_count
     2. ドメインを正規化する: ドメイン内のすべてのピリオド（.）をアンダースコア（_）に置き換えます。
        • 例: storage.googleapis.com -> storage_googleapis_com
     3. パスを正規化する: パス内のすべてのピリオド（.）とスラッシュ（/）をアンダースコア（_）に置き換えます。
        • 例: network/received_bytes_count -> network_received_bytes_count
     4. コロンで結合する: 正規化したドメインと正規化したパスをコロン（:）で結合します。
        • 例: storage_googleapis_com:network_received_bytes_count
     5. ネイティブの Prometheus メトリクス: メトリクスタイプにスラッシュがない場合は、そのまま使用します。
        • 例: up -> up、http_requests_total -> http_requests_total
     6. 分布のサフィックス: メトリクスの valueType が DISTRIBUTION の場合、正規化した名前の末尾に _bucket を追加します。
        • 例: cloudfunctions.googleapis.com/function/execution_times -> cloudfunctions_googleapis_com:function_execution_times_bucket
   • 最終的なクエリがコメントのない1行（# または // がない状態）であることを確認します。Cloud Monitoring のクエリ変換では空白が折りたたまれるため、コメントの後ろにあるコードが無視されたり、解析エラーが発生したりする可能性があります。
   • グループ化句の構文: グループ化句（by (label) など）は、集約演算子（sum、avg、min、max、count など）の後にのみ置いてください。メトリクスセレクターの直後にグループ化句を置かないでください。
     • 誤り: metric{...} by (label)
     • 正しい例: sum(rate(metric{...}[5m])) by (label)
   • フェンス付き出力コードブロック: 最終回答では、検証済みの PromQL クエリを必ずフェンス付きの promql コードブロックで囲んでください。
2. リンターによる検証:
   • 生成したすべてのクエリを1回のバッチで検証します: python3 <path_to_skill>/scripts/validate_promql.py --query '<q1>' '<q2>'
   • 検証に失敗した場合は、 PromQL エラー回復ガイドを読み、よくある型の不一致や構文エラーを診断して修正してから、処理を繰り返してください。

参考資料

• Cloud Monitoring PromQL 基本集約リファレンス
• Cloud Monitoring PromQL エラー回復ガイド
• Cloud Monitoring PromQL ドキュメント
• Cloud Monitoring 監視対象リソースタイプのリファレンス