tmolavi/mcp-agent-skills-hub/alloydb-postgres-monitor

Usage

All scripts can be executed using Node.js. Replace <param_name> and <param_value> with actual values.

Bash: node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'

PowerShell: node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'

Note: The scripts automatically load the environment variables from various .env files. Do not ask the user to set vars unless skill executions fails due to env var absence.

Scripts

get_query_metrics

Fetches query level cloudmonitoring data (timeseries metrics) for queries running in an AlloyDB instance. To use this tool, you must provide the Google Cloud projectId and a PromQL query.

Generate the PromQL query for AlloyDB query metrics using the provided metrics and rules. Get labels like cluster_id, instance_id, and query_hash from the user's intent. If query_hash is provided, use the per-query metrics.

Defaults:

1. Interval: Use a default interval of 5m for _over_time aggregation functions unless a different window is specified by the user.

PromQL Query Examples:

1. Basic Time Series: avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance"}[5m])
2. Top K: topk(30, avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance"}[5m]))
3. Mean: avg(avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="my-instance","cluster_id"="my-cluster"}[5m]))
4. Minimum: min(min_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
5. Maximum: max(max_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
6. Sum: sum(avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
7. Count streams: count(avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
8. Percentile with groupby on instanceid, clusterid: quantile by ("instance_id","cluster_id")(0.99,avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","cluster_id"="my-cluster","instance_id"="my-instance"}[5m]))

Available Metrics List: metricname. description. monitored resource. labels. aggregate is the aggregated values for all query stats, Use aggregate metrics if query id is not provided. For perquery metrics do not fetch querystring unless specified by user specifically. Have the aggregation on query hash to avoid fetching the querystring. Do not use latency metrics for anything.

1. alloydb.googleapis.com/database/postgresql/insights/aggregate/latencies: Aggregated query latency distribution. alloydb.googleapis.com/Database. user, client_addr.
2. alloydb.googleapis.com/database/postgresql/insights/aggregate/execution_time: Accumulated aggregated query execution time since the last sample. alloydb.googleapis.com/Database. user, client_addr.
3. alloydb.googleapis.com/database/postgresql/insights/aggregate/io_time: Accumulated aggregated IO time since the last sample. alloydb.googleapis.com/Database. user, client_addr, io_type.
4. alloydb.googleapis.com/database/postgresql/insights/aggregate/lock_time: Accumulated aggregated lock wait time since the last sample. alloydb.googleapis.com/Database. user, client_addr, lock_type.
5. alloydb.googleapis.com/database/postgresql/insights/aggregate/row_count: Aggregated number of retrieved or affected rows since the last sample. alloydb.googleapis.com/Database. user, client_addr.
6. alloydb.googleapis.com/database/postgresql/insights/aggregate/shared_blk_access_count: Aggregated shared blocks accessed by statement execution. alloydb.googleapis.com/Database. user, client_addr, access_type.
7. alloydb.googleapis.com/database/postgresql/insights/perquery/latencies: Per query latency distribution. alloydb.googleapis.com/Database. user, client_addr, querystring, query_hash.
8. alloydb.googleapis.com/database/postgresql/insights/perquery/execution_time: Accumulated execution times per user per database per query. alloydb.googleapis.com/Database. user, client_addr, querystring, query_hash.
9. alloydb.googleapis.com/database/postgresql/insights/perquery/io_time: Accumulated IO time since the last sample per query. alloydb.googleapis.com/Database. user, client_addr, io_type, querystring, query_hash.
10. alloydb.googleapis.com/database/postgresql/insights/perquery/lock_time: Accumulated lock wait time since the last sample per query. alloydb.googleapis.com/Database. user, client_addr, lock_type, querystring, query_hash.
11. alloydb.googleapis.com/database/postgresql/insights/perquery/row_count: The number of retrieved or affected rows since the last sample per query. alloydb.googleapis.com/Database. user, client_addr, querystring, query_hash.
12. alloydb.googleapis.com/database/postgresql/insights/perquery/shared_blk_access_count: Shared blocks accessed by statement execution per query. alloydb.googleapis.com/Database. user, client_addr, access_type, querystring, query_hash.
13. alloydb.googleapis.com/database/postgresql/insights/pertag/latencies: Query latency distribution. alloydb.googleapis.com/Database. user, client_addr, action, application, controller, db_driver, framework, route, tag_hash.
14. alloydb.googleapis.com/database/postgresql/insights/pertag/execution_time: Accumulated execution times since the last sample. alloydb.googleapis.com/Database. user, client_addr, action, application, controller, db_driver, framework, route, tag_hash.
15. alloydb.googleapis.com/database/postgresql/insights/pertag/io_time: Accumulated IO time since the last sample per tag. alloydb.googleapis.com/Database. user, client_addr, action, application, controller, db_driver, framework, route, io_type, tag_hash.
16. alloydb.googleapis.com/database/postgresql/insights/pertag/lock_time: Accumulated lock wait time since the last sample per tag. alloydb.googleapis.com/Database. user, client_addr, action, application, controller, db_driver, framework, route, lock_type, tag_hash.
17. alloydb.googleapis.com/database/postgresql/insights/pertag/shared_blk_access_count: Shared blocks accessed by statement execution per tag. alloydb.googleapis.com/Database. user, client_addr, action, application, controller, db_driver, framework, route, access_type, tag_hash.
18. alloydb.googleapis.com/database/postgresql/insights/pertag/row_count: The number of retrieved or affected rows since the last sample per tag. alloydb.googleapis.com/Database. user, client_addr, action, application, controller, db_driver, framework, route, tag_hash.

Parameters

get_query_plan

Generate a PostgreSQL EXPLAIN plan in JSON format for a single SQL statement—without executing it. This returns the optimizer's estimated plan, costs, and rows (no ANALYZE, no extra options). Use in production safely for plan inspection, regression checks, and query tuning workflows.

Parameters

get_system_metrics

Fetches system level cloudmonitoring data (timeseries metrics) for an AlloyDB cluster, instance. To use this tool, you must provide the Google Cloud projectId and a PromQL query.

Generate the PromQL query for AlloyDB system metrics using the provided metrics and rules. Get labels like cluster_id and instance_id from the user's intent.

Defaults:

1. Interval: Use a default interval of 5m for _over_time aggregation functions unless a different window is specified by the user.

PromQL Query Examples:

1. Basic Time Series: avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance"}[5m])
2. Top K: topk(30, avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance"}[5m]))
3. Mean: avg(avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="my-instance","cluster_id"="my-cluster"}[5m]))
4. Minimum: min(min_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
5. Maximum: max(max_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
6. Sum: sum(avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
7. Count streams: count(avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","instance_id"="alloydb-instance","cluster_id"="alloydb-cluster"}[5m]))
8. Percentile with groupby on instanceid, clusterid: quantile by ("instance_id","cluster_id")(0.99,avg_over_time({"__name__"="alloydb.googleapis.com/instance/cpu/average_utilization","monitored_resource"="alloydb.googleapis.com/Instance","cluster_id"="my-cluster","instance_id"="my-instance"}[5m]))