MCP Toolbox 的 Cloud Monitoring 集成使用 PromQL 查询 Google Cloud Monitoring 时序指标【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文围绕 MCP Toolbox for Databases 的cloud-monitoring集成展开介绍如何通过cloud-monitoringsource 接入 Google Cloud Monitoring API如何用cloud-monitoring-query-prometheus工具以 PromQL 查询数据库实例的系统级与查询级指标以及如何通过预置配置prebuilt configs一键获得 AlloyDB、Cloud SQL 等数据库的可观测性工具集。读完本文你将掌握该集成的两种认证方式ADC 与客户端 OAuth、完整的 source/tool 配置写法、参数规范并能对照源码理解请求是如何发往 Monitoring API 的。一、Cloud Monitoring Source为 Monitoring API 提供客户端cloud-monitoringsource 是 MCP Toolbox 与 Google Cloud Monitoring API。1.1 两种认证方式source 支持两种认证模式对应实现位于 cloud_monitoring.go 的Initialize方法Application Default CredentialsADC默认不设置useClientOAuth时source 调用google.FindDefaultCredentials(ctx, monitoring.MonitoringScope)获取默认凭据并用其 TokenSource 构建 OAuth2 客户端。这与gcloud auth application-default login、GCE 服务账号、GOOGLE_APPLICATION_CREDENTIALS等标准 ADC 机制完全一致。Client-side OAuth将useClientOAuth设为true后source 不再自行获取凭据而是期望客户端例如 Web 浏览器在每次请求时提供 OAuth 2.0 access token。源码中的GetClient方法会校验 token 非空——若启用了客户端 OAuth 但未提供 token将直接返回错误client-side OAuth is enabled but no access token was provided。1.2 Source 配置示例来自官方文档的示例配置可直接复制使用将name改为你自己的名字kind: source name: my-cloud-monitoring type: cloud-monitoring --- kind: source name: my-oauth-cloud-monitoring type: cloud-monitoring useClientOAuth: true1.3 配置字段参考字段类型必填说明typestring是必须为cloud-monitoring。useClientOAuthboolean否为true时使用客户端 OAuth 认证否则使用 Application Default Credentials。默认值为false。在源码层面Config结构体cloud_monitoring.go与上表一一对应name和type带有validate:required约束。source 的baseURL固定为https://monitoring.googleapis.comIsReadOnly()返回false——因为该 source 本身不执行写操作读写属性由其工具层注解决定。1.4 RunQueryPromQL 请求的底层构造查询执行的唯一入口是Source.RunQuery(projectID, query)cloud_monitoring.go其请求链路值得注意请求 URL 按模板拼出/v1/projects/{projectId}/location/global/prometheus/api/v1/query即 Cloud Monitoring 为每个项目暴露的Prometheus 兼容查询端点location/global为固定路径PromQL 语句通过查询参数query传递请求头统一附加 Toolbox 的 User-Agent非 200 响应会携带状态码与响应体返回错误空响应体返回nil正常响应被解析为map[string]any返回给上层工具。单元测试 cloud_monitoring_test.go 与集成测试 cloud_monitoring_integration_test.go 分别覆盖配置解析/客户端构造与真实 API 调用场景。二、cloud-monitoring-query-prometheus 工具用 PromQL 查询项目指标cloud-monitoring-query-prometheus是该集成目前提供的工具用于针对某个 Google Cloud 项目用 PromQL 语句从 Cloud Monitoring 拉取时序指标数据。工具文档见 cloud-monitoring-query-prometheus.md。2.1 典型使用场景Ad-hoc 分析直接为某个数据库实例执行 PromQL 查询快速排查性能问题资源利用率监控跟踪数据库实例的 CPU、内存、磁盘使用情况查询性能监控观察实例级或单查询级的 latency、execution_time、wait_time系统健康总览获取数据库实例的整体健康状态预置配置通过 prebuilt configs 中已经配好的工具直接查询数据库系统级/查询级指标见第四节。2.2 权限要求使用该工具需要当前身份在 Google Cloud 项目上拥有roles/monitoring.viewer2.3 工具参数名称类型必填说明projectIdstring是Google Cloud 项目 ID。querystring是要执行的 Prometheus 查询语句。从源码看cloudmonitoring.go这两个参数并非来自配置文件而是在工具Initialize时于代码内部硬编码定义且都标记为required。Invoke方法会从参数集中按字符串类型取出projectId与query任一缺失都会返回 Agent 错误随后调用 source 的RunQuery完成查询。2.4 工具配置示例官方文档给出了一段面向 AlloyDB 等待时间指标的完整配置示例其中description为 LLM 提供了指标名、monitored resource、labels 以及一条可直接运行的 PromQL 范例kind: tool name: get_wait_time_metrics type: cloud-monitoring-query-prometheus source: cloud-monitoring-source description: | This tool fetches system wait time information for AlloyDB cluster, instance. Get the projectID, clusterID and instanceID from the user intent. To use this tool, you must provide the Google Cloud projectId and a PromQL query. Generate query using these metric details: metric: alloydb.googleapis.com/instance/postgresql/wait_time, monitored_resource: alloydb.googleapis.com/Instance. labels: cluster_id, instance_id, wait_event_type, wait_event_name. Basic time series example promql query: avg_over_time({__name__alloydb.googleapis.com/instance/postgresql/wait_time,monitored_resourcealloydb.googleapis.com/Instance,instance_idalloydb-instance}[5m])工具字段参考字段类型必填说明typestring是必须为cloud-monitoring-query-prometheus。sourcestring是一个cloud-monitoringsource 的名称。descriptionstring是传递给 agent 的工具描述。几个源码层面的补充事实description在Initialize中被强制校验为空即报错description is required for tool %q这与上表必填一致工具的 source 兼容性通过compatibleSource接口要求实现Client()与RunQuery在配置加载期由ValidateSource校验运行时Invoke会再次断言防止把其他类型 source 挂到此工具上注解默认为只读tools.NewReadOnlyAnnotations即该工具被声明为不产生副作用Authorized方法被显式覆盖为始终放行——认证与授权完全交由底层 GCP 凭据IAM执行这一点在 cloudmonitoring.go 的注释中有明确说明。2.5 可复用的 PromQL 查询模式预置配置 alloydb-postgres-observability.yaml 的get_system_metrics描述中内嵌了一组 PromQL 模板覆盖了常见聚合需求以 AlloyDB CPU 平均利用率指标为例# 1. 基础时序默认窗口 5m avg_over_time({__name__alloydb.googleapis.com/instance/cpu/average_utilization,monitored_resourcealloydb.googleapis.com/Instance,instance_idalloydb-instance}[5m]) # 2. Top K topk(30, avg_over_time({...}[5m])) # 3. 均值 avg(avg_over_time({...}[5m])) # 4/5. 最小值 / 最大值 min(min_over_time({...}[5m])) max(max_over_time({...}[5m])) # 6. 求和 sum(avg_over_time({...}[5m])) # 7. 流计数 count(avg_over_time({...}[5m])) # 8. 按标签分组的分位数 quantile by (instance_id,cluster_id)(0.99, avg_over_time({...}[5m]))对应的get_query_metrics工具还内置了 AlloyDB 高级查询洞察Advanced Query Insights的指标清单分为三类aggregate 聚合指标如.../insights/aggregate/execution_time、.../aggregate/latencies、.../aggregate/row_countlabels 为user、client_addr等——当用户没有给出具体 query hash 时应使用这类聚合指标perquery 单查询指标如.../insights/perquery/execution_time、.../perquery/latencies额外携带query_hash与querystringlabels——只有用户明确提供了 query hash 时才应下钻到该粒度且描述中特别要求对 query hash 做聚合以避免拉取 querystring、不要使用 latency 指标做其他用途pertag 标签维度指标按application、framework、route、tag_hash等维度切分。这些描述本身就是为 LLM 调优过的提示词工程说明该工具的设计目标是让 agent 能够依据用户意图自动生成正确的 PromQL。三、认证细节与客户端 OAuth 流程useClientOAuth: true模式下source 在Initialize阶段只创建一个带 User-Agent 的裸http.Client不持有任何凭据cloud_monitoring.go。真正的凭据通过 MCP 的访问令牌机制注入每次工具调用时GetClient(ctx, accessToken)用本次请求携带的 access token 构造一个oauth2.StaticTokenSource客户端返回UseClientAuthorization()返回true后服务端会在 MCP 握手层面要求客户端提供授权。适用前提是客户端如浏览器中的 agent 前端已经持有对该用户有效的 OAuth 2.0 token且该 token 对monitoring.googleapis.com具有roles/monitoring.viewer权限。反之默认 ADC 模式更适合服务器端部署Docker、GCE 等凭据生命周期完全由 Toolbox 进程管理。四、预置配置一键获得数据库可观测性工具集Cloud Monitoring 集成最大的实战价值在于它被组合进了多个 observability 类 prebuilt config。以 AlloyDB 为例alloydb-postgres-observability--prebuilt值alloydb-postgres-observability同时挂载了cloud-monitoring与databaseinsights两个 source共提供 7 个工具工具来源功能get_system_metricscloud-monitoring用 PromQL 获取 AlloyDB 实例的系统级时序指标get_query_metricscloud-monitoring用 PromQL 获取实例上查询级时序指标get_advanced_aggregated_query_statsdatabase-insights聚合查询执行统计总/平均执行时间、执行次数、等待时间、规范化 SQL支持按 database/user/query ID 过滤与分页get_advanced_aggregated_wait_event_statsdatabase-insights聚合等待事件统计定位性能瓶颈支持 WAIT_CLASS / WAIT_EVENT 两级粒度get_advanced_time_series_query_statsdatabase-insights查询执行统计的时序趋势rate(execution_time)、rate(wait_time)get_advanced_time_series_wait_event_statsdatabase-insights等待事件时序趋势分析争用模式get_index_recommendationsdatabase-insights索引顾问建议CREATE INDEX 语句、目标 schema/表/列、预估存储占用与预期性能提升权限方面该预置配置需要roles/monitoring.viewerCloud Monitoring 指标工具与roles/databaseinsights.viewerDatabase Insights 诊断工具且依赖 Advanced Query Insights 已启用。配置中还提供三个 toolset 用于按需收窄暴露面alloydb_postgres_cloud_monitoring_tools仅 2 个 Cloud Monitoring 指标工具、alloydb_postgres_database_insights_tools仅 5 个 Database Insights 工具、alloydb_postgres_observability_tools全部 7 个工具。完整配置可参考 alloydb-postgres-observability.yaml。同样的组合模式也覆盖了 Cloud SQL 各引擎对应的预置文档包括 Cloud SQL for PostgreSQL Observability、Cloud SQL for MySQL Observability、Cloud SQL for SQL Server Observability其配置分别位于 cloud-sql-postgres-observability.yaml、cloud-sql-mysql-observability.yaml、cloud-sql-mssql-observability.yaml。五、小结与适用边界cloud-monitoringsource 是一个薄客户端封装核心能力是把 PromQL 请求转发到monitoring.googleapis.com的 Prometheus 兼容端点认证二选一ADC 或客户端 OAuthcloud-monitoring-query-prometheus工具仅暴露projectIdquery两个必填参数指标知识指标名、labels、PromQL 模板被刻意写进工具的description交由 LLM 在运行时生成查询需要项目级roles/monitoring.viewer权限工具自身声明为只读且不在 Toolbox 层面做额外鉴权IAM 检查完全下沉到 GCP 凭据若目标是数据库可观测性系统指标 查询洞察 索引建议优先直接使用*-observability预置配置再按需通过 toolset 收窄工具暴露范围该工具面向 Google Cloud 环境非 GCP 的自建 Prometheus 数据源无法通过此 source 接入MCP Toolbox 对通用 HTTP 服务的接入属于另一套 source 的范畴。参考文档入口Cloud Monitoring 集成目录、Source 文档、工具文档。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP Toolbox 的 Cloud Monitoring 集成：使用 PromQL 查询 Google Cloud Monitoring 时序指标
MCP Toolbox 的 Cloud Monitoring 集成使用 PromQL 查询 Google Cloud Monitoring 时序指标【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文围绕 MCP Toolbox for Databases 的cloud-monitoring集成展开介绍如何通过cloud-monitoringsource 接入 Google Cloud Monitoring API如何用cloud-monitoring-query-prometheus工具以 PromQL 查询数据库实例的系统级与查询级指标以及如何通过预置配置prebuilt configs一键获得 AlloyDB、Cloud SQL 等数据库的可观测性工具集。读完本文你将掌握该集成的两种认证方式ADC 与客户端 OAuth、完整的 source/tool 配置写法、参数规范并能对照源码理解请求是如何发往 Monitoring API 的。一、Cloud Monitoring Source为 Monitoring API 提供客户端cloud-monitoringsource 是 MCP Toolbox 与 Google Cloud Monitoring API。1.1 两种认证方式source 支持两种认证模式对应实现位于 cloud_monitoring.go 的Initialize方法Application Default CredentialsADC默认不设置useClientOAuth时source 调用google.FindDefaultCredentials(ctx, monitoring.MonitoringScope)获取默认凭据并用其 TokenSource 构建 OAuth2 客户端。这与gcloud auth application-default login、GCE 服务账号、GOOGLE_APPLICATION_CREDENTIALS等标准 ADC 机制完全一致。Client-side OAuth将useClientOAuth设为true后source 不再自行获取凭据而是期望客户端例如 Web 浏览器在每次请求时提供 OAuth 2.0 access token。源码中的GetClient方法会校验 token 非空——若启用了客户端 OAuth 但未提供 token将直接返回错误client-side OAuth is enabled but no access token was provided。1.2 Source 配置示例来自官方文档的示例配置可直接复制使用将name改为你自己的名字kind: source name: my-cloud-monitoring type: cloud-monitoring --- kind: source name: my-oauth-cloud-monitoring type: cloud-monitoring useClientOAuth: true1.3 配置字段参考字段类型必填说明typestring是必须为cloud-monitoring。useClientOAuthboolean否为true时使用客户端 OAuth 认证否则使用 Application Default Credentials。默认值为false。在源码层面Config结构体cloud_monitoring.go与上表一一对应name和type带有validate:required约束。source 的baseURL固定为https://monitoring.googleapis.comIsReadOnly()返回false——因为该 source 本身不执行写操作读写属性由其工具层注解决定。1.4 RunQueryPromQL 请求的底层构造查询执行的唯一入口是Source.RunQuery(projectID, query)cloud_monitoring.go其请求链路值得注意请求 URL 按模板拼出/v1/projects/{projectId}/location/global/prometheus/api/v1/query即 Cloud Monitoring 为每个项目暴露的Prometheus 兼容查询端点location/global为固定路径PromQL 语句通过查询参数query传递请求头统一附加 Toolbox 的 User-Agent非 200 响应会携带状态码与响应体返回错误空响应体返回nil正常响应被解析为map[string]any返回给上层工具。单元测试 cloud_monitoring_test.go 与集成测试 cloud_monitoring_integration_test.go 分别覆盖配置解析/客户端构造与真实 API 调用场景。二、cloud-monitoring-query-prometheus 工具用 PromQL 查询项目指标cloud-monitoring-query-prometheus是该集成目前提供的工具用于针对某个 Google Cloud 项目用 PromQL 语句从 Cloud Monitoring 拉取时序指标数据。工具文档见 cloud-monitoring-query-prometheus.md。2.1 典型使用场景Ad-hoc 分析直接为某个数据库实例执行 PromQL 查询快速排查性能问题资源利用率监控跟踪数据库实例的 CPU、内存、磁盘使用情况查询性能监控观察实例级或单查询级的 latency、execution_time、wait_time系统健康总览获取数据库实例的整体健康状态预置配置通过 prebuilt configs 中已经配好的工具直接查询数据库系统级/查询级指标见第四节。2.2 权限要求使用该工具需要当前身份在 Google Cloud 项目上拥有roles/monitoring.viewer2.3 工具参数名称类型必填说明projectIdstring是Google Cloud 项目 ID。querystring是要执行的 Prometheus 查询语句。从源码看cloudmonitoring.go这两个参数并非来自配置文件而是在工具Initialize时于代码内部硬编码定义且都标记为required。Invoke方法会从参数集中按字符串类型取出projectId与query任一缺失都会返回 Agent 错误随后调用 source 的RunQuery完成查询。2.4 工具配置示例官方文档给出了一段面向 AlloyDB 等待时间指标的完整配置示例其中description为 LLM 提供了指标名、monitored resource、labels 以及一条可直接运行的 PromQL 范例kind: tool name: get_wait_time_metrics type: cloud-monitoring-query-prometheus source: cloud-monitoring-source description: | This tool fetches system wait time information for AlloyDB cluster, instance. Get the projectID, clusterID and instanceID from the user intent. To use this tool, you must provide the Google Cloud projectId and a PromQL query. Generate query using these metric details: metric: alloydb.googleapis.com/instance/postgresql/wait_time, monitored_resource: alloydb.googleapis.com/Instance. labels: cluster_id, instance_id, wait_event_type, wait_event_name. Basic time series example promql query: avg_over_time({__name__alloydb.googleapis.com/instance/postgresql/wait_time,monitored_resourcealloydb.googleapis.com/Instance,instance_idalloydb-instance}[5m])工具字段参考字段类型必填说明typestring是必须为cloud-monitoring-query-prometheus。sourcestring是一个cloud-monitoringsource 的名称。descriptionstring是传递给 agent 的工具描述。几个源码层面的补充事实description在Initialize中被强制校验为空即报错description is required for tool %q这与上表必填一致工具的 source 兼容性通过compatibleSource接口要求实现Client()与RunQuery在配置加载期由ValidateSource校验运行时Invoke会再次断言防止把其他类型 source 挂到此工具上注解默认为只读tools.NewReadOnlyAnnotations即该工具被声明为不产生副作用Authorized方法被显式覆盖为始终放行——认证与授权完全交由底层 GCP 凭据IAM执行这一点在 cloudmonitoring.go 的注释中有明确说明。2.5 可复用的 PromQL 查询模式预置配置 alloydb-postgres-observability.yaml 的get_system_metrics描述中内嵌了一组 PromQL 模板覆盖了常见聚合需求以 AlloyDB CPU 平均利用率指标为例# 1. 基础时序默认窗口 5m avg_over_time({__name__alloydb.googleapis.com/instance/cpu/average_utilization,monitored_resourcealloydb.googleapis.com/Instance,instance_idalloydb-instance}[5m]) # 2. Top K topk(30, avg_over_time({...}[5m])) # 3. 均值 avg(avg_over_time({...}[5m])) # 4/5. 最小值 / 最大值 min(min_over_time({...}[5m])) max(max_over_time({...}[5m])) # 6. 求和 sum(avg_over_time({...}[5m])) # 7. 流计数 count(avg_over_time({...}[5m])) # 8. 按标签分组的分位数 quantile by (instance_id,cluster_id)(0.99, avg_over_time({...}[5m]))对应的get_query_metrics工具还内置了 AlloyDB 高级查询洞察Advanced Query Insights的指标清单分为三类aggregate 聚合指标如.../insights/aggregate/execution_time、.../aggregate/latencies、.../aggregate/row_countlabels 为user、client_addr等——当用户没有给出具体 query hash 时应使用这类聚合指标perquery 单查询指标如.../insights/perquery/execution_time、.../perquery/latencies额外携带query_hash与querystringlabels——只有用户明确提供了 query hash 时才应下钻到该粒度且描述中特别要求对 query hash 做聚合以避免拉取 querystring、不要使用 latency 指标做其他用途pertag 标签维度指标按application、framework、route、tag_hash等维度切分。这些描述本身就是为 LLM 调优过的提示词工程说明该工具的设计目标是让 agent 能够依据用户意图自动生成正确的 PromQL。三、认证细节与客户端 OAuth 流程useClientOAuth: true模式下source 在Initialize阶段只创建一个带 User-Agent 的裸http.Client不持有任何凭据cloud_monitoring.go。真正的凭据通过 MCP 的访问令牌机制注入每次工具调用时GetClient(ctx, accessToken)用本次请求携带的 access token 构造一个oauth2.StaticTokenSource客户端返回UseClientAuthorization()返回true后服务端会在 MCP 握手层面要求客户端提供授权。适用前提是客户端如浏览器中的 agent 前端已经持有对该用户有效的 OAuth 2.0 token且该 token 对monitoring.googleapis.com具有roles/monitoring.viewer权限。反之默认 ADC 模式更适合服务器端部署Docker、GCE 等凭据生命周期完全由 Toolbox 进程管理。四、预置配置一键获得数据库可观测性工具集Cloud Monitoring 集成最大的实战价值在于它被组合进了多个 observability 类 prebuilt config。以 AlloyDB 为例alloydb-postgres-observability--prebuilt值alloydb-postgres-observability同时挂载了cloud-monitoring与databaseinsights两个 source共提供 7 个工具工具来源功能get_system_metricscloud-monitoring用 PromQL 获取 AlloyDB 实例的系统级时序指标get_query_metricscloud-monitoring用 PromQL 获取实例上查询级时序指标get_advanced_aggregated_query_statsdatabase-insights聚合查询执行统计总/平均执行时间、执行次数、等待时间、规范化 SQL支持按 database/user/query ID 过滤与分页get_advanced_aggregated_wait_event_statsdatabase-insights聚合等待事件统计定位性能瓶颈支持 WAIT_CLASS / WAIT_EVENT 两级粒度get_advanced_time_series_query_statsdatabase-insights查询执行统计的时序趋势rate(execution_time)、rate(wait_time)get_advanced_time_series_wait_event_statsdatabase-insights等待事件时序趋势分析争用模式get_index_recommendationsdatabase-insights索引顾问建议CREATE INDEX 语句、目标 schema/表/列、预估存储占用与预期性能提升权限方面该预置配置需要roles/monitoring.viewerCloud Monitoring 指标工具与roles/databaseinsights.viewerDatabase Insights 诊断工具且依赖 Advanced Query Insights 已启用。配置中还提供三个 toolset 用于按需收窄暴露面alloydb_postgres_cloud_monitoring_tools仅 2 个 Cloud Monitoring 指标工具、alloydb_postgres_database_insights_tools仅 5 个 Database Insights 工具、alloydb_postgres_observability_tools全部 7 个工具。完整配置可参考 alloydb-postgres-observability.yaml。同样的组合模式也覆盖了 Cloud SQL 各引擎对应的预置文档包括 Cloud SQL for PostgreSQL Observability、Cloud SQL for MySQL Observability、Cloud SQL for SQL Server Observability其配置分别位于 cloud-sql-postgres-observability.yaml、cloud-sql-mysql-observability.yaml、cloud-sql-mssql-observability.yaml。五、小结与适用边界cloud-monitoringsource 是一个薄客户端封装核心能力是把 PromQL 请求转发到monitoring.googleapis.com的 Prometheus 兼容端点认证二选一ADC 或客户端 OAuthcloud-monitoring-query-prometheus工具仅暴露projectIdquery两个必填参数指标知识指标名、labels、PromQL 模板被刻意写进工具的description交由 LLM 在运行时生成查询需要项目级roles/monitoring.viewer权限工具自身声明为只读且不在 Toolbox 层面做额外鉴权IAM 检查完全下沉到 GCP 凭据若目标是数据库可观测性系统指标 查询洞察 索引建议优先直接使用*-observability预置配置再按需通过 toolset 收窄工具暴露范围该工具面向 Google Cloud 环境非 GCP 的自建 Prometheus 数据源无法通过此 source 接入MCP Toolbox 对通用 HTTP 服务的接入属于另一套 source 的范畴。参考文档入口Cloud Monitoring 集成目录、Source 文档、工具文档。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考