cloud-monitoring-promql-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Monitoring PromQL Generator

Cloud Monitoring PromQL 生成器

Use this skill to generate a valid PromQL query from any Cloud Monitoring metric type. This guide applies to all Cloud Monitoring metric types by mapping Cloud Monitoring metric and resource descriptors to PromQL structures.

使用此技能可从任意Cloud Monitoring指标类型生成有效的PromQL查询。本指南通过将Cloud Monitoring指标和资源描述符映射到PromQL结构，适用于所有Cloud Monitoring指标类型。

Workflow

工作流程

Resolve Project ID (CRITICAL & BLOCKING)

解析项目ID（关键且阻塞步骤）

Before performing any other actions (such as searching code, reading references, or running validation), you MUST verify whether the Google Cloud Project ID is available:

Check Prompt/Payload: Look for the Project ID in the user's prompt or input.
Check Environment: If the Project ID is not present in the prompt, you MUST run
```
gcloud config get-value project
```
to attempt to resolve it from the environment.
Ask for Clarification (BLOCKING): If the Project ID is not in the prompt AND the
```
gcloud
```
command fails, returns an empty string, or is unavailable, you MUST immediately stop. Do NOT generate a PromQL query, do not run the validation script, and do not use placeholders (like
```
YOUR_PROJECT_ID
```
). You must refuse to proceed and ask the user to provide the Project ID.

在执行任何其他操作（如搜索代码、查阅参考资料或运行验证）之前，您必须验证Google Cloud项目ID是否可用：

检查提示/负载: 在用户的提示或输入中查找项目ID。
检查环境: 如果提示中没有项目ID，您必须运行
```
gcloud config get-value project
```
尝试从环境中解析。
请求澄清（阻塞步骤）: 如果提示中没有项目ID，且
```
gcloud
```
命令执行失败、返回空字符串或不可用，您必须立即停止操作。请勿生成PromQL查询、不要运行验证脚本、也不要使用占位符（如
```
YOUR_PROJECT_ID
```
）。您必须拒绝继续并要求用户提供项目ID。

Inspect Metric and Resource Descriptors

检查指标和资源描述符

Use Provided Descriptors First: If the user's prompt already includes metric descriptor details (such as
```
metric.type
```
,
```
metricKind
```
,
```
valueType
```
, or
```
monitoredResourceTypes
```
) or specific resource filter values, use those values directly instead of calling the Cloud Monitoring API.
Discover Missing Descriptors: If exact metric descriptors (
```
metric.type
```
,
```
metricKind
```
,
```
valueType
```
) are missing or underspecified, resolve the target metric type's descriptor using one of these paths:
- Vague Query: If the prompt is vague (for example,
```
"VM CPU usage"
```
  ), use the
```
cloud-monitoring-metric-selection
```
  skill first to identify the specific metric type.
- Known Metric Type: If you already have the specific metric type name (for example,
```
compute.googleapis.com/instance/cpu/utilization
```
  ) but need its descriptor, call the
```
google-cloud-monitoring:list_metric_descriptors
```
  MCP tool. If the tool is missing, refer to the
```
cloud-monitoring-metric-selection
```
  skill to configure the Cloud Monitoring MCP server.
- Fallback: If the MCP tool cannot be configured, fall back to making a direct Cloud Monitoring API call.
Identify Key Fields: From the retrieved descriptor, identify four key schema attributes:
- type
  : The Cloud Monitoring metric type string.
- metricKind
  :
```
GAUGE
```
  ,
```
DELTA
```
  , or
```
CUMULATIVE
```
  .
- valueType
  :
```
INT64
```
  ,
```
DOUBLE
```
  ,
```
DISTRIBUTION
```
  , or
```
BOOL
```
  .
- monitoredResourceTypes
  : Compatible
```
resource.type
```
  strings required for resource scoping and grouping.

优先使用提供的描述符: 如果用户的提示已包含指标描述符详情（如
```
metric.type
```
、
```
metricKind
```
、
```
valueType
```
或
```
monitoredResourceTypes
```
）或特定资源过滤值，请直接使用这些值，无需调用Cloud Monitoring API。
发现缺失的描述符: 如果缺少或未明确指定确切的指标描述符（
```
metric.type
```
、
```
metricKind
```
、
```
valueType
```
），请通过以下路径之一解析目标指标类型的描述符：
- 模糊查询: 如果提示内容模糊（例如
```
"VM CPU使用率"
```
  ），请先使用
