cloud-monitoring-list-time-series-request

Cloud Monitoring ListTimeSeries リクエスト生成ツール

このスキルを使用すると、任意の Cloud Monitoring メトリック記述子を、有効で本番環境ですぐに使用できる ListTimeSeries REST API クエリパラメーター（name、filter、interval.startTime、interval.endTime、aggregation.*、view）に変換できます。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用に関する帰属情報をお読みください。ターミナルから直接実行するコマンド（生成されたスクリプト、Terraform、またはユーザーコード内のコマンドは対象外）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-list-time-series-request)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:cloud-monitoring-list-time-series-request) を追加してください。

重要なルール

• プロジェクト ID の確認は必須：GCP プロジェクト ID がユーザーのプロンプト、入力ペイロード、または環境コンテキスト（gcloud config get-value project など）に含まれていることを必ず確認してください。プロジェクト ID がなく、特定できない場合は、ListTimeSeries リクエストを生成または実行する前に、必ずユーザーに確認してください。プロジェクト名にプレースホルダーを使用しないでください。

ワークフロー

メトリックのメタデータを確認する

1. 提供済みのメトリックメタデータを最初に使用する：ユーザーのプロンプトに metric.type、metricKind、valueType、リソースタイプ、ラベルキーなどのメトリックメタデータがすでに含まれている場合は、API ツールを呼び出さず、それらの値を直接使用してください。
2. 不足しているメタデータを調べる：metric.type、metricKind、valueType を含む正確なメトリック記述子が不足している、または詳細が不十分な場合は、次のいずれかの方法で対象メトリックの記述子を特定してください。
   • 曖昧なクエリ：VM の CPU 使用率を尋ねる場合など、プロンプトが曖昧な場合は、まず cloud-monitoring-metric-selection スキルを使用して具体的なメトリックタイプを特定してください。
   • 既知のメトリックタイプ：compute.googleapis.com/instance/cpu/utilization など、具体的なメトリックタイプ名がすでにわかっていて、その記述子が必要な場合は、list_metric_descriptors MCP ツールを呼び出してください。このツールがない場合は、cloud-monitoring-metric-selection スキルを参照して Cloud Monitoring MCP サーバーを設定してください。
   • フォールバック：MCP ツールを設定できない場合は、Cloud Monitoring API を直接呼び出してください。
3. 主要なフィールドを特定する：取得した記述子から、スキーマの主要な属性を特定してください。
   • type：Cloud Monitoring のメトリックタイプ文字列です。
   • metricKind：GAUGE、DELTA、または CUMULATIVE です。
   • valueType：INT64、DOUBLE、DISTRIBUTION、または BOOL です。
   • monitoredResourceTypes：互換性のある resource.type 文字列です。例：["cloudsql_database", "cloudsql_instance"]。複数のリソースタイプが列挙されている場合は、ユーザーのリクエストで指定された対象の粒度に一致する resource.type を選択してください。

---

Monitoring フィルターの作成

filter パラメーターは、クエリを単一の metric.type と、任意のリソースラベルおよびメトリックラベルに制限する、Cloud Monitoring 構文の必須文字列です。

1. 単一のメトリックタイプへの制限：すべての filter では、等価演算子を使用した metric.type 節を正確に 1 つ指定する必要があります。例：

   • metric.type = "compute.googleapis.com/instance/cpu/utilization"

2. 監視対象リソースタイプのフィルター：対象リソースの粒度がわかっている場合は、サービス間でメトリックタイプやサブリソースが重複するのを防ぐため、resource.type フィルターを含める必要があります。例：

   • metric.type = "cloudsql.googleapis.com/database/cpu/utilization" AND resource.type = "cloudsql_database"

3. ユーザー指定のリテラルと ID の保持：ユーザーが指定したリソース名、ID、ゾーン、プロジェクトのパラメーターは、変更せずに使用する必要があります。明示的に要求されない限り、メトリックメタデータの検出時に見つかったアクティブなリソースで、ユーザー指定の識別子を上書きまたは置き換えてはなりません。

4. ラベルタイプのプレフィックス指定：

   • インスタンス ID、ゾーン、プロジェクト、データベース ID、サブスクリプション ID などのリソースレベルのディメンションには、resource.labels. プレフィックスを付けます。例：
     • resource.labels.instance_id = "123456789"
     • resource.labels.database_id = "my-project:my-instance"
   • 状態、コマンド、レスポンスコード、メトリックに保存されているインスタンス名のメタデータなどのメトリックレベルのディメンションには、metric.labels. プレフィックスを付けます。例：
     • metric.labels.state != "free"
     • metric.labels.instance_name = "instance-1"

5. リソース名と ID の解決：

   • ユーザーが "instance-1" のような人間が読める GCE VM インスタンス名を指定していても、resource.labels.instance_id が数値 ID を想定している場合は、metric.labels.instance_name = "instance-1" または metadata.system_labels.name = "instance-1" を使用してフィルタリングする必要があります。
   • resource.metadata.name や resource.metadata.* は使用しないでください。このプレフィックスは Cloud Monitoring のフィルター構文では無効です。
   • リソースタイプで文字列 ID が明示的に使用されていない限り、文字列のインスタンス名を resource.labels.instance_id に直接割り当てないでください。

6. データベース識別子ラベル：Cloud SQL と Spanner の database_id、BigQuery の dataset_id などのデータベースラベルでは、<project_id>:<instance_name> 形式の複合キーを使用します。例： resource.labels.database_id = "my-project:foo"。

