cloud-monitoring-metric-selection

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Metric Selection (Service Query & Local Keyword Filtering)

指标选择（服务查询与本地关键词过滤）

Use this skill to identify the most relevant Google Cloud Monitoring metric descriptors. It queries all metric descriptors for a target service from the API and filters them locally inside the agent's context using keyword matching.

使用此技能识别最相关的Google Cloud Monitoring指标描述符。它会从API查询目标服务的所有指标描述符，并在Agent的上下文内通过关键词匹配进行本地过滤。

CRITICAL RULES

关键规则

Always Query Live APIs: You MUST always retrieve the most up-to-date metric descriptors dynamically by calling the
```
list_metric_descriptors
```
MCP tool.

始终查询实时API：你必须通过调用
```
list_metric_descriptors
```
MCP工具动态检索最新的指标描述符。

Workflow

工作流程

Step 1: Verify & Auto-Configure MCP

步骤1：验证并自动配置MCP

Check if any tool matching

list_metric_descriptors

(e.g.

google-cloud-monitoring:list_metric_descriptors

mcp_google-cloud-monitoring_list_metric_descriptors

, or a similar pattern) is available in your active toolset.

Verify via Unique URL: To ensure you are calling the correct Google Cloud Monitoring tool, confirm that the underlying MCP server configuration points to: https://monitoring.googleapis.com/mcp
.
If the tool is missing:
- Locate the MCP configuration file for the user's environment. Check common paths:
  - ```
  ~/.gemini/config/mcp_config.json
```
- ```
~/.codeium/windsurf/mcp_config.json
```
  - ```
  cline_mcp_settings.json
```
- ```
claude_desktop_config.json
```
- Directly update/merge the configuration file with the following server configuration. CRITICAL: Merge the JSON object to preserve any existing MCP servers in
```
mcpServers
```
  . Do not overwrite the file.
  json
```
"google-cloud-monitoring": {
  "url": "https://monitoring.googleapis.com/mcp",
  "authProviderType": "google_credentials",
  "enabledTools": [
    "list_metric_descriptors"
  ]
}
```
- Print a clear message notifying the user that the
```
google-cloud-monitoring
```
  MCP server has been configured, and request them to restart or start a new chat session to refresh tools. Stop calling further tools and end the turn.

检查你的可用工具集中是否存在匹配

list_metric_descriptors

的工具（例如

google-cloud-monitoring:list_metric_descriptors

、

mcp_google-cloud-monitoring_list_metric_descriptors

或类似模式）。

通过唯一URL验证：为确保调用正确的Google Cloud Monitoring工具，请确认底层MCP服务器配置指向：https://monitoring.googleapis.com/mcp
。
如果工具缺失：
- 定位用户环境中的MCP配置文件。检查常见路径：
  - ```
  ~/.gemini/config/mcp_config.json
```
- ```
~/.codeium/windsurf/mcp_config.json
```
  - ```
  cline_mcp_settings.json
```
- ```
claude_desktop_config.json
```
- 使用以下服务器配置直接更新/合并配置文件。关键提示：合并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: Analyze Request & Extract Keywords

步骤2：分析请求并提取关键词

Identify the target GCP service prefix (e.g.
```
compute
```
,
```
spanner
```
,
```
bigquery
```
,
```
storage
```
) and the project ID from the resource URI.
Extract target metric concepts from the user's prompt (e.g., "CPU", "memory", "bytes scanned", "latency", "connections").
Map these concepts to standard Google Cloud Monitoring metric substrings (e.g.,
```
cpu
```
,
```
mem
```
,
```
scanned_bytes
```
,
```
latenc
```
,
```
connections
```
).

Example Query Analysis:

User Prompt: "Check Cloud Storage bucket write throughput and request count"

Resource URI:

//storage.googleapis.com/projects/my-project/buckets/my-bucket

Service Prefix:
```
storage
```
(mapped to
```
storage.googleapis.com
```
)
Metric Keywords:
```
write
```
,
```
throughput
```
,
```
request
```
,
```
count
```
Mapped Substrings:
```
write
```
,
```
throughput
```
,
```
request_count
```
,
```
count
```

