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)" 并将 agent-skills/1.0 (skill:cloud-monitoring-list-time-series-request) 添加到 User-Agent 标头中。

关键规则

• 必须确认项目 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。

---

构造监控过滤器

filter 参数是一个必填字符串，使用 Cloud Monitoring 语法，将查询限制为单个 metric.type，并可选包含资源和指标标签：

1. 限制为单个指标类型：每个 filter 都必须使用相等运算符指定且仅指定一个 metric.type 子句。例如：

   • 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 的解析：

   • 如果用户指定了易读的 GCE VM 实例名称（例如 "instance-1"），但 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。请阅读并遵循 Cloud Monitoring ListTimeSeries 基本聚合参考， 根据指标的 Metric Kind 和 Value Type 组合选择准确的 perSeriesAligner 和 crossSeriesReducer 组合，并遵循适用于利用率指标、计数器、分布以及基于状态的 测量值（例如过滤条件为 state != "free" 的内存）的强制 SRE 规则。
2. 分组字段和资源粒度：当 crossSeriesReducer 指定为 REDUCE_NONE 以外的任何值时，请列出要保留的确切标签。查询虚拟机、数据库或订阅等多实例资源时，请在 groupByFields 中包含主要资源标识符。例如，虚拟机使用 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"
}

• 聚合要求：在 aggregation 参数中填入选择聚合时确定的 perSeriesAligner、crossSeriesReducer、alignmentPeriod 和可选的 groupByFields 值。
• 时间间隔要求：startTime 和 endTime 必须是有效的 RFC 3339 和 ISO 8601 时间戳，例如 "YYYY-MM-DDTHH:MM:SSZ"。如果用户未明确提供， 则动态计算以当前时间结束、向前回溯一小时的时间间隔，其中 endTime 为当前时刻， startTime 为一小时前。不得硬编码示例中的静态日期。
• 对齐周期要求：根据 endTime 减去 startTime 得到的回溯时长，使用上述映射确定 alignmentPeriod。对于默认的向前回溯一小时时间间隔，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