7. Ops Agent メトリックの状態ラベルフィルタリング：agent.googleapis.com/memory/percent_used および agent.googleapis.com/disk/percent_used メトリックでは、metric.labels.state != "free" を使用する必要があります。metric.labels.state = "used" でフィルタリングしてはなりません。

---

集約構造の選択

メトリクスのプロパティと可視化の目的に応じて、perSeriesAligner、crossSeriesReducer、groupByFields、alignmentPeriod を選択します。

1. 集約リファレンスの確認：すべてのリクエストの aggregation クエリパラメーターに、perSeriesAligner と crossSeriesReducer の両方を必ず含めてください。メトリクスの Metric Kind と Value Type の組み合わせに適した正確な perSeriesAligner と crossSeriesReducer の組み合わせを選び、利用率メトリクス、カウンター、分布、ならびに state != "free" でフィルタリングしたメモリなどの状態ベースのゲージに関する必須の SRE ルールを適用するには、Cloud Monitoring ListTimeSeries Basic Aggregations Reference を読み、その指示に従ってください。
2. グループ化フィールドとリソースの粒度：crossSeriesReducer に REDUCE_NONE 以外を指定する場合は、保持するラベルを正確に列挙してください。VM、データベース、サブスクリプションなどの複数インスタンスを持つリソースをクエリする場合は、主要なリソース識別子を groupByFields に含めてください。たとえば、VM には resource.labels.instance_id、データベースには resource.labels.database_id を使用します。これにより、個別のリソースストリームが単一のグローバルな集計にまとめられるのを防げます。
3. アラインメント期間の決定：endTime から startTime を引いてクエリのルックバック期間を計算し、startTime が endTime より前であることを確認します。endTime <= startTime の場合は、期間を計算する前にエラーとして通知してください。Cloud Console のデフォルトの細かい粒度の基準に従って alignmentPeriod を設定します。
   • 期間 <= 110 分：alignmentPeriod = "60s" に設定します。
   • 期間 <= 23 時間：alignmentPeriod = "300s" に設定します。
   • 期間 <= 6 日：alignmentPeriod = "3600s" に設定します。
   • 期間 <= 23 日：alignmentPeriod = "10800s" に設定します。
   • 期間 <= 80 日：alignmentPeriod = "21600s" に設定します。
   • 期間 <= 180 日：alignmentPeriod = "43200s" に設定します。
   • 期間 <= 350 日：alignmentPeriod = "86400s" に設定します。
   • 期間 <= 500 日：alignmentPeriod = "172800s" に設定します。
   • 省略ルール：perSeriesAligner が ALIGN_NONE に設定されている場合に限り、alignmentPeriod を省略します。

---

有効なリクエストの形式

生成した ListTimeSeries REST クエリパラメーターを提示します。たとえば、次のようになります。

{
  "name": "projects/<project_id>",
  "filter": "metric.type = \"<metric_type>\" AND resource.type = \"<resource_type>\"",
  "interval": {
    "startTime": "<iso_8601_start>",
    "endTime": "<iso_8601_end>"
  },
  "aggregation": {
    "alignmentPeriod": "60s",
    "perSeriesAligner": "ALIGN_RATE",
    "crossSeriesReducer": "REDUCE_SUM",
    "groupByFields": [
      "resource.labels.zone"
    ]
  },
  "view": "FULL"
}

• 集約の要件：集約の選択時に決定した perSeriesAligner、crossSeriesReducer、alignmentPeriod および省略可能な groupByFields の値を aggregation パラメーターに設定します。
• インターバルの要件：startTime と endTime は、"YYYY-MM-DDTHH:MM:SSZ" などの有効な RFC 3339 および ISO 8601 のタイムスタンプでなければなりません。ユーザーが明示的に指定していない場合は、現在の時刻を終了時刻とする 1 時間のルックバック期間を動的に計算します。この場合、endTime は現在の時刻、startTime は 1 時間前です。例にある静的な日付をハードコードしてはいけません。
• アラインメント期間の要件：上記の対応表を使用し、endTime から startTime を引いたルックバック期間に基づいて alignmentPeriod を決定します。デフォルトの 1 時間のルックバック期間では、alignmentPeriod は "60s" です。
• ビューの要件：時系列データポイントが必要な場合は "FULL"、メタデータと系列の識別情報のみを調べる場合は "HEADERS" を必ずデフォルトとして使用します。

---

list_timeseries MCP ツールでリクエストを検証する

最終出力を返す前に、生成したリクエストパラメーターをライブの Cloud Monitoring テレメトリに対して必ず検証してください。list_timeseries MCP ツールを呼び出し、生成したすべてのクエリパラメーター（name、filter、interval、aggregation）を渡してください。検証時には、リクエストの構造を確認しながらレイテンシーとペイロードサイズを最小限に抑えるため、必ず view="HEADERS" を設定してください。API エラーがないレスポンスであれば、フィルターと集計の設定が有効であることを確認できます。

list_timeseries ツールを利用できない場合は、直接 API を呼び出してください。

---

参考資料

• Cloud Monitoring ListTimeSeries 基本集計リファレンス
• Cloud Monitoring の監視対象リソースタイプのリファレンス
• Cloud Monitoring のフィルター構文
• Cloud Monitoring REST API リファレンス：projects.timeSeries.list