cloud-monitoring-metric-selection

メトリクスの選択（サービスへのクエリとローカルでのキーワードフィルタリング）

このスキルを使用すると、最も関連性の高い Cloud Monitoring のメトリクス記述子を特定できます。API から対象サービスのすべてのメトリクス記述子を取得し、エージェントのコンテキスト内でキーワードに基づいてローカルにフィルタリングします。

クレジット表記

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

重要なルール

• 常にライブ API にクエリする：list_metric_descriptors MCP ツールを呼び出して、常に最新のメトリクス記述子を動的に取得する必要があります。
• プロジェクト ID とリソースパラメーターの確認は必須：API ツール（list_metric_descriptors など）を呼び出す前に、GCP プロジェクト ID がプロンプト、URI、または環境コンテキストで指定されていることを必ず確認してください。プロジェクト ID を特定できない場合、API クエリを実行する前に、ユーザーに確認するか、プロジェクト ID の提示を求めてください。未確認のデフォルト名やプレースホルダー名（mock-project、my-project-id、unused、YOUR_PROJECT_ID など）を使って API クエリを実行してはいけません。
• フォールバックの報告：API 呼び出しが失敗し、フォールバックの情報源（公開ドキュメントなど）を使用した場合は、エラー、フォールバックの情報源、ライブデータではないことによるリスク（情報が古い可能性、カスタムメトリクスの欠落、スキーマの不一致など）を必ず明示してください。

ワークフロー

ステップ 1：MCP の確認と自動設定

1. アクティブなツールセットに、list_metric_descriptors に一致するツール（google-cloud-monitoring:list_metric_descriptors、mcp_google-cloud-monitoring_list_metric_descriptors、または類似のパターンなど）があるか確認します。

2. 一意の URL で確認：正しい Cloud Monitoring ツールを呼び出していることを確認するため、基盤となる MCP サーバーの設定が https://monitoring.googleapis.com/mcp を参照していることを確認します。

3. ツールが見つからない場合：

   • ユーザーの環境にある MCP 設定ファイルを探します。一般的なパスを確認してください：

     • ~/.gemini/config/mcp_config.json
     • ~/.codeium/windsurf/mcp_config.json
     • cline_mcp_settings.json
     • claude_desktop_config.json

   • 次のサーバー設定を使って、設定ファイルを直接更新またはマージします。重要：mcpServers 内にある既存の MCP サーバーを保持するため、JSON オブジェクトをマージしてください。ファイルを上書きしてはいけません。

     "google-cloud-monitoring": {
       "url": "https://monitoring.googleapis.com/mcp",
       "authProviderType": "google_credentials",
       "enabledTools": [
         "list_metric_descriptors"
       ]
     }
     

   • google-cloud-monitoring MCP サーバーを設定したことをユーザーにはっきりと伝え、ツールを更新するために再起動するか、新しいチャットセッションを開始するよう求めます。それ以上ツールを呼び出さず、ターンを終了します。

Step 2: リクエストを分析し、キーワードを抽出する

1. プロジェクト ID と識別子を特定する：プロンプト、リソース URI、または環境コンテキストから、GCP プロジェクト ID とリソース識別子を確認します。 上記の重要なルールに従い、プレースホルダーのプロジェクト名は使用しないでください。

2. サービスのプレフィックスを特定する：対象の GCP サービスを、標準的なプレフィックス（compute、spanner、bigquery、storage など）に対応付けます。

3. メトリクスの概念を抽出する：ユーザーのプロンプトからメトリクスのキーワード（「CPU」、「memory」、「bytes scanned」、「latency」、「connections」など）を抽出し、検索文字列に対応付けます。

クエリ分析の例：

• ユーザープロンプト：「Cloud Storage バケットの書き込みスループットとリクエスト数を確認する」
• リソース URI： //storage.googleapis.com/projects/my-project/buckets/my-bucket
• サービスのプレフィックス：storage（storage.googleapis.com に対応）
• メトリクスのキーワード：write、throughput、request、count
• 対応する検索文字列：write、throughput、request_count、count

Step 3: list_metric_descriptors ツールでメトリクス記述子をクエリする

特定した各サービスプレフィックスについて、list_metric_descriptors MCP ツールを使用して、すべてのメトリクス記述子をクエリします（pageSize: 200 を使用）。Cloud Monitoring のフィルターでは、複数の metric.type 条件を OR で結合できないため、特定したサービスプレフィックスごとに個別のクエリを実行する必要があります（逐次または並列で実行できます）。

レスポンスに nextPageToken が含まれている場合は、そのプレフィックスの残りの記述子をすべて取得するまで、pageToken を指定して続けて呼び出す必要があります。

