MCP Toolbox Cloud SQL for PostgreSQL Observability 预置配置详解用 PromQL 查询系统级与查询级监控指标【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文围绕 MCP ToolboxMCP Toolbox for Databases的cloud-sql-postgres-observability预置配置展开讲清它包含的get_system_metrics与get_query_metrics两个 PromQL 查询工具、roles/monitoring.viewer权限前提、全部可用指标的元数据以及底层cloud-monitoringsource 如何把 PromQL 请求转发到 Google Cloud Monitoring Prometheus 端点。读完本文你可以直接在启动 MCP Toolbox 服务时启用该预置配置让 Agent 对 Cloud SQL for PostgreSQL 实例做资源利用率、连接数、死锁、复制延迟、事务年龄以及慢查询执行时间等维度的时序指标分析。配置概览与启用方式该预置配置在 CLI 中的--prebuilt取值为cloud-sql-postgres-observability其完整定义位于 internal/prebuiltconfigs/tools/cloud-sql-postgres-observability.yaml。YAML 文件由三段组成一个cloud-monitoring类型的 sourcecloud-monitoring-source、两个cloud-monitoring-query-prometheus类型的 tool以及一个把它们打包在一起的 toolsetkind: source name: cloud-monitoring-source type: cloud-monitoring --- kind: tool name: get_system_metrics type: cloud-monitoring-query-prometheus source: cloud-monitoring-source description: | ...系统指标查询说明与指标清单见下文 --- kind: tool name: get_query_metrics type: cloud-monitoring-query-prometheus source: cloud-monitoring-source description: | ...查询级指标查询说明与指标清单见下文 --- kind: toolset name: cloud_sql_postgres_cloud_monitoring_tools tools: - get_system_metrics - get_query_metrics启动方式摘自 docs/en/reference/cli.md 的用法示例# 单独启用该预置配置 ./toolbox --prebuilt cloud-sql-postgres-observability # 与其他预置配置叠加例如 PostgreSQL 数据库工具 监控工具 ./toolbox --prebuilt cloud-sql-postgres --prebuilt cloud-sql-postgres-observability # 与自定义配置文件组合 ./toolbox --config tools.yaml --prebuilt cloud-sql-postgres-observability几个实现细节可以印证其工作方式--prebuilt是一个StringSliceVar标志允许重复指定多个取值帮助文本会动态列出所有可用预置名见 cmd/internal/flags.go。所有预置 YAML 通过go:embed打包进二进制按“文件名去掉.yaml后缀”作为 key 注册见 internal/prebuiltconfigs/prebuiltconfigs.go。因此cloud-sql-postgres-observability这个 key 正是来自文件名cloud-sql-postgres-observability.yaml。预置配置还支持 toolset 后缀过滤如--prebuilt source/toolset只加载指定 toolset本配置的 toolset 名为cloud_sql_postgres_cloud_monitoring_tools。回归测试TestPrebuiltTools显式加载了该配置确保其 YAML 可被正常解析见 cmd/internal/config_test.go。官方同时提醒预置配置面向“构建时build-time”场景即 Agent 协助受信任开发者构建东西它们不适用于 Agent 直接面向不受信任用户的“运行时run-time”场景见 docs/en/documentation/configuration/prebuilt-configs/_index.md。权限与认证前提文档明确要求在项目上需要Monitoring Viewerroles/monitoring.viewer角色才能查看监控数据。该要求与 cloud-monitoring-query-prometheus 工具文档中的 IAM 要求一致。认证方面cloud-monitoringsource 支持两种方式见 docs/en/integrations/cloudmonitoring/source.md应用默认凭证ADC默认行为source 使用 ADC 向 Monitoring API 鉴权客户端 OAuthsource 配置中设置useClientOAuth: true时由客户端如浏览器在每个请求中提供 OAuth 2.0 access token。从源码看internal/sources/cloudmonitoring/cloud_monitoring.goInitialize在UseClientOAuth为 false 时调用google.FindDefaultCredentials(ctx, monitoring.MonitoringScope)获取 ADC 令牌源并构造oauth2HTTP 客户端为 true 时则使用普通 HTTP 客户端等待请求级 access token。两个工具本身都带有只读注解tools.GetAnnotationsOrDefault(..., tools.NewReadOnlyAnnotations)见 internal/tools/cloudmonitoring/cloudmonitoring.go且Authorized方法恒返回 true——鉴权强制完全委托给底层 GCP 凭证即上一节的roles/monitoring.viewer。工具一get_system_metrics系统级指标get_system_metrics用于以 PromQL 查询某个 Postgres 实例的系统级时序指标。它的入参只有两个在工具代码内部硬编码而非来自 YAML参数类型必填说明projectIdstring是Google Cloud 项目 IDquerystring是要执行的 PromQL 查询参数定义与调用逻辑见 internal/tools/cloudmonitoring/cloudmonitoring.goInvoke从参数映射中取出projectId与query直接调用 source 的RunQuery(projectID, query)任何错误经util.ProcessGcpError包装后返回给 Agent。查询构造约定工具描述写给 LLM 的 prompt中内置了构造规则理解这些规则有助于手写query默认时间窗口对*_over_time聚合函数除非用户另行指定默认使用5m区间。标签来源instance_id等标签从用户意图中提取database_id标签实际是实例 ID格式为project_id:instance_id。受监控资源系统指标统一使用monitored_resource cloudsql_database。示例 PromQL以下示例取自预置配置的描述文本以 CPU 利用率指标为例占位符替换为真实值即可运行# 基础时间序列 avg_over_time({__name__cloudsql.googleapis.com/database/cpu/utilization,monitored_resourcecloudsql_database,project_idmy-projectId,database_idmy-projectId:my-instanceId}[5m]) # Top K topk(30, avg_over_time({__name__cloudsql.googleapis.com/database/cpu/utilization,monitored_resourcecloudsql_database,project_idmy-projectId,database_idmy-projectId:my-instanceId}[5m])) # 均值 / 最小 / 最大 / 求和 / 流计数 avg(avg_over_time({...}[5m])) min(min_over_time({...}[5m])) max(max_over_time({...}[5m])) sum(avg_over_time({...}[5m])) count(avg_over_time({...}[5m])) # 按 database_id 分组的 0.99 分位数 quantile by (database_id)(0.99, avg_over_time({...}[5m]))完整系统指标清单26 项下表完整整理自 cloud-sql-postgres-observability.yaml均为cloudsql_database受监控资源下的指标共同标签包含project_id、database_id资源与 IO指标名说明附加标签cloudsql.googleapis.com/database/cpu/utilization当前 CPU 利用率相对预留 CPU 的百分比值通常为 0.0–1.0可能超过 1.0图表以 0%–100% 展示—cloudsql.googleapis.com/database/memory/components数据库内存统计组件按 usage、cache、free 等以百分比表示componentcloudsql.googleapis.com/database/disk/bytes_used_by_data_type按数据类型的磁盘数据使用量字节data_typecloudsql.googleapis.com/database/disk/read_ops_count数据盘读 IO 操作增量计数—cloudsql.googleapis.com/database/disk/write_ops_count数据盘写 IO 操作增量计数—cloudsql.googleapis.com/database/network/received_bytes_count网络接收字节增量计数—cloudsql.googleapis.com/database/network/sent_bytes_count网络发送字节增量计数destinationcloudsql.googleapis.com/database/postgresql/blocks_read_count数据库读取的磁盘块数source字段区分实际磁盘读与 buffer cache 读database,source连接与后端指标名说明附加标签cloudsql.googleapis.com/database/postgresql/new_connection_count新增连接数databasecloudsql.googleapis.com/database/postgresql/num_backends实例连接总数databasecloudsql.googleapis.com/database/postgresql/num_backends_by_state按状态分组的连接数database,statecloudsql.googleapis.com/database/postgresql/num_backends_by_application按应用分组的连接数applicationcloudsql.googleapis.com/database/postgresql/backends_in_wait处于等待状态的后端数backend_type,wait_event,wait_event_type事务与锁指标名说明附加标签cloudsql.googleapis.com/database/postgresql/transaction_count事务数增量计数database,transaction_typecloudsql.googleapis.com/database/postgresql/transaction_id_utilization事务 ID 消耗百分比0.0–1.0图表以 0%–100% 展示—cloudsql.googleapis.com/database/postgresql/deadlock_count检测到的死锁数databasecloudsql.googleapis.com/database/postgresql/vacuum/oldest_transaction_age最老待 vacuum 事务的年龄以自该事务以来发生的事务数计oldest_transaction_type数据与查询行为按库统计指标名说明附加标签cloudsql.googleapis.com/database/postgresql/tuples_processed_countinsert/update/delete 等操作处理的行数operation_type,databasecloudsql.googleapis.com/database/postgresql/tuple_size数据库中元组行数database,tuple_statecloudsql.googleapis.com/database/postgresql/tuples_fetched_count查询取回的行数databasecloudsql.googleapis.com/database/postgresql/tuples_returned_count查询处理时扫描的行数databasecloudsql.googleapis.com/database/postgresql/temp_bytes_written_count查询写入临时文件的总字节数databasecloudsql.googleapis.com/database/postgresql/temp_files_written_countjoin、sort 等算法使用临时文件数database复制与归档指标名说明附加标签cloudsql.googleapis.com/database/postgresql/external_sync/max_replica_byte_lagPostgres 外部服务器ES副本的字节复制延迟跨副本上所有库聚合—cloudsql.googleapis.com/database/replication/log_archive_success_countWAL 归档成功次数—cloudsql.googleapis.com/database/replication/log_archive_failure_countWAL 归档失败次数—工具二get_query_metrics查询级指标get_query_metrics用于以 PromQL 查询在 Postgres 实例中运行的查询的时序指标同样接受projectId与query两个必填参数。工具描述额外规定了几条查询构造约束从用户意图提取instance_id、query_hash等标签提供了query_hash时使用 per_query 指标query hash 与 query id 相同未提供 query id 时使用 aggregate 指标查 perquery 指标时除非用户明确要求不要抓取querystring标签并优先按query_hash聚合避免拉取完整 SQL 文本不要使用 latency 类指标配置描述明确写道 “Do not use latency metrics for anything”。与系统级指标的关键差异在于查询级指标使用受监控资源cloudsql_instance_database实例标签为resource_id格式同样是project_id:instance_id。示例 PromQL# 基础时间序列聚合执行时间 avg_over_time({__name__cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time,monitored_resourcecloudsql_instance_database,project_idmy-projectId,resource_idmy-projectId:my-instanceId}[5m]) # Top 30 慢查询聚合 topk(30, avg_over_time({__name__cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time,monitored_resourcecloudsql_instance_database,project_idmy-projectId,resource_idmy-projectId:my-instanceId}[5m])) # 按 resource_id 与 database 分组的 0.99 分位数 quantile by (resource_id,database)(0.99, avg_over_time({__name__cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time,monitored_resourcecloudsql_instance_database,project_idmy-projectId,resource_idmy-projectId:my-instanceId}[5m]))完整查询级指标清单18 项整理自 cloud-sql-postgres-observability.yaml受监控资源均为cloudsql_instance_database公共标签包含user、client_addr、project_id、resource_idaggregate全量聚合未提供 query id 时使用指标名说明附加标签cloudsql.googleapis.com/database/postgresql/insights/aggregate/latencies聚合查询延迟分布配置建议不用于分析—cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time自上次采样以来累计的聚合查询执行时间—cloudsql.googleapis.com/database/postgresql/insights/aggregate/io_time自上次采样以来累计的聚合 IO 时间io_typecloudsql.googleapis.com/database/postgresql/insights/aggregate/lock_time自上次采样以来累计的聚合锁等待时间lock_typecloudsql.googleapis.com/database/postgresql/insights/aggregate/row_count自上次采样以来聚合的取回/影响行数—cloudsql.googleapis.com/database/postgresql/insights/aggregate/shared_blk_access_count语句执行访问的共享块数access_typeperquery按查询聚合提供了 query_hash 时使用额外含querystring、query_hash标签指标名说明附加标签cloudsql.googleapis.com/database/postgresql/insights/perquery/latencies单查询延迟分布配置建议不用于分析querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/execution_time按用户/库/查询累计的执行时间querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/io_time按查询累计的 IO 时间io_type,querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/lock_time按查询累计的锁等待时间lock_type,querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/row_count按查询统计的取回/影响行数querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/shared_blk_access_count按查询统计的共享块访问access_type,querystring,query_hashpertag按 SQL 注释标签聚合额外含tag_hash及 OpenTelemetry 语义标签指标名说明附加标签cloudsql.googleapis.com/database/postgresql/insights/pertag/latencies按标签的查询延迟分布配置建议不用于分析action,application,controller,db_driver,framework,route,tag_hashcloudsql.googleapis.com/database/postgresql/insights/pertag/execution_time按标签累计的执行时间同上cloudsql.googleapis.com/database/postgresql/insights/pertag/io_time按标签累计的 IO 时间另含io_typecloudsql.googleapis.com/database/postgresql/insights/pertag/lock_time按标签累计的锁等待时间另含lock_typecloudsql.googleapis.com/database/postgresql/insights/pertag/shared_blk_access_count按标签的共享块访问另含access_typecloudsql.googleapis.com/database/postgresql/insights/pertag/row_count按标签统计的行数同上pertag 指标的存在意味着如果应用使用 SQL 注释标记如application、route、action等标签Agent 可以按业务维度而非 SQL 文本聚合执行时间便于做业务级慢查询归因。底层调用链PromQL 如何到达 Monitoring API两个工具共用同一实现。完整调用链为工具层internal/tools/cloudmonitoring/cloudmonitoring.go 中注册的cloud-monitoring-query-prometheus工具类型在Invoke中取出projectId、query后调用source.RunQuery(projectID, query)。Source 层internal/sources/cloudmonitoring/cloud_monitoring.go 的RunQuery向 Cloud Monitoring 的 Prometheus 兼容端点发起 GET 请求GET https://monitoring.googleapis.com/v1/projects/{projectID}/location/global/prometheus/api/v1/query?query{promql}请求携带 User-Agent响应非 200 时返回带状态与响应体的错误空 body 返回 nil否则将 JSON 反序列化为map[string]any后原样交给 Agent。从源码结构看这意味着工具返回的是 Prometheus 查询 API 的标准 JSON 结构status、data.result时序数组Agent 需要自行解释其中的样本点与标签。与同族预置配置的关系与适用边界docs/en/integrations/cloudmonitoring/prebuilt-configs/目录下还有三篇姊妹文档AlloyDB PostgreSQL Observability、Cloud SQL for MySQL Observability 和 Cloud SQL for SQL Server Observability结构与本文完全同构一个 monitoring source 系统/查询两个 PromQL 工具 一个 toolset只是指标清单和受监控资源不同。使用本预置配置时的边界与限制只读两个工具均带只读注解仅执行 PromQL 查询不会修改数据库或监控数据权限调用身份必须拥有roles/monitoring.viewer或等价权限否则 Monitoring API 会拒绝请求错误经ProcessGcpError透传给客户端指标依赖 Cloud SQL Insights查询级指标来自 Cloud SQL PostgreSQL 的 Insights 采集链路若实例未开启相应采集能力perquery/pertag 指标可能无数据这属于 GCP 侧前提而非 Toolbox 配置项适用场景构建时build-time让 Agent 帮助开发者排查资源利用率、连接与锁等待、复制延迟、事务年龄、慢查询归因等问题文档明确提示它不面向不受信任用户的运行时场景。小结cloud-sql-postgres-observability预置配置把“Cloud SQL for PostgreSQL Cloud Monitoring”的观测能力封装成了两条极简的 MCP 工具get_system_metrics26 项系统指标cloudsql_database资源database_id标签与get_query_metrics18 项查询级指标cloudsql_instance_database资源resource_id标签含 aggregate/perquery/pertag 三个粒度。启用只需--prebuilt cloud-sql-postgres-observability一行命令权限上确保roles/monitoring.viewer认证默认走 ADC可选useClientOAuth: true。工具的描述文本本身就是为 LLM 生成的指标字典与 PromQL 模板Agent 可以据此直接构造查询而对实现有疑问的读者可以沿 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 SQL for PostgreSQL Observability 预置配置详解：用 PromQL 查询系统级与查询级监控指标
MCP Toolbox Cloud SQL for PostgreSQL Observability 预置配置详解用 PromQL 查询系统级与查询级监控指标【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文围绕 MCP ToolboxMCP Toolbox for Databases的cloud-sql-postgres-observability预置配置展开讲清它包含的get_system_metrics与get_query_metrics两个 PromQL 查询工具、roles/monitoring.viewer权限前提、全部可用指标的元数据以及底层cloud-monitoringsource 如何把 PromQL 请求转发到 Google Cloud Monitoring Prometheus 端点。读完本文你可以直接在启动 MCP Toolbox 服务时启用该预置配置让 Agent 对 Cloud SQL for PostgreSQL 实例做资源利用率、连接数、死锁、复制延迟、事务年龄以及慢查询执行时间等维度的时序指标分析。配置概览与启用方式该预置配置在 CLI 中的--prebuilt取值为cloud-sql-postgres-observability其完整定义位于 internal/prebuiltconfigs/tools/cloud-sql-postgres-observability.yaml。YAML 文件由三段组成一个cloud-monitoring类型的 sourcecloud-monitoring-source、两个cloud-monitoring-query-prometheus类型的 tool以及一个把它们打包在一起的 toolsetkind: source name: cloud-monitoring-source type: cloud-monitoring --- kind: tool name: get_system_metrics type: cloud-monitoring-query-prometheus source: cloud-monitoring-source description: | ...系统指标查询说明与指标清单见下文 --- kind: tool name: get_query_metrics type: cloud-monitoring-query-prometheus source: cloud-monitoring-source description: | ...查询级指标查询说明与指标清单见下文 --- kind: toolset name: cloud_sql_postgres_cloud_monitoring_tools tools: - get_system_metrics - get_query_metrics启动方式摘自 docs/en/reference/cli.md 的用法示例# 单独启用该预置配置 ./toolbox --prebuilt cloud-sql-postgres-observability # 与其他预置配置叠加例如 PostgreSQL 数据库工具 监控工具 ./toolbox --prebuilt cloud-sql-postgres --prebuilt cloud-sql-postgres-observability # 与自定义配置文件组合 ./toolbox --config tools.yaml --prebuilt cloud-sql-postgres-observability几个实现细节可以印证其工作方式--prebuilt是一个StringSliceVar标志允许重复指定多个取值帮助文本会动态列出所有可用预置名见 cmd/internal/flags.go。所有预置 YAML 通过go:embed打包进二进制按“文件名去掉.yaml后缀”作为 key 注册见 internal/prebuiltconfigs/prebuiltconfigs.go。因此cloud-sql-postgres-observability这个 key 正是来自文件名cloud-sql-postgres-observability.yaml。预置配置还支持 toolset 后缀过滤如--prebuilt source/toolset只加载指定 toolset本配置的 toolset 名为cloud_sql_postgres_cloud_monitoring_tools。回归测试TestPrebuiltTools显式加载了该配置确保其 YAML 可被正常解析见 cmd/internal/config_test.go。官方同时提醒预置配置面向“构建时build-time”场景即 Agent 协助受信任开发者构建东西它们不适用于 Agent 直接面向不受信任用户的“运行时run-time”场景见 docs/en/documentation/configuration/prebuilt-configs/_index.md。权限与认证前提文档明确要求在项目上需要Monitoring Viewerroles/monitoring.viewer角色才能查看监控数据。该要求与 cloud-monitoring-query-prometheus 工具文档中的 IAM 要求一致。认证方面cloud-monitoringsource 支持两种方式见 docs/en/integrations/cloudmonitoring/source.md应用默认凭证ADC默认行为source 使用 ADC 向 Monitoring API 鉴权客户端 OAuthsource 配置中设置useClientOAuth: true时由客户端如浏览器在每个请求中提供 OAuth 2.0 access token。从源码看internal/sources/cloudmonitoring/cloud_monitoring.goInitialize在UseClientOAuth为 false 时调用google.FindDefaultCredentials(ctx, monitoring.MonitoringScope)获取 ADC 令牌源并构造oauth2HTTP 客户端为 true 时则使用普通 HTTP 客户端等待请求级 access token。两个工具本身都带有只读注解tools.GetAnnotationsOrDefault(..., tools.NewReadOnlyAnnotations)见 internal/tools/cloudmonitoring/cloudmonitoring.go且Authorized方法恒返回 true——鉴权强制完全委托给底层 GCP 凭证即上一节的roles/monitoring.viewer。工具一get_system_metrics系统级指标get_system_metrics用于以 PromQL 查询某个 Postgres 实例的系统级时序指标。它的入参只有两个在工具代码内部硬编码而非来自 YAML参数类型必填说明projectIdstring是Google Cloud 项目 IDquerystring是要执行的 PromQL 查询参数定义与调用逻辑见 internal/tools/cloudmonitoring/cloudmonitoring.goInvoke从参数映射中取出projectId与query直接调用 source 的RunQuery(projectID, query)任何错误经util.ProcessGcpError包装后返回给 Agent。查询构造约定工具描述写给 LLM 的 prompt中内置了构造规则理解这些规则有助于手写query默认时间窗口对*_over_time聚合函数除非用户另行指定默认使用5m区间。标签来源instance_id等标签从用户意图中提取database_id标签实际是实例 ID格式为project_id:instance_id。受监控资源系统指标统一使用monitored_resource cloudsql_database。示例 PromQL以下示例取自预置配置的描述文本以 CPU 利用率指标为例占位符替换为真实值即可运行# 基础时间序列 avg_over_time({__name__cloudsql.googleapis.com/database/cpu/utilization,monitored_resourcecloudsql_database,project_idmy-projectId,database_idmy-projectId:my-instanceId}[5m]) # Top K topk(30, avg_over_time({__name__cloudsql.googleapis.com/database/cpu/utilization,monitored_resourcecloudsql_database,project_idmy-projectId,database_idmy-projectId:my-instanceId}[5m])) # 均值 / 最小 / 最大 / 求和 / 流计数 avg(avg_over_time({...}[5m])) min(min_over_time({...}[5m])) max(max_over_time({...}[5m])) sum(avg_over_time({...}[5m])) count(avg_over_time({...}[5m])) # 按 database_id 分组的 0.99 分位数 quantile by (database_id)(0.99, avg_over_time({...}[5m]))完整系统指标清单26 项下表完整整理自 cloud-sql-postgres-observability.yaml均为cloudsql_database受监控资源下的指标共同标签包含project_id、database_id资源与 IO指标名说明附加标签cloudsql.googleapis.com/database/cpu/utilization当前 CPU 利用率相对预留 CPU 的百分比值通常为 0.0–1.0可能超过 1.0图表以 0%–100% 展示—cloudsql.googleapis.com/database/memory/components数据库内存统计组件按 usage、cache、free 等以百分比表示componentcloudsql.googleapis.com/database/disk/bytes_used_by_data_type按数据类型的磁盘数据使用量字节data_typecloudsql.googleapis.com/database/disk/read_ops_count数据盘读 IO 操作增量计数—cloudsql.googleapis.com/database/disk/write_ops_count数据盘写 IO 操作增量计数—cloudsql.googleapis.com/database/network/received_bytes_count网络接收字节增量计数—cloudsql.googleapis.com/database/network/sent_bytes_count网络发送字节增量计数destinationcloudsql.googleapis.com/database/postgresql/blocks_read_count数据库读取的磁盘块数source字段区分实际磁盘读与 buffer cache 读database,source连接与后端指标名说明附加标签cloudsql.googleapis.com/database/postgresql/new_connection_count新增连接数databasecloudsql.googleapis.com/database/postgresql/num_backends实例连接总数databasecloudsql.googleapis.com/database/postgresql/num_backends_by_state按状态分组的连接数database,statecloudsql.googleapis.com/database/postgresql/num_backends_by_application按应用分组的连接数applicationcloudsql.googleapis.com/database/postgresql/backends_in_wait处于等待状态的后端数backend_type,wait_event,wait_event_type事务与锁指标名说明附加标签cloudsql.googleapis.com/database/postgresql/transaction_count事务数增量计数database,transaction_typecloudsql.googleapis.com/database/postgresql/transaction_id_utilization事务 ID 消耗百分比0.0–1.0图表以 0%–100% 展示—cloudsql.googleapis.com/database/postgresql/deadlock_count检测到的死锁数databasecloudsql.googleapis.com/database/postgresql/vacuum/oldest_transaction_age最老待 vacuum 事务的年龄以自该事务以来发生的事务数计oldest_transaction_type数据与查询行为按库统计指标名说明附加标签cloudsql.googleapis.com/database/postgresql/tuples_processed_countinsert/update/delete 等操作处理的行数operation_type,databasecloudsql.googleapis.com/database/postgresql/tuple_size数据库中元组行数database,tuple_statecloudsql.googleapis.com/database/postgresql/tuples_fetched_count查询取回的行数databasecloudsql.googleapis.com/database/postgresql/tuples_returned_count查询处理时扫描的行数databasecloudsql.googleapis.com/database/postgresql/temp_bytes_written_count查询写入临时文件的总字节数databasecloudsql.googleapis.com/database/postgresql/temp_files_written_countjoin、sort 等算法使用临时文件数database复制与归档指标名说明附加标签cloudsql.googleapis.com/database/postgresql/external_sync/max_replica_byte_lagPostgres 外部服务器ES副本的字节复制延迟跨副本上所有库聚合—cloudsql.googleapis.com/database/replication/log_archive_success_countWAL 归档成功次数—cloudsql.googleapis.com/database/replication/log_archive_failure_countWAL 归档失败次数—工具二get_query_metrics查询级指标get_query_metrics用于以 PromQL 查询在 Postgres 实例中运行的查询的时序指标同样接受projectId与query两个必填参数。工具描述额外规定了几条查询构造约束从用户意图提取instance_id、query_hash等标签提供了query_hash时使用 per_query 指标query hash 与 query id 相同未提供 query id 时使用 aggregate 指标查 perquery 指标时除非用户明确要求不要抓取querystring标签并优先按query_hash聚合避免拉取完整 SQL 文本不要使用 latency 类指标配置描述明确写道 “Do not use latency metrics for anything”。与系统级指标的关键差异在于查询级指标使用受监控资源cloudsql_instance_database实例标签为resource_id格式同样是project_id:instance_id。示例 PromQL# 基础时间序列聚合执行时间 avg_over_time({__name__cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time,monitored_resourcecloudsql_instance_database,project_idmy-projectId,resource_idmy-projectId:my-instanceId}[5m]) # Top 30 慢查询聚合 topk(30, avg_over_time({__name__cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time,monitored_resourcecloudsql_instance_database,project_idmy-projectId,resource_idmy-projectId:my-instanceId}[5m])) # 按 resource_id 与 database 分组的 0.99 分位数 quantile by (resource_id,database)(0.99, avg_over_time({__name__cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time,monitored_resourcecloudsql_instance_database,project_idmy-projectId,resource_idmy-projectId:my-instanceId}[5m]))完整查询级指标清单18 项整理自 cloud-sql-postgres-observability.yaml受监控资源均为cloudsql_instance_database公共标签包含user、client_addr、project_id、resource_idaggregate全量聚合未提供 query id 时使用指标名说明附加标签cloudsql.googleapis.com/database/postgresql/insights/aggregate/latencies聚合查询延迟分布配置建议不用于分析—cloudsql.googleapis.com/database/postgresql/insights/aggregate/execution_time自上次采样以来累计的聚合查询执行时间—cloudsql.googleapis.com/database/postgresql/insights/aggregate/io_time自上次采样以来累计的聚合 IO 时间io_typecloudsql.googleapis.com/database/postgresql/insights/aggregate/lock_time自上次采样以来累计的聚合锁等待时间lock_typecloudsql.googleapis.com/database/postgresql/insights/aggregate/row_count自上次采样以来聚合的取回/影响行数—cloudsql.googleapis.com/database/postgresql/insights/aggregate/shared_blk_access_count语句执行访问的共享块数access_typeperquery按查询聚合提供了 query_hash 时使用额外含querystring、query_hash标签指标名说明附加标签cloudsql.googleapis.com/database/postgresql/insights/perquery/latencies单查询延迟分布配置建议不用于分析querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/execution_time按用户/库/查询累计的执行时间querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/io_time按查询累计的 IO 时间io_type,querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/lock_time按查询累计的锁等待时间lock_type,querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/row_count按查询统计的取回/影响行数querystring,query_hashcloudsql.googleapis.com/database/postgresql/insights/perquery/shared_blk_access_count按查询统计的共享块访问access_type,querystring,query_hashpertag按 SQL 注释标签聚合额外含tag_hash及 OpenTelemetry 语义标签指标名说明附加标签cloudsql.googleapis.com/database/postgresql/insights/pertag/latencies按标签的查询延迟分布配置建议不用于分析action,application,controller,db_driver,framework,route,tag_hashcloudsql.googleapis.com/database/postgresql/insights/pertag/execution_time按标签累计的执行时间同上cloudsql.googleapis.com/database/postgresql/insights/pertag/io_time按标签累计的 IO 时间另含io_typecloudsql.googleapis.com/database/postgresql/insights/pertag/lock_time按标签累计的锁等待时间另含lock_typecloudsql.googleapis.com/database/postgresql/insights/pertag/shared_blk_access_count按标签的共享块访问另含access_typecloudsql.googleapis.com/database/postgresql/insights/pertag/row_count按标签统计的行数同上pertag 指标的存在意味着如果应用使用 SQL 注释标记如application、route、action等标签Agent 可以按业务维度而非 SQL 文本聚合执行时间便于做业务级慢查询归因。底层调用链PromQL 如何到达 Monitoring API两个工具共用同一实现。完整调用链为工具层internal/tools/cloudmonitoring/cloudmonitoring.go 中注册的cloud-monitoring-query-prometheus工具类型在Invoke中取出projectId、query后调用source.RunQuery(projectID, query)。Source 层internal/sources/cloudmonitoring/cloud_monitoring.go 的RunQuery向 Cloud Monitoring 的 Prometheus 兼容端点发起 GET 请求GET https://monitoring.googleapis.com/v1/projects/{projectID}/location/global/prometheus/api/v1/query?query{promql}请求携带 User-Agent响应非 200 时返回带状态与响应体的错误空 body 返回 nil否则将 JSON 反序列化为map[string]any后原样交给 Agent。从源码结构看这意味着工具返回的是 Prometheus 查询 API 的标准 JSON 结构status、data.result时序数组Agent 需要自行解释其中的样本点与标签。与同族预置配置的关系与适用边界docs/en/integrations/cloudmonitoring/prebuilt-configs/目录下还有三篇姊妹文档AlloyDB PostgreSQL Observability、Cloud SQL for MySQL Observability 和 Cloud SQL for SQL Server Observability结构与本文完全同构一个 monitoring source 系统/查询两个 PromQL 工具 一个 toolset只是指标清单和受监控资源不同。使用本预置配置时的边界与限制只读两个工具均带只读注解仅执行 PromQL 查询不会修改数据库或监控数据权限调用身份必须拥有roles/monitoring.viewer或等价权限否则 Monitoring API 会拒绝请求错误经ProcessGcpError透传给客户端指标依赖 Cloud SQL Insights查询级指标来自 Cloud SQL PostgreSQL 的 Insights 采集链路若实例未开启相应采集能力perquery/pertag 指标可能无数据这属于 GCP 侧前提而非 Toolbox 配置项适用场景构建时build-time让 Agent 帮助开发者排查资源利用率、连接与锁等待、复制延迟、事务年龄、慢查询归因等问题文档明确提示它不面向不受信任用户的运行时场景。小结cloud-sql-postgres-observability预置配置把“Cloud SQL for PostgreSQL Cloud Monitoring”的观测能力封装成了两条极简的 MCP 工具get_system_metrics26 项系统指标cloudsql_database资源database_id标签与get_query_metrics18 项查询级指标cloudsql_instance_database资源resource_id标签含 aggregate/perquery/pertag 三个粒度。启用只需--prebuilt cloud-sql-postgres-observability一行命令权限上确保roles/monitoring.viewer认证默认走 ADC可选useClientOAuth: true。工具的描述文本本身就是为 LLM 生成的指标字典与 PromQL 模板Agent 可以据此直接构造查询而对实现有疑问的读者可以沿 source 实现、工具实现 和 预置配置加载逻辑 三处源码继续深入。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