从资源URI中识别目标GCP服务前缀（例如
```
compute
```
、
```
spanner
```
、
```
bigquery
```
、
```
storage
```
）和项目ID。
从用户的提示中提取目标指标概念（例如“CPU”、“内存”、“扫描字节数”、“延迟”、“连接数”）。
将这些概念映射为标准Google Cloud Monitoring指标子字符串（例如
```
cpu
```
、
```
mem
```
、
```
scanned_bytes
```
、
```
latenc
```
、
```
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: Query Metric Descriptors via list_metric_descriptors Tool

步骤3：通过list_metric_descriptors工具查询指标描述符

Query all metric descriptors for each identified service prefix using the

list_metric_descriptors

MCP tool (using

pageSize: 200

). Because Google Cloud Monitoring filters do not allow combining multiple

metric.type

restrictions with

OR

, you must initiate a separate query for each identified service prefix (either sequentially or in parallel).

If any response includes a

nextPageToken

, you MUST make consecutive follow-up calls passing

pageToken

until all remaining descriptors for that prefix are retrieved before filtering.

Filter Pattern Construction: Map the target service domain to its appropriate prefix style:

Standard Google Cloud Services:

starts_with("<service_prefix>.googleapis.com/")

(e.g.,

bigquery.googleapis.com/

redis.googleapis.com/

Ops Agent (Guest OS):
```
starts_with("agent.googleapis.com/")
```
(for guest OS memory/disk metrics).
Kubernetes / GKE Native:
```
starts_with("kubernetes.io/")
```
Istio Service Mesh:
```
starts_with("istio.io/")
```
Knative Serving / Autoscaler:
```
starts_with("knative.dev/")
```

Custom / External Metrics: Use

starts_with("custom.googleapis.com/")

starts_with("external.googleapis.com/")

Example Tool Call Payload: If both Spanner and Compute Engine are targeted in the request, execute these two tool calls:

Spanner query:

json

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

Compute Engine query:

json

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

Call the

list_metric_descriptors

tool with these payloads.

使用

list_metric_descriptors

MCP工具（设置

pageSize: 200

）查询每个已识别服务前缀的所有指标描述符。由于Google Cloud Monitoring过滤器不允许将多个

metric.type

限制条件通过

OR

组合，你必须为每个已识别的服务前缀发起单独的查询（可串行或并行执行）。

如果任何响应包含

nextPageToken

，你必须在过滤前连续调用工具并传入

pageToken

，直到获取该前缀的所有剩余描述符。

过滤模式构建：将目标服务域映射到相应的前缀格式：

标准Google Cloud服务：

starts_with("<service_prefix>.googleapis.com/")

（例如

bigquery.googleapis.com/

、

redis.googleapis.com/

）。

Ops Agent（客户机操作系统）：
```
starts_with("agent.googleapis.com/")
```
（用于客户机操作系统内存/磁盘指标）。
Kubernetes / GKE原生：
```
starts_with("kubernetes.io/")
```
Istio服务网格：
```
starts_with("istio.io/")
```
Knative Serving / 自动扩缩器：
```
starts_with("knative.dev/")
```

自定义/外部指标：使用

starts_with("custom.googleapis.com/")

或

starts_with("external.googleapis.com/")

。

工具调用负载示例：如果请求同时针对Spanner和Compute Engine，执行以下两次工具调用：

Spanner查询：

json

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

Compute Engine查询：

json

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

使用这些负载调用

list_metric_descriptors

工具。

Step 4: Local Filtering & Fallback Protocol

步骤4：本地过滤与回退协议

Aggregate all descriptors returned from Step 3, and filter them locally inside your LLM context:

Keyword Filtering: Filter the list by matching your target metric keywords (e.g. "cpu", "latency") against the
```
type
```
,
```
displayName
```
, and
```
description
```
fields of the descriptors.
Resource Alignment: Check if the metric contains labels matching the target resource granularity (e.g., checking for a
```
database
```
label if targeting a database resource). Do not attempt to dynamically match resource type strings directly, as Google Cloud Monitoring resource mappings (like Spanner databases mapping to
```
spanner_instance
```
) can be counter-intuitive.

汇总步骤3返回的所有描述符，并在你的LLM上下文内进行本地过滤：

关键词过滤：通过将目标指标关键词（例如"cpu"、"latency"）与描述符的
```
type
```
、
```
displayName
```
和
```
description
```
字段匹配来过滤列表。
资源对齐：检查指标是否包含与目标资源粒度匹配的标签（例如，如果目标是数据库资源，则检查是否存在
```
database
```
标签）。不要尝试直接动态匹配资源类型字符串，因为Google Cloud Monitoring的资源映射（如Spanner数据库映射到
```
spanner_instance
```
）可能不符合直觉。

Troubleshooting & API Fallbacks

故障排查与API回退策略

If any tool call fails, times out, or returns empty results, use these strategies:

Case A: API Syntax Error: Examine the error message, correct the filter syntax, and retry.
Case B: Timeout / Rate Limits: Retry the call once with a smaller page size (e.g.,
```
pageSize: 20
```
).
Case C: Unrecoverable Failure / Empty List:
1. Verify if the target service is enabled in the project.
2. Search Google Cloud public documentation to verify standard metrics for the service.
3. Notify the user of the failure and ask for clarification.

如果任何工具调用失败、超时或返回空结果，请使用以下策略：

情况A：API语法错误：检查错误消息，修正过滤器语法并重试。
情况B：超时/速率限制：使用更小的页面大小（例如
```
pageSize: 20
```
）重试一次。
情况C：不可恢复的失败/空列表：
1. 验证目标服务是否在项目中已启用。
2. 搜索Google Cloud公开文档以验证该服务的标准指标。
3. 通知用户失败情况并请求澄清。

Step 5: Output Selected Metrics

步骤5：输出选定的指标

For each service domain, return only the 5-15 key metrics directly relevant to the user's intent.

You MUST report the selected metrics in clean Markdown tables, grouped by service (i.e., one table per service prefix). The table MUST include the following columns: "Metric Type", "Display Name", "Description", "Metric Kind", "Value Type", "Unit", and "Monitored Resource Types". Map the fields from the Google Cloud Monitoring

list_metric_descriptors

tool call response objects directly to the table columns:

Metric Type: Map to the

type

field (e.g.,

spanner.googleapis.com/instance/cpu/utilization

Display Name: Map to the
```
displayName
```
field.
Description: Map to the
```
description
```
field.
Metric Kind: Map to the
```
metricKind
```
field (e.g.,
```
GAUGE
```
,
```
DELTA
```
,
```
CUMULATIVE
```
).
Value Type: Map to the
```
valueType
```
field (e.g.,
```
INT64
```
,
```
DOUBLE
```
,
```
DISTRIBUTION
```
,
```
BOOL
```
).
Unit: Map to the
```
unit
```
field (e.g.,
```
1
```
,
```
By
```
,
```
s
```
,
```
ms
```
).
Monitored Resource Types: Map to the
```
monitoredResourceTypes
```
list field (e.g.,
```
["spanner_instance"]
```
).

Example Output Table:

Metric Type	Display Name	Description	Metric Kind	Value Type	Unit	Monitored Resource Types
`spanner.googleapis.com/instance/cpu/utilization`	Instance CPU Utilization	Fraction of allocated CPU currently in use.	GAUGE	DOUBLE	1	`["spanner_instance"]`

对于每个服务域，仅返回与用户意图直接相关的5-15个关键指标。

你必须将选定的指标整理为清晰的Markdown表格，按服务分组（即每个服务前缀对应一个表格）。表格必须包含以下列：“Metric Type”、“Display Name”、“Description”、“Metric Kind”、“Value Type”、“Unit”和“Monitored Resource Types”。将Google 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	Fraction of allocated CPU currently in use.	GAUGE	DOUBLE	1	`["spanner_instance"]`

Reference Documentation & Links

参考文档与链接

Google Cloud Monitoring Metric List: GCP Metrics Documentation
MetricDescriptor MCP Tool Reference: MCP Tools Reference: monitoring.googleapis.com
Monitoring Filter Syntax Guide: Monitoring Filters

Google Cloud Monitoring指标列表: GCP Metrics Documentation
MetricDescriptor MCP工具参考: MCP Tools Reference: monitoring.googleapis.com
监控过滤器语法指南: Monitoring Filters