企业官网建设流程全解析

Google Cloud Monitoring 指标选择技能：通过 MCP 动态查询 MetricDescriptor 并本地关键词过滤

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本文围绕 skills 仓库中的cloud-monitoring-metric-selection技能展开，讲解如何为 AI Agent 构建一套“实时 API 查询 + 本地关键词过滤”的 GCP 监控指标发现流程：从 MCP 服务端配置与校验、Project ID 强制澄清，到按服务前缀构造list_metric_descriptors查询载荷、处理分页、执行本地过滤，直至输出标准化的指标描述符表格。读完本文，你将能够完整复现该技能的五步工作流，并将其无缝接入 cloud-monitoring-list-time-series-request 与 cloud-monitoring-promql-query 等下游技能，形成“指标发现 → 请求构造 → 图表生成”的可观测性工具链。

技能定位：在仓库中的上下游关系

该技能的核心职责是：为目标 GCP 服务或资源（Compute Engine、Spanner、BigQuery、Cloud Run、Cloud SQL、Pub/Sub、Cloud Storage 等）检索、查询并识别相关的 Google Cloud Monitoring 指标描述符（MetricDescriptor）。其定义见技能清单 index.json 中的同名条目，并在 README.md 的 “Management tools” 分类下被列为 “Metric Selection (Service Query & Local Keyword Filtering)”。

从源码结构看，该技能并非孤立存在，而是仓库可观测性技能链路的“发现”入口：

• cloud-monitoring-list-time-series-request 明确写道：当用户提示词模糊（例如只说“VM CPU 使用率”）时，应先使用cloud-monitoring-metric-selection技能定位具体的metric.type；若 MCP 工具缺失，也指向本技能完成监控 MCP 服务端的配置。
• cloud-monitoring-promql-query 与 cloud-monitoring-chart-generation 同样把本技能列为指标不明确时的前置步骤。
• 插件目录下的 rules/google-cloud-discovery.md 将cloud-monitoring-*整体归入 “observability” 路由分类，说明该技能是 Google Cloud 技能目录中可观测性领域的标准组件。

技能的实现策略可概括为一句话：不依赖任何硬编码指标清单，而是从 API 动态拉取全量描述符，再在 LLM 上下文内用关键词匹配完成二次过滤。这保证了数据新鲜度（能覆盖自定义指标），同时避免把大结果集直接暴露给下游。

三条 CRITICAL RULES：数据源、Project ID 与降级策略

原文档开篇即给出三条必须遵守的规则，它们是整个技能正确性的基石：

1. Always Query Live APIs（永远实时查询）：必须始终通过调用list_metric_descriptorsMCP 工具动态获取最新的指标描述符，禁止依赖记忆或静态缓存中的指标列表。
2. Mandatory Project ID and Resource Parameter Clarification（强制澄清 Project ID）：在调用任何 API 工具之前，必须确认 GCP Project ID 已经出现在提示词、URI 或环境上下文中；若无法解析，必须先向用户询问，绝不使用mock-project、my-project-id、unused、YOUR_PROJECT_ID这类占位项目名执行查询。
3. Fallback Reporting（降级上报）：如果 API 调用失败而不得不使用降级来源（如公开文档），必须明确报告：错误内容、所使用的降级来源、以及非实时数据的风险（数据可能过期、缺少自定义指标、schema 不匹配）。

其中第 2 条在下游技能 cloud-monitoring-list-time-series-request 中得到了呼应——后者同样要求 Project ID 缺失时必须先澄清，并额外给出了一个可接受的解析途径：gcloud config get-value project。两条规则配合，防止 Agent 在错误的命名空间下执行指标发现。

Step 1：验证与自动配置 Monitoring MCP 服务端

第一步的目标是确认list_metric_descriptors工具可用，并在缺失时自动完成 MCP 配置。具体流程如下：

1. 检查工具集：在活跃工具集中查找任何匹配list_metric_descriptors的工具，命名模式可能形如google-cloud-monitoring:list_metric_descriptors、mcp_google-cloud-monitoring_list_metric_descriptors或类似变体（不同客户端对 MCP 工具的命名前缀不同，因此按模式匹配而非精确名称匹配）。

2. 通过唯一 URL 验证：为确保调用的是正确的 Google 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

   然后将以下服务端配置合并进mcpServers对象：

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

   原文档特别标注CRITICAL：必须合并（merge）JSON 对象以保留mcpServers中已有的其他服务端，不得覆盖整个文件。这一点与仓库中 plugins/cloud/google-cloud-developer/mcp.json 的组织方式一致——该文件本身就是一个只含单个developer-knowledge服务端的mcpServers结构，合并而非覆盖是同类配置操作的通用要求。

