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 |