```
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。
识别关键字段: 从检索到的描述符中识别四个关键架构属性：
- type
  : Cloud Monitoring指标类型字符串。
- metricKind
  :
```
GAUGE
```
  、
```
DELTA
```
  或
```
CUMULATIVE
```
  。
- valueType
  :
```
INT64
```
  、
```
DOUBLE
```
  、
```
DISTRIBUTION
```
  或
```
BOOL
```
  。
- monitoredResourceTypes
  : 资源范围界定和分组所需的兼容
```
resource.type
```
  字符串。

Resolve Resource Filters & Discovery Protocol

解析资源过滤器与发现协议

To filter data by a specific resource instance, apply these resource rules and discovery protocols:

Monitored Resource Filter: Always include the
```
monitored_resource="<type>"
```
filter in your query to prevent collisions across services that share metric names.
- Example:
```
monitored_resource="gae_app"
```
Preserve User Literals (CRITICAL): ALWAYS use the literal resource names, namespaces, and IDs provided in the user's prompt. Do NOT override or replace these values with active resource names found during Cloud Monitoring discovery unless the user explicitly asked you to find active resources. Telemetry discovery must only be used to identify metric type names and label keys, not to override user input.
Resource Identifier Mapping:
- Direct & Specific Keys: Use the most specific resource identifier available. Example:
```
version_id
```
  ,
```
cluster_name
```
  .
- Name-to-ID Resolution: If the user filters by a resource name (such as
```
"instance-1"
```
  ), but the resource schema uses numeric IDs (like
```
instance_id
```
  ), use PromQL string name labels instead of numeric ID labels. Example:
```
instance_name
```
  ,
```
metadata_system_name
```
  .
- Composite Identifiers: For resources with hierarchical identifiers (such as Cloud SQL databases), format the filter as a single composite key. Do NOT split them into separate
```
project_id
```
  and sub-resource labels. Example:
```
database_id="{project_id}:{instance_name}"
```
  .

Resource Label Discovery: The

google-cloud-monitoring:list_metric_descriptors

tool only returns metric-specific labels. If the label schema for a monitored resource is unknown, fetch the resource descriptor directly from the Cloud Monitoring v3 REST API (

projects.monitoredResourceDescriptors.get

bash

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}"

An HTTP 200 OK response returns the

MonitoredResourceDescriptor

object containing the

labels

array with the exact resource label keys for that resource.

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

受监控资源过滤器: 请始终在查询中包含
```
monitored_resource="<type>"
```
过滤器，以防止共享指标名称的服务之间发生冲突。
- 示例:
```
monitored_resource="gae_app"
```
保留用户字面量（关键）: 请始终使用用户提示中提供的字面资源名称、命名空间和ID。除非用户明确要求查找活动资源，否则请勿用Cloud Monitoring发现过程中找到的活动资源名称覆盖或替换这些值。遥测发现仅应用于识别指标类型名称和标签键，而非覆盖用户输入。
资源标识符映射:
- 直接且特定的键: 使用可用的最具体资源标识符。示例:
```
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}"
```
  。

资源标签发现:

google-cloud-monitoring:list_metric_descriptors

工具仅返回特定于指标的标签。如果受监控资源的标签架构未知，请直接从Cloud Monitoring v3 REST API (

projects.monitoredResourceDescriptors.get

)获取资源描述符：

bash

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

对象，其中包含该资源的确切资源标签键。

Choose Aggregation Structure & Defaults

选择聚合结构与默认值

The query structure and aggregation functions (such as

rate

histogram_quantile

sum

, or

avg

) depend on the metric type and how it is visualized.

Consult the Reference: Consult the Cloud Monitoring to PromQL Basic Aggregations Reference as the single source of truth to map Cloud Monitoring properties (Metric Kind, Value Type, Aligner, Reducer) to their PromQL structures.
SRE Aggregation & Visualization Rules:
- Do NOT sum or average ratio/percentage utilization metrics (like CPU % or Memory limit utilization) across resource instances. Instead, keep them unaggregated (raw metric), group by instance, or wrap in
```
topk(30, avg_over_time(...))
```
  .
- State Label Filtering (CRITICAL): Only the metrics
```
agent.googleapis.com/memory/percent_used
```
  and
```
agent.googleapis.com/disk/percent_used
```
  require
```
{state!="free"}
```
  . Do NOT filter by
```
{state="used"}
```
  .

查询结构和聚合函数（如

rate

、

histogram_quantile

、

sum

或

avg

）取决于指标类型及其可视化方式。

查阅参考资料: 请查阅Cloud Monitoring 到 PromQL 基础聚合参考作为单一可信来源，将Cloud Monitoring属性（指标类型、值类型、对齐器、归约器）映射到对应的PromQL结构。
SRE聚合与可视化规则:
- 请勿对比率/百分比利用率指标（如CPU使用率或内存限制利用率）跨资源实例求和或取平均值。相反，请保持其未聚合状态（原始指标）、按实例分组，或使用
```
topk(30, avg_over_time(...))
```
  包裹。
- 状态标签过滤（关键）: 仅
```
agent.googleapis.com/memory/percent_used
```
  和
```
agent.googleapis.com/disk/percent_used
```
  这两个指标需要
```
{state!="free"}
```
  过滤。请勿使用
```
{state="used"}
```
  进行过滤。

Format & Validate Query

格式化与验证查询

Before presenting any PromQL queries, validate them using the linter:

在展示任何PromQL查询之前，请使用校验器进行验证：

Python Dependencies

Python依赖项

Before executing the validation script (

scripts/validate_promql.py

), install the required Python dependencies:

bash

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

在执行验证脚本(

scripts/validate_promql.py

)之前，请安装所需的Python依赖项：

bash

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

Validation Procedure

验证流程

Format Constraints:
- Metric Name Normalization: Convert Cloud Monitoring metric types to PromQL metric names using this recipe:
  1. Split Domain and Path: Split the Cloud Monitoring metric type by the first slash (
```
/
```
    ) to separate the domain from the path.
    - Example:
      storage.googleapis.com/network/received_bytes_count
      -> domain
      storage.googleapis.com
      , path
      network/received_bytes_count
  2. Normalize Domain: Replace all periods (
```
.
```
    ) in the domain with underscores (
```
_
```
    ).
    - Example:
      storage.googleapis.com
      ->
      storage_googleapis_com
  3. Normalize Path: Replace all periods (
```
.
```
    ) and slashes (
```
/
```
    ) in the path with underscores (
```
_
```
    ).
    - Example:
      network/received_bytes_count
      ->
      network_received_bytes_count
  4. Join with Colon: Join the normalized domain and normalized path with a colon (
```
:
```
    ).
    - Example:
      storage_googleapis_com:network_received_bytes_count
  5. Native Prometheus Metrics: If the metric type has no slash, keep it as-is.
    - Example:
      up
      ->
      up
      ,
      http_requests_total
      ->
      http_requests_total
  6. Distribution Suffix: If the metric's
```
valueType
```
    is
```
DISTRIBUTION
```
    , append
```
_bucket
```
    to the end of the normalized name.
    - Example:
      cloudfunctions.googleapis.com/function/execution_times
      ->
      cloudfunctions_googleapis_com:function_execution_times_bucket
- Ensure the final query is a single line with no comments (no
```
#
```
  or
```
//
```
  ). Cloud Monitoring query translation collapses whitespace and can cause code trailing a comment to be ignored or throw parsing errors.
- Grouping Clause Syntax: Ensure grouping clauses (such as
```
by (label)
```
  ) only follow aggregation operators (such as
```
sum
```
  ,
```
avg
```
  ,
```
min
```
  ,
```
max
```
  , or
```
count
```
  ). Never place a grouping clause directly after a metric selector.
  - Incorrect:
```
metric{...} by (label)
```
  - Correct:
```
sum(rate(metric{...}[5m])) by (label)
```
- Fenced Output Code Block: ALWAYS wrap the final verified PromQL query in a fenced
```
promql
```
  code block in your final response.
Linter Verification:
- Validate all generated queries in a single batch:
```
python3 <path_to_skill>/scripts/validate_promql.py --query '<q1>' '<q2>'
```
- If validation fails, read PromQL Error Recovery Guide to diagnose and fix common type mismatches and syntax errors before repeating the loop.

格式约束:
- 指标名称规范化: 使用以下规则将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
```
  代码块中作为最终响应。
校验器验证:
- 批量验证所有生成的查询：
```
python3 <path_to_skill>/scripts/validate_promql.py --query '<q1>' '<q2>'
```
- 如果验证失败，请查阅PromQL错误恢复指南诊断并修复常见的类型不匹配和语法错误，然后重复验证流程。

References

参考资料

Cloud Monitoring PromQL Basic Aggregations Reference
Cloud Monitoring PromQL Error Recovery Guide
Cloud Monitoring PromQL Documentation
Cloud Monitoring Monitored Resource Types Reference

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