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 |
1---2name: cloud-metrics3description: 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.4---5
6# Cloud Metrics
7
8Query GCP Monitoring API using the bundled `cloud_metrics.py` script.
9
10## Prerequisites
11
12Requires GCP authentication. Verify with:
13```bash
14gcloud auth application-default print-access-token
15```
16
17If not authenticated:
18```bash
19gcloud auth application-default login
20```
21
22## Quick Reference
23
24```bash
25# Run with uv (handles dependencies automatically)
26uv run scripts/cloud_metrics.py <command> [options]
27
28# Commands
29query # Query metric data
30describe # Show metric labels and filter examples
31list # List available metrics
32```
33
34## Common Workflows
35
36### Find top resource consumers
37
38```bash
39# Top 10 CPU consumers
40uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time --top 10 --stats
41
42# Top memory users with latest values
43uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/memory/used_bytes --top 20 --latest
44```
45
46### Explore available metrics
47
48```bash
49# List all kubernetes metrics
50uv run scripts/cloud_metrics.py list -p PROJECT --prefix kubernetes.io
51
52# Describe a metric (shows available labels for filtering)
53uv run scripts/cloud_metrics.py describe -p PROJECT -m kubernetes.io/container/cpu/core_usage_time
54```
55
56### Query with filters and aggregation
57
58```bash
59# Filter by namespace
60uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
61 -f 'resource.labels.namespace_name="production"'
62
63# Aggregate across containers, group by namespace
64uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
65 --reducer REDUCE_SUM --group-by namespace_name
66
67# Specific time range
68uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
69 --start 2025-01-01T00:00:00Z --end 2025-01-01T12:00:00Z
70```
71
72### Export data
73
74```bash
75# JSON output (for jq processing)
76uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
77 --output json --stats | jq '.[] | select(.stats.max > 0.5)'
78
79# CSV output
80uv run scripts/cloud_metrics.py query -p PROJECT -m kubernetes.io/container/cpu/core_usage_time \
81 --output csv --latest > cpu_usage.csv
82```
83
84## Key Options
85
86| Option | Description |
87|--------|-------------|
88| `-p, --project` | GCP project ID (required) |
89| `-m, --metric` | Metric type (required for query/describe) |
90| `-f, --filter` | Filter expression (repeatable) |
91| `-d, --duration` | Time range: `30m`, `1h`, `7d` (default: 1h) |
92| `--aligner` | ALIGN_RATE, ALIGN_MEAN, ALIGN_SUM, ALIGN_MAX, ALIGN_MIN, ALIGN_DELTA |
93| `--reducer` | REDUCE_SUM, REDUCE_MEAN, REDUCE_MAX, REDUCE_COUNT, REDUCE_PERCENTILE_99/95/50 |
94| `--group-by` | Label to group by when using reducer |
95| `--top N` | Show only top N series by max value |
96| `--stats` | Show statistics (min, max, avg, p50, p95, p99) |
97| `--latest` | Show only latest value per series |
98| `-o, --output` | `table` (default), `json`, `csv` |
99
100## Common Metric Types
101
102| Metric | Description |
103|--------|-------------|
104| `kubernetes.io/container/cpu/core_usage_time` | CPU usage (use ALIGN_RATE) |
105| `kubernetes.io/container/memory/used_bytes` | Memory usage |
106| `kubernetes.io/container/restart_count` | Container restarts |
107| `kubernetes.io/pod/network/received_bytes_count` | Network RX |
108| `kubernetes.io/pod/network/sent_bytes_count` | Network TX |
109| `compute.googleapis.com/instance/cpu/utilization` | VM CPU utilization |
110| `compute.googleapis.com/instance/disk/read_bytes_count` | Disk reads |
majiayu000