cloud-metrics
Query Google Cloud Monitoring metrics using the cloud_metrics.py tool. Use when users ask about GCP metrics, Cloud Monitoring, Kubernetes metrics (CPU, memory, network), container resource usage, or need to export monitoring data. Triggers on requests like "show me CPU usage", "list available metrics", "describe this metric", "top memory consumers", or any Google Cloud Monitoring queries.
When & Why to Use This Skill
This Claude skill enables seamless interaction with Google Cloud Monitoring (GCP) to query, analyze, and export critical infrastructure and Kubernetes metrics. It simplifies complex observability tasks by allowing users to retrieve real-time data on CPU usage, memory consumption, and network traffic through natural language, effectively bridging the gap between the GCP Monitoring API and actionable insights.
Use Cases
- 1. Kubernetes Resource Optimization: Identify the top 10 CPU or memory-consuming containers to optimize cluster performance and manage cloud costs effectively.
- 2. Rapid Incident Troubleshooting: Quickly query network latency, disk I/O, or container restart counts during system outages to pinpoint root causes in GCP environments.
- 3. Automated Performance Reporting: Generate and export specific monitoring data into CSV or JSON formats for stakeholder reports or further analysis with data tools.
- 4. Infrastructure Auditing: List and describe available metrics and labels across different GCP projects to ensure comprehensive monitoring coverage and visibility.
| name | cloud-metrics |
|---|---|
| description | Query Google Cloud Monitoring metrics using the cloud_metrics.py tool. Use when users ask about GCP metrics, Cloud Monitoring, Kubernetes metrics (CPU, memory, network), container resource usage, or need to export monitoring data. Triggers on requests like "show me CPU usage", "list available metrics", "describe this metric", "top memory consumers", or any Google Cloud Monitoring queries. |
Cloud Metrics
Query GCP Monitoring API using the bundled cloud_metrics.py script.
Prerequisites
Requires GCP authentication. Verify with:
gcloud auth application-default print-access-token
If not authenticated:
gcloud auth application-default login
Quick Reference
# Run with uv (handles dependencies automatically)
uv run scripts/cloud_metrics.py <command> [options]
# Commands
query # Query metric data
describe # Show metric labels and filter examples
list # List available metrics
Common Workflows
Find top resource consumers
# Top 10 CPU consumers
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time --top 10 --stats
# Top memory users with latest values
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/memory/used_bytes --top 20 --latest
Explore available metrics
# List all kubernetes metrics
uv run scripts/cloud_metrics.py list -p PROJECT --prefix kubernetes.io
# Describe a metric (shows available labels for filtering)
uv run scripts/cloud_metrics.py describe -p PROJECT -m kubernetes.io/container/cpu/core_usage_time
Query with filters and aggregation
# Filter by namespace
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
-f 'resource.labels.namespace_name="production"'
# Aggregate across containers, group by namespace
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
--reducer REDUCE_SUM --group-by namespace_name
# Specific time range
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
--start 2025-01-01T00:00:00Z --end 2025-01-01T12:00:00Z
Export data
# JSON output (for jq processing)
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
--output json --stats | jq '.[] | select(.stats.max > 0.5)'
# CSV output
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
--output csv --latest > cpu_usage.csv
Key Options
| Option | Description |
|---|---|
-p, --project |
GCP project ID (required) |
-m, --metric |
Metric type (required for query/describe) |
-f, --filter |
Filter expression (repeatable) |
-d, --duration |
Time range: 30m, 1h, 7d (default: 1h) |
--aligner |
ALIGN_RATE, ALIGN_MEAN, ALIGN_SUM, ALIGN_MAX, ALIGN_MIN, ALIGN_DELTA |
--reducer |
REDUCE_SUM, REDUCE_MEAN, REDUCE_MAX, REDUCE_COUNT, REDUCE_PERCENTILE_99/95/50 |
--group-by |
Label to group by when using reducer |
--top N |
Show only top N series by max value |
--stats |
Show statistics (min, max, avg, p50, p95, p99) |
--latest |
Show only latest value per series |
-o, --output |
table (default), json, csv |
Common Metric Types
| Metric | Description |
|---|---|
kubernetes.io/container/cpu/core_usage_time |
CPU usage (use ALIGN_RATE) |
kubernetes.io/container/memory/used_bytes |
Memory usage |
kubernetes.io/container/restart_count |
Container restarts |
kubernetes.io/pod/network/received_bytes_count |
Network RX |
kubernetes.io/pod/network/sent_bytes_count |
Network TX |
compute.googleapis.com/instance/cpu/utilization |
VM CPU utilization |
compute.googleapis.com/instance/disk/read_bytes_count |
Disk reads |