cloud-metrics

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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill enables seamless interaction with Google Cloud Monitoring (GCP) to query, analyze, and export critical infrastructure and Kubernetes metrics. It simplifies complex observability tasks by allowing users to retrieve real-time data on CPU usage, memory consumption, and network traffic through natural language, effectively bridging the gap between the GCP Monitoring API and actionable insights.

Use Cases

  • 1. Kubernetes Resource Optimization: Identify the top 10 CPU or memory-consuming containers to optimize cluster performance and manage cloud costs effectively.
  • 2. Rapid Incident Troubleshooting: Quickly query network latency, disk I/O, or container restart counts during system outages to pinpoint root causes in GCP environments.
  • 3. Automated Performance Reporting: Generate and export specific monitoring data into CSV or JSON formats for stakeholder reports or further analysis with data tools.
  • 4. Infrastructure Auditing: List and describe available metrics and labels across different GCP projects to ensure comprehensive monitoring coverage and visibility.
namecloud-metrics
descriptionQuery 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.

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