cloud-monitoring-metric-selection

指标选择（服务查询和本地关键词筛选）

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

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须先阅读 使用归属信息。对于直接在终端中执行的命令（绝不用于生成的脚本、Terraform 或用户代码），在 gcloud 前添加 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-metric-selection)"，并在 User-Agent 请求头中追加 agent-skills/1.0 (skill:cloud-monitoring-metric-selection)。

关键规则

• 始终查询实时 API：必须始终通过调用 list_metric_descriptors MCP 工具，动态检索最新的指标描述符。
• 必须确认项目 ID 和资源参数：调用任何 API 工具（例如 list_metric_descriptors）之前，必须确认提示词、URI 或环境上下文中已提供 GCP 项目 ID。如果无法确定项目 ID，必须先请用户确认或提供该 ID，再执行 API 查询。不得对未经确认的默认项目名称或占位项目名称（例如 mock-project、my-project-id、unused 或 YOUR_PROJECT_ID）运行 API 查询。
• 回退报告：如果 API 调用失败并使用了回退来源（例如公共文档），必须说明错误、回退来源以及非实时数据的风险（例如数据可能过时、缺少自定义指标或架构不匹配）。

工作流

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

1. 检查当前可用工具集中是否有与 list_metric_descriptors 匹配的工具（例如 google-cloud-monitoring:list_metric_descriptors、mcp_google-cloud-monitoring_list_metric_descriptors 或类似模式的工具）。

2. 通过唯一 URL 验证：为确保调用的是正确的 Cloud Monitoring 工具，请确认底层 MCP 服务配置指向：https://monitoring.googleapis.com/mcp。

3. 如果缺少该工具：

   • 找到用户环境的 MCP 配置文件。检查以下常见路径：

     • ~/.gemini/config/mcp_config.json
     • ~/.codeium/windsurf/mcp_config.json
     • cline_mcp_settings.json
     • claude_desktop_config.json

   • 直接使用以下服务配置更新/合并配置文件。关键：合并 JSON 对象以保留 mcpServers 中已有的 MCP 服务。不要覆盖整个文件。

     "google-cloud-monitoring": {
       "url": "https://monitoring.googleapis.com/mcp",
       "authProviderType": "google_credentials",
       "enabledTools": [
         "list_metric_descriptors"
       ]
     }
     

   • 明确告知用户已配置 google-cloud-monitoring MCP 服务，并请他们重启或开始新的聊天会话以刷新工具。停止调用其他工具并结束本轮对话。

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

1. 解析项目 ID 和标识符：检查提示词、资源 URI 或环境上下文中是否包含 GCP 项目 ID 和资源标识符。 根据上文的关键规则，不得使用占位项目名称。

2. 识别服务前缀：将目标 GCP 服务映射到其标准前缀（例如 compute、spanner、bigquery、storage）。

3. 提取指标概念：从用户提示中提取指标关键词（例如“CPU”“内存”“扫描字节数”“延迟”“连接数”），并将其映射为搜索子串。

查询分析示例：

• 用户提示：“检查 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

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

使用 list_metric_descriptors MCP 工具，查询每个已识别服务前缀对应的所有指标描述符（使用 pageSize: 200）。由于 Cloud Monitoring 过滤条件不允许使用 OR 合并多个 metric.type 限制，因此必须针对每个已识别的服务前缀分别发起查询（可按顺序或并行执行）。

如果任何响应包含 nextPageToken，则必须继续调用，并传入 pageToken，直到检索到该前缀的所有剩余描述符。

*过滤模式构造：*将目标服务域映射为相应的前缀形式：

1. 标准 Google Cloud 服务： starts_with("<service_prefix>.googleapis.com/")（例如 bigquery.googleapis.com/、redis.googleapis.com/）。
2. Ops Agent（Guest OS）：starts_with("agent.googleapis.com/")（用于 Guest OS 内存／磁盘指标）。
3. Kubernetes／GKE 原生指标：starts_with("kubernetes.io/")
4. Istio 服务网格：starts_with("istio.io/")
5. Knative Serving／Autoscaler：starts_with("knative.dev/")
6. 自定义／外部指标：使用 starts_with("custom.googleapis.com/") 或 starts_with("external.googleapis.com/")。

*工具调用载荷示例：*如果请求中同时涉及 Spanner 和 Compute Engine，请执行以下两次工具调用：

1. Spanner 查询：

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

1. Compute Engine 查询：

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

使用这些载荷调用 list_metric_descriptors 工具。

步骤 4：本地过滤与回退流程

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

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

故障排除与 API 回退

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

• 情况 A：API 语法错误：检查错误消息，修正过滤条件语法，然后重试。
• 情况 B：超时／速率限制：将页大小调小后（例如 pageSize: 20）重试一次。
• 情况 C：无法恢复的故障／空列表：
  1. 确认目标服务是否已在项目中启用。
  2. 搜索 Google Cloud 公开文档，确认该服务的标准指标。

步骤 5：输出选定指标

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

你必须使用整洁的 Markdown 表格报告选定的指标，并按服务分组（即每个服务前缀使用一个表格）。表格必须包含以下列：“Metric Type”“Display Name”“Description”“Metric Kind”“Value Type”“Unit”和“Monitored Resource Types”。将 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	当前正在使用的已分配 CPU 的比例。	GAUGE	DOUBLE	1	["spanner_instance"]

参考文档和链接

• Cloud Monitoring 指标列表： GCP 指标文档
• MetricDescriptor MCP 工具参考： MCP 工具参考：monitoring.googleapis.com
• Monitoring 过滤语法指南： Monitoring 过滤器