4. 提示并结束回合：打印明确信息告知用户google-cloud-monitoringMCP 服务端已配置完成，请求其重启或开启新会话以刷新工具列表，然后停止调用后续工具并结束当前回合。这一步避免了在工具尚未生效时继续执行必然失败的调用。

Step 2：解析请求并提取关键词

请求分析阶段做三件事：

1. Resolve Project ID and Identifiers（解析 Project ID 与资源标识）：从提示词、资源 URI 或环境上下文中解析 GCP Project ID 与资源标识，并严格遵守上文 CRITICAL RULES 中“不使用占位项目名”的约束。
2. Identify Service Prefix（识别服务前缀）：把目标 GCP 服务映射到其标准前缀，例如compute、spanner、bigquery、storage。
3. Extract Metric Concepts（提取指标概念）：从用户提示中提取指标关键词（如 “CPU”、“memory”、“bytes scanned”、“latency”、“connections”），并映射为搜索子串。

原文档给出的示例值得逐字保留，因为它展示了从自然语言到结构化查询参数的完整映射：

• 用户提示：“Check Cloud Storage bucket write throughput and request count”
• 资源 URI：//storage.googleapis.com/projects/my-project/buckets/my-bucket
• 服务前缀：storage（映射到storage.googleapis.com）
• 指标关键词：write、throughput、request、count
• 映射后的搜索子串：write、throughput、request_count、count

注意示例中request count同时映射出request_count与count两个子串——这是为描述符字段中常见的下划线命名做的前置归一化，保证后续过滤时不会因命名风格差异漏掉storage.googleapis.com/bucket/bytes_write_count这类指标。

Step 3：按服务前缀发起 list_metric_descriptors 查询

这是技能的核心查询步骤，包含三个关键决策点：

3.1 每个服务前缀单独查询

由于 Google Cloud Monitoring 的过滤语法不允许用OR组合多个metric.type限制条件，必须为每个识别出的服务前缀单独发起一次查询（可串行也可并行），查询时使用pageSize: 200。

3.2 过滤模式的六种构造方式

将目标服务域映射到对应的前缀风格：

这六类前缀覆盖了 GCP 监控生态的主要指标来源：官方云服务指标、Guest Agent 指标、容器/网格指标以及用户自定义指标（custom.googleapis.com/前缀正是 CRITICAL RULES 强调“实时查询”的价值所在——静态清单永远无法覆盖这些用户自建指标）。

3.3 示例工具调用载荷

当请求同时涉及 Spanner 与 Compute Engine 时，需执行两次工具调用：

1. Spanner 查询：

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

2. Compute Engine 查询：

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

   其中name字段为projects/<project-id>形式的资源路径，filter使用 Monitoring Filter 语法，pageSize控制单页返回的描述符数量。

3.4 分页处理：nextPageToken 必须消费完毕

如果任何一次响应包含nextPageToken，必须携带pageToken连续发起后续调用，直到该前缀下的所有剩余描述符全部取回，之后才允许进入本地过滤阶段。这一步是数据完整性的硬约束：若在中途开始过滤，可能因截断而漏掉排在后面的自定义指标。

Step 4：本地过滤与降级协议

聚合 Step 3 返回的全部描述符后，在 LLM 上下文内执行两步本地过滤：

1. Keyword Filtering（关键词过滤）：用目标指标关键词（如 “cpu”、“latency”）与描述符的type、displayName、description三个字段做匹配。同时匹配这三个字段而非仅type，是因为描述符的人类可读名称与说明文本往往包含关键词的另一种表达（例如关键词 “latency” 可能只出现在description中）。
2. Resource Alignment（资源粒度对齐）：检查指标是否包含与目标资源粒度匹配的 labels（例如目标为数据库资源时，检查是否存在database标签）。原文档特别提醒：不要尝试直接对资源类型字符串做动态匹配，因为 Google Cloud Monitoring 的资源映射可能反直觉——典型例子是 Spanner database 映射到spanner_instance资源类型，直接按 “database” 字样匹配资源类型会得出错误结论。

故障排查与 API 降级（Troubleshooting & API Fallbacks）

当工具调用失败、超时或返回空结果时，按以下三种情形处置：

