Cloud Metrics

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

Common Metric Types