Google Cloud Metrics Skill

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

Time Range Guidance

Default to the smallest range that answers the question. Start with 15m (the default) and only widen if the user explicitly asks for a longer window, the metric is sparse, or you need historical comparison. Larger ranges return more data, cost more, and are slower — do not pass -d 1h/2h/24h unless the user asked or you've justified it.

Common Workflows

Find top resource consumers

# Top 10 CPU consumers (ALIGN_RATE is the default — converts cumulative core_usage_time to cores)
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 (use only when investigating a known incident window)
uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
  --start 2025-01-01T14:00:00Z --end 2025-01-01T14:15: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

Common Metric Types