フィルターパターンの作成： 対象のサービスドメインを、適切なプレフィックス形式に対応付けます。

1. 標準的な Google Cloud サービス： starts_with("<service_prefix>.googleapis.com/")（bigquery.googleapis.com/、redis.googleapis.com/ など）。
2. Ops Agent（ゲスト OS）：starts_with("agent.googleapis.com/")（ゲスト OS のメモリ／ディスクのメトリクス用）。
3. Kubernetes／GKE ネイティブ：starts_with("kubernetes.io/")
4. Istio サービスメッシュ：starts_with("istio.io/")
5. Knative Serving／Autoscaler：starts_with("knative.dev/")
6. カスタム／外部メトリクス：starts_with("custom.googleapis.com/") または starts_with("external.googleapis.com/") を使用します。

ツール呼び出しペイロードの例： リクエストの対象が Spanner と Compute Engine の両方の場合は、次の 2 つのツール呼び出しを実行します。

1. Spanner のクエリ：

{
  "name": "projects/my-project-id",
  "filter": "metric.type = starts_with(\"spanner.googleapis.com/\")",
  "pageSize": 200
}

1. Compute Engine のクエリ：

{
  "name": "projects/my-project-id",
  "filter": "metric.type = starts_with(\"compute.googleapis.com/\")",
  "pageSize": 200
}

これらのペイロードを指定して、list_metric_descriptors ツールを呼び出します。

Step 4: ローカルでのフィルタリングとフォールバック手順

Step 3 で返されたすべての記述子をまとめ、LLM のコンテキスト内でローカルにフィルタリングします。

1. キーワードによるフィルタリング：記述子の type、displayName、description フィールドに対して、対象のメトリクスキーワード（「cpu」、「latency」など）で一致する項目を絞り込みます。
2. リソースとの対応確認：対象リソースの粒度に一致するラベルがメトリクスに含まれているか確認します（たとえば、データベースリソースが対象なら、database ラベルがあるかを確認します）。リソースタイプの文字列を動的に直接照合しようとしないでください。Cloud Monitoring のリソースマッピング（Spanner データベースが spanner_instance に対応付けられる場合など）は直感に反することがあります。

トラブルシューティングと API のフォールバック

ツール呼び出しが失敗する、タイムアウトする、または結果が空の場合は、次の方法を使用します。

• ケース A：API 構文エラー：エラーメッセージを確認し、フィルターの構文を修正して再試行します。
• ケース B：タイムアウト／レート制限：ページサイズを小さくして（pageSize: 20 など）一度だけ再試行します。
• ケース C：回復不能な失敗／空のリスト：
  1. 対象のサービスがプロジェクトで有効になっているか確認します。
  2. Google Cloud の公開ドキュメントを検索して、そのサービスの標準的なメトリクスを確認します。

ステップ 5：選択したメトリクスを出力する

各サービスドメインについて、ユーザーの意図に直接関連する主要なメトリクスのみを 5～15 件返してください。

選択したメトリクスは、サービスごと（つまり、サービスプレフィックスごとに 1 つのテーブル）にまとめ、整然とした Markdown テーブルで必ず報告してください。テーブルには、「Metric Type」、「Display Name」、「Description」、「Metric Kind」、「Value Type」、「Unit」、「Monitored Resource Types」の列を必ず含めてください。Cloud Monitoring の list_metric_descriptors ツール呼び出しのレスポンスオブジェクトから、各フィールドを対応するテーブル列に直接割り当ててください。

• Metric Type：type フィールドに割り当てます（例：spanner.googleapis.com/instance/cpu/utilization）。
• Display Name：displayName フィールドに割り当てます。
• Description：description フィールドに割り当てます。
• Metric Kind：metricKind フィールドに割り当てます（例：GAUGE、DELTA、CUMULATIVE）。
• Value Type：valueType フィールドに割り当てます（例：INT64、DOUBLE、DISTRIBUTION、BOOL）。
• Unit：unit フィールドに割り当てます（例：1、By、s、ms）。
• Monitored Resource Types：monitoredResourceTypes リストフィールドに割り当てます（例：["spanner_instance"]）。

出力テーブルの例：

Metric Type	Display Name	Description	Metric Kind	Value Type	Unit	Monitored Resource Types
spanner.googleapis.com/instance/cpu/utilization	Instance CPU Utilization	割り当て済み CPU のうち、現在使用中の割合です。	GAUGE	DOUBLE	1	["spanner_instance"]

リファレンスドキュメントとリンク

• Cloud Monitoring メトリクス一覧： GCP Metrics Documentation
• MetricDescriptor MCP ツールのリファレンス： MCP Tools Reference: monitoring.googleapis.com
• Monitoring フィルター構文ガイド： Monitoring Filters