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

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: 15m, 30m, 1h, 7d (default: 15m)
--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	json (default), table, 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