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

工作流

解析项目 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-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 字符串，用于资源范围限定和分组。

解析资源筛选条件与发现协议

要按特定资源实例筛选数据，请应用以下资源规则和发现协议：

1. 受监控资源筛选条件：始终在查询中包含 monitored_resource="<type>" 筛选条件，以避免共享指标名称的服务之间发生冲突。

   • 示例：monitored_resource="gae_app"

2. 保留用户提供的字面值（关键）：始终使用用户提示中提供的字面资源 名称、命名空间和 ID。除非用户明确要求查找活动资源，否则不要 使用 Cloud Monitoring 发现的活动资源名称覆盖或替换这些值。遥测发现只能用于识别指标 类型名称和标签键，不得用于覆盖用户输入。

3. 资源标识符映射：

   • 直接且具体的键：使用可用的最具体资源标识符。示例：version_id、cluster_name。
   • 名称到 ID 的解析：如果用户按资源名称（例如 "instance-1"）筛选， 但资源架构使用数字 ID（例如 instance_id），请使用 PromQL 字符串名称标签，而非数字 ID 标签。示例：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 响应会返回 MonitoredResourceDescriptor 对象，其中包含 labels 数组， 该数组列出了此资源的确切资源标签键。

选择聚合结构与默认值

查询结构和聚合函数（例如 rate、 histogram_quantile、sum 或 avg）取决于指标类型及其可视化方式。

1. 查阅参考资料：请查阅 Cloud Monitoring 到 PromQL 基础聚合参考，将 Cloud Monitoring 属性（指标类型、 值类型、对齐器、归约器）映射到对应的 PromQL 结构。该参考资料是唯一可信来源。
2. SRE 聚合与可视化规则：
   • 不要对资源实例间的比率／百分比利用率指标求和或取平均值（例如 CPU % 或内存限制利用率）。应保持未聚合状态（原始指标）、按实例分组，或使用 topk(30, avg_over_time(...)) 包装。
   • 状态标签筛选（关键）：只有指标 agent.googleapis.com/memory/percent_used 和 agent.googleapis.com/disk/percent_used 需要 {state!="free"}。不要 使用 {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
   • 确保最终查询为不含注释的单行（不含 # 或 //）。Cloud Monitoring 查询转换会折叠空白字符，可能导致注释后的代码被忽略或引发解析错误。
   • 分组子句语法：确保分组子句（例如 by (label)）仅跟在聚合运算符（例如 sum、avg、 min、max 或 count）之后。切勿将分组子句直接放在指标选择器之后。
     • 错误：metric{...} by (label)
     • 正确：sum(rate(metric{...}[5m])) by (label)
   • 围栏代码块输出：最终回复中必须始终使用带围栏的 promql 代码块包裹最终验证通过的 PromQL 查询。
2. Linter 验证：
   • 使用单个批次验证所有生成的查询：python3 <path_to_skill>/scripts/validate_promql.py --query '<q1>' '<q2>'
   • 如果验证失败，请阅读 PromQL 错误恢复指南，诊断并修复常见的类型不匹配和语法错误，然后重新执行验证。

参考资料

• Cloud Monitoring PromQL 基本聚合参考
• Cloud Monitoring PromQL 错误恢复指南
• Cloud Monitoring PromQL 文档
• Cloud Monitoring 受监控资源类型参考