mcpField
P
prometheus

prometheus

github.com/ionfuryCloud & DevOps2572 installsUpdated today
Repository

About prometheus

A Prometheus querying skill for a Kubernetes monitoring setup where Prometheus and Alertmanager sit behind OAuth2 Proxy. It documents pod access, port forwarding, and a bundled script for instant and range PromQL queries.

Key features

  1. 01Query Prometheus from a pod
  2. 02Access APIs through port forwarding
  3. 03Run instant PromQL queries
  4. 04Run range queries with time steps
  5. 05Review common CPU, memory, and pod queries

Use cases

  1. 01Check whether monitored targets are up
  2. 02Inspect CPU and memory usage
  3. 03Find pods outside running or succeeded states
  4. 04Run repeated queries through a local port-forward

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ionfury/homelab --skill prometheus

After installing, type/prometheusin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

tests.yaml
references/
queries.md
scripts/
promql.sh

Details

From the project README

Prometheus Querying

Setup

Prometheus and Alertmanager are behind OAuth2 Proxy on the internal gateway. DNS URLs (https://prometheus.internal.tomnowak.work) redirect to an OAuth login page and cannot be used for API queries via curl.

Access Methods

Option 1: kubectl exec (quick, no setup)

# Query Prometheus API directly inside the pod
kubectl --context <cluster> exec -n monitoring prometheus-kube-prometheus-stack-0 -c prometheus -- \
  wget -qO- 'http://localhost:9090/api/v1/query?query=up' | jq '.data.result'

# Query Alertmanager API
kubectl --context <cluster> exec -n monitoring alertmanager-kube-prometheus-stack-0 -c alertmanager -- \
  wget -qO- 'http://localhost:9093/api/v2/alerts' | jq .

Option 2: Port-forward (for scripts and repeated queries)

kubectl --context <cluster> port-forward -n monitoring svc/prometheus-operated 9090:9090 &
export PROMETHEUS_URL=http://localhost:9090

The promql.sh script defaults to http://localhost:9090 and works with port-forward out of the box.

Quick Queries

Use the bundled script at .claude/skills/prometheus/scripts/promql.sh:

# Start port-forward first (script defaults to http://localhost:9090)
kubectl --context <cluster> port-forward -n monitoring svc/prometheus-operated 9090:9090 &

# Instant query
./scripts/promql.sh query 'up'

# Range query (last hour, 15s resolution)
./scripts/promql.sh range 'node_cpu_seconds_total' --start 1h --step 15s

# Firing alerts only
./scripts/promql.sh alerts --firing

# All alert rules
./scripts/promql.sh rules

# Find metrics by label
./scripts/promql.sh series '{job="node-exporter"}'

# Health check
./scripts/promql.sh health

Common Queries

# CPU usage %
./scripts/promql.sh query 'avg(1 - rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100'

# Memory usage %
./scripts/promql.sh query '(1 - sum(node_memory_MemAvailable_bytes) / sum(node_memory_MemTotal_bytes)) * 100'

# Problem pods
./scripts/promql.sh query 'kube_pod_status_phase{phase!~"Running|Succeeded"} == 1'

# Container restarts (last hour)
./scripts/promql.sh query 'increase(kube_pod_container_status_restarts_total[1h]) > 0'

# Firing alerts
./scripts/promql.sh alerts --firing

# Full alert details
./scripts/promql.sh alerts --verbose

Creating Monitoring Resources

This skill covers querying Prometheus. For authoring new monitoring resources (PrometheusRules, ServiceMonitors, PodMonitors, AlertmanagerConfig, recording rules), see the monitoring-authoring skill.

Prometheus Details

PropertyValue
Namespacemonitoring
Serviceprometheus-operated:9090
Retention14 days / 50GB
External labelprometheus_source: ${cluster_name}

Comments

Markdown supported