• Case A：API 语法错误——检查错误信息，修正 filter 语法后重试。
• Case B：超时 / 限流——以较小的页大小（如pageSize: 20）重试一次。
• Case C：不可恢复失败 / 空列表：
  1. 先验证目标服务是否已在该项目中启用（服务未启用时该前缀下没有描述符，空结果是正常现象，不是 API 故障）；
  2. 再检索 Google Cloud 公开文档核对该服务的标准指标作为降级来源。

按 CRITICAL RULES 第 3 条，一旦走了第 2 步降级路径，最终输出中必须声明错误、降级来源与数据陈旧风险，保证读者知晓结论的置信度边界。

Step 5：输出标准化指标表格

最终输出阶段有两条硬性格式约束：

• 数量控制：每个服务域只返回 5～15 个与用户意图直接相关的核心指标，避免把过滤后的全量列表倾倒给用户；
• 按服务分组：以干净的 Markdown 表格输出，每个服务前缀一张表，且必须包含以下七列：Metric Type、Display Name、Description、Metric Kind、Value Type、Unit、Monitored Resource Types。

字段到list_metric_descriptors响应对象的映射关系是明确的：

原文档的示例输出表格如下：

这七列不是展示性信息，而是下游技能的直接输入：cloud-monitoring-list-time-series-request 技能明确要求从描述符中提取metricKind（决定 aligner/reducer 的选择）、valueType（决定数值处理）与monitoredResourceTypes（决定resource.type过滤子句，例如从["cloudsql_database", "cloudsql_instance"]中按用户粒度挑选其一）来构造ListTimeSeries请求参数；cloud-monitoring-promql-query 同样以这些元数据为前提。因此，表格列的严格标准化实际上是该技能与下游技能之间的接口契约。

与仓库中配套技能与文档的协作方式

结合仓库内容，可以进一步理解该技能在整体链路中的位置：

• 上游触发：当用户请求模糊（“看看我的 Spanner 数据库健康状况”“VM CPU 高”）而无法直接给出metric.type时，list-time-series-request 与 promql-query 两个技能都会显式把流程交还给本技能。
• 同族可观测技能：cloud-logging-query-generation（日志查询生成）与 cloud-monitoring-chart-generation（图表生成）与本技能共同构成监控/日志方向的能力矩阵，路由规则见 rules/google-cloud-discovery.md（原文档中写为google-cloud-discovery.md，位于插件 rules 目录）。
• MCP 配置范式：插件内 mcp.json 展示了mcpServers指向https://developerknowledge.googleapis.com/mcp的标准写法；本技能要求的google-cloud-monitoring服务端条目采用同样的结构范式，只是 URL 换成https://monitoring.googleapis.com/mcp并附加enabledTools白名单（仅启用list_metric_descriptors一个工具），这是最小权限的做法——指标发现只需要列表能力，不需要读写时序数据。
• 背景参考：原文档的 Reference Documentation 一节指向了 GCP Metrics 文档、list_metric_descriptorsMCP 工具参考与 Monitoring Filter 语法指南；在本仓库中，可直接阅读的技能级入口是 skills/cloud/cloud-monitoring-metric-selection/SKILL.md。

适用前提与限制小结

综合原文档的约束，使用该技能（或按该文复现该流程）时需满足以下前提，并注意相应限制：

1. 必须有已确认的 GCP Project ID：占位项目名被明令禁止，缺失时必须向用户澄清，这是不可跳过的守卫步骤。
2. 必须有可用的 Monitoring MCP 服务端：指向https://monitoring.googleapis.com/mcp，认证方式为google_credentials；若需现场配置，注意合并写入、配置后须重启会话。
3. 过滤语法的限制：不能在一次查询中OR多个metric.type前缀，多服务场景只能多查并聚合；查询结果必须消费完所有nextPageToken才能过滤。
4. 资源映射需靠 labels 而非资源类型字符串：如 Spanner database 实际映射到spanner_instance，做资源粒度对齐时要检查指标的 label 结构。
5. 降级必须透明：任何基于公开文档而非实时 API 的结论，都要附带错误说明、来源声明与数据陈旧风险提示。

掌握以上流程后，该技能即可作为 GCP 可观测性 Agent 工作流的指标发现基座：上游承接模糊的用户请求，下游向 ListTimeSeries 请求生成、PromQL 生成与图表生成技能输出结构化的指标元数据，整条链路全部基于实时 API 数据而非硬编码清单。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills