prometheus

Prometheus API スキル

/api/v1 の HTTP API を使って、Prometheus の監視システムにクエリを実行します。

クイックリファレンス

即時クエリ

curl 'http://<prometheus>:9090/api/v1/query?query=<promql>&time=<timestamp>'

範囲クエリ

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

レスポンス形式

すべてのレスポンスは JSON を返します。

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

HTTP コード：400（パラメーター不正）、422（式エラー）、503（タイムアウト）。

クエリエンドポイント

エンドポイント	用途	主なパラメーター
/api/v1/query	即時クエリ	query、time、timeout、limit
/api/v1/query_range	範囲クエリ	query、start、end、step、timeout、limit
/api/v1/format_query	PromQL の整形	query
/api/v1/series	ラベルによる時系列の検索	match[]、start、end、limit
/api/v1/labels	ラベル名の一覧表示	start、end、match[]、limit
/api/v1/label/<name>/values	ラベル値	start、end、match[]、limit
/api/v1/query_exemplars	エグザンプラーのクエリ	query、start、end

メタデータとステータスのエンドポイント

エンドポイント	用途
/api/v1/targets	ターゲット検出のステータス（state=active|dropped|any）
/api/v1/targets/metadata	ターゲットからのメトリクスメタデータ
/api/v1/metadata	すべてのメトリクスメタデータ
/api/v1/rules	アラートルール／記録ルール
/api/v1/alerts	アクティブなアラート
/api/v1/alertmanagers	Alertmanager の検出
/api/v1/status/config	現在の設定 YAML
/api/v1/status/flags	CLI フラグ
/api/v1/status/runtimeinfo	ランタイム情報
/api/v1/status/buildinfo	ビルド情報
/api/v1/status/tsdb	TSDB のカーディナリティ統計
/api/v1/status/walreplay	WAL 再生の進行状況

管理者用エンドポイント（--web.enable-admin-api が必要）

エンドポイント	メソッド	用途
/api/v1/admin/tsdb/snapshot	POST	TSDB スナップショットの作成
/api/v1/admin/tsdb/delete_series	POST	時系列の削除（match[]、start、end）
/api/v1/admin/tsdb/clean_tombstones	POST	削除済みデータのクリーンアップ

よく使う PromQL パターン

# 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])

結果の型

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

スクリプト

クエリスクリプト：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

ヘルスチェック：scripts/prom_health.py

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

詳細リファレンス

API の完全なドキュメント：references/api_reference.md

PromQL 関数：references/promql_functions.md

---

注意点

• 頻繁にリセットされるカウンターに対する rate()：計算は正しくても意味をなさない場合があります — カウンター値がスクレイプ間で維持されない場合は、increase() を使い、明示的に間隔で割ってください。
• up{} はターゲットごとのゲージです：不安定なターゲットは up=0 になりますが、for の条件を満たすまではアラートは発生しません。稼働確認には短い for を、ノイズを抑えるには長い for を設定してください。
• 記録ルールは固定間隔で評価されます。評価が抜けても遡って補完されないため、インシデント中は記録時系列にギャップが生じます。
• フェデレーションの match[] パラメーターでは、すべてのマッチャーが一致する必要があります — 空のマッチャーは時系列を返さないため、データのない正常なクエリのように見えます。
• 古いマーカーのセマンティクス：時系列のスクレイプが停止すると、デフォルトで 5 分後に古いマーカーが付きます。その後、クエリ結果は「0」ではなく「データなし」になります。absent() に対するアラートに影響します。
• サービスディスカバリーと relabel_config：keep アクションの正規表現に誤りがあると、すべてのターゲットが通知なく除外されます。設定を変更するたびに /api/v1/targets で確認してください。