mcpField
P
prometheus-api

prometheus-api

github.com/julianobarbosaCloud & DevOps1459 installsUpdated 2d ago
Repository

About prometheus-api

A skill for querying Prometheus monitoring systems through the HTTP API, with command-line scripts for queries and health checks. It is intended for users inspecting metrics, targets, alerts, and system status.

Key features

  1. 01Instant and range queries
  2. 02Series, labels, and metadata lookup
  3. 03Target, alert, and rule inspection
  4. 04Prometheus status endpoint access
  5. 05Query and health-check scripts

Use cases

  1. 01Inspecting a metric at a point in time
  2. 02Tracking metric values over a time range
  3. 03Checking active targets and alerts
  4. 04Reviewing Prometheus runtime and TSDB status

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/julianobarbosa/claude-code-skills --skill prometheus-api

After installing, type/prometheus-apiin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
api_reference.md
promql_functions.md
scripts/
prom_health.py
prom_metadata.py
prom_query.py

Details

From the project README

Prometheus API Skill

Query Prometheus monitoring systems via HTTP API at /api/v1.

Quick Reference

Instant Query
curl 'http://<prometheus>:9090/api/v1/query?query=<promql>&time=<timestamp>'
Range Query
curl 'http://<prometheus>:9090/api/v1/query_range?query=<promql>&start=<ts>&end=<ts>&step=<duration>'

Response Format

All responses return JSON:

{
  "status": "success" | "error",
  "data": <result>,
  "errorType": "<string>",
  "error": "<string>",
  "warnings": ["<string>"]
}

HTTP codes: 400 (bad params), 422 (expression error), 503 (timeout).

Query Endpoints

EndpointPurposeKey Parameters
/api/v1/queryInstant queryquery, time, timeout, limit
/api/v1/query_rangeRange queryquery, start, end, step, timeout, limit
/api/v1/format_queryFormat PromQLquery
/api/v1/seriesFind series by labelsmatch[], start, end, limit
/api/v1/labelsList label namesstart, end, match[], limit
/api/v1/label/<name>/valuesLabel valuesstart, end, match[], limit
/api/v1/query_exemplarsQuery exemplarsquery, start, end

Metadata & Status Endpoints

EndpointPurpose
/api/v1/targetsTarget discovery status (state=active|dropped|any)
/api/v1/targets/metadataMetric metadata from targets
/api/v1/metadataAll metric metadata
/api/v1/rulesAlerting/recording rules
/api/v1/alertsActive alerts
/api/v1/alertmanagersAlertmanager discovery
/api/v1/status/configCurrent config YAML
/api/v1/status/flagsCLI flags
/api/v1/status/runtimeinfoRuntime info
/api/v1/status/buildinfoBuild info
/api/v1/status/tsdbTSDB cardinality stats
/api/v1/status/walreplayWAL replay progress

Admin Endpoints (require --web.enable-admin-api)

EndpointMethodPurpose
/api/v1/admin/tsdb/snapshotPOSTCreate TSDB snapshot
/api/v1/admin/tsdb/delete_seriesPOSTDelete series (match[], start, end)
/api/v1/admin/tsdb/clean_tombstonesPOSTClean deleted data

Common PromQL Patterns

# Rate of counter over 5m
rate(http_requests_total[5m])

# Sum by label
sum by (job) (rate(http_requests_total[5m]))

# Percentile from histogram
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

# Filter by label
up{job="prometheus", instance=~".*:9090"}

# Increase over time
increase(http_requests_total[1h])

# Average over time range
avg_over_time(process_cpu_seconds_total[5m])

Result Types

  • vector: [{"metric": {...}, "value": [timestamp, "value"]}]
  • matrix: [{"metric": {...}, "values": [[ts, "val"], ...]}]
  • scalar: [timestamp, "value"]
  • string: [timestamp, "string"]

Scripts

Query script: scripts/prom_query.py

# Instant query
python scripts/prom_query.py http://localhost:9090 'up'

# Range query
python scripts/prom_query.py http://localhost:9090 'rate(http_requests_total[5m])' \
  --start '2024-01-01T00:00:00Z' --end '2024-01-01T01:00:00Z' --step '1m'

# Output: table, json, csv
python scripts/prom_query.py http://localhost:9090 'up' --format table

Health check: scripts/prom_health.py

python scripts/prom_health.py http://localhost:9090

Detailed Reference

For complete API documentation: references/api_reference.md

For PromQL functions: references/promql_functions.md

Comments

Markdown supported