AI は誤ることがあります。原文をご確認ください 専用ページで開く
ドキュメントに質問
目次

Prometheus 操作マニュアル

7 分で読了
このページの目次

discovery・scrape・storage・query・rule を分ける。up=1 は scrape 成功でアプリ正常を意味しない。series 不在・scrape 失敗・アプリ失敗を区別する。

やりたいこと参照先
target down・metric 消失discovery と scrape
query 低速・graph 不自然window・step・cardinality
設定・rule 変更検査と再読込
storage と backupTSDB の範囲

target の存在を先に確認

readiness と discovery を分けて確認する

# instance が query を処理できるか確認する
curl -fsS http://127.0.0.1:9090/-/ready

各 request の URL を実入口へ揃えて変更し、必要な認証・TLS を指定する。

# scrape URL・実 label・最新エラーを読む
curl -fsS http://127.0.0.1:9090/api/v1/targets |
  jq '.data.activeTargets[] | {labels,scrapeUrl,health,lastError,lastScrape}'

lastError で timeout・証明書・接続拒否・形式を分け、lastScrape の新しさも見る。

# active にない場合に dropped の発見 label を調べる
curl -fsS 'http://127.0.0.1:9090/api/v1/targets?state=dropped' |
  jq '.data.droppedTargets[] | .discoveredLabels'

保持件数で省かれる場合があり、見つからなくても discovery・設定を確認する。

# 現時点の scrape 成功指標を query する
curl -fsS --get http://127.0.0.1:9090/api/v1/query \
  --data-urlencode 'query=up' | jq .

最初に status、次に data.result を読む。実 job/instance で絞り、空配列を 0 と解釈しない。

結果意味確認
up = 0target は存在、scrape 失敗lastError, timeout, DNS, TLS, auth, format
up = 1scrape 成功でもアプリ障害はあり得る業務 metric と利用経路の probe
up が空discovery・relabel・時間/label 不一致discovered/dropped target と selector

Prometheus 側 network から scrapeUrl と metrics を確認する。exporter 待受けだけでは DNS・認証・CA は不明。relabel 後の実 label で query し ready を全 target の健康としない。

step は評価間隔で scrape 間隔ではない

単一時点・区間の評価を選ぶ

# 各 counter の 5 分 rate を現時点で評価する
curl -fsS --get http://127.0.0.1:9090/api/v1/query \
  --data-urlencode 'query=rate(http_requests_total[5m])' | jq .

実在する counter を使う。値は毎秒の増分で、期間内の総件数ではない。

# 明示した UTC 区間で 30 秒ごとに再評価する
curl -fsS --get http://127.0.0.1:9090/api/v1/query_range \
  --data-urlencode 'query=rate(http_requests_total[5m])' \
  --data-urlencode 'start=2026-09-10T00:00:00Z' \
  --data-urlencode 'end=2026-09-10T01:00:00Z' \
  --data-urlencode 'step=30s' | jq .

前の query と別方式。問題区間へ絞り、resultType・時刻・values・warnings/infos を読む。

data のある期間を選ぶ。URL encode で式を保護する。各 step に再評価し rate の5m は sample window。step を細かくしても元 sample は増えない。counter ごとの reset を扱うため rate 後に sum し、短すぎる window に注意。

図を準備しています
一つの label が series 数を倍増させる

全独立組合せが存在する場合 series 数は label 値数の積。user ID 次元で route×method×status が桁違いに増える。

図は全組合せが存在する場合の数で実在数とは限らない。user/request ID や raw URL は無制限 churn を生む。有限 label と route template を使う。recording rule は新 series を書き、元の基数を減らさない。

file と稼働状態の両方を検証

配備前：使用中の file を特定して検証する

# 設定引数と service の実行主体を確認する
systemctl cat prometheus.service

実 config・rule path に合わせ、旧 file を保存し、対応版の promtool を使う。

# 設定と参照 rule を検証する
promtool check config /etc/prometheus/prometheus.yml

成功後に配備する。実 scrape・認証の検証は別途必要。

# rule の個別変更時に対象 file を検証する
promtool check rules /etc/prometheus/rules/*.yml

個別 rule 向けの確認で、同じ検証を機械的に繰返す必要はない。glob が実 file に一致すること。

# 作成済みの rule 動作 test を実行する
promtool test rules /etc/prometheus/tests/alerts.test.yml

通常の rule でなく test 定義。入力系列と期待結果を用意し、閾値・for・回復・欠損を扱う。

配備後：signal・結果・時刻を確認する

# 確認した main process に reload を要求する
sudo systemctl kill --signal=HUP --kill-whom=main prometheus.service

signal 送信成功と読込成功は別。操作時刻を記録して次を確認する。

# 今回の設定読込 log を確認する
journalctl -u prometheus.service --since "5 minutes ago" --no-pager

# 稼働中の設定が意図した内容か確認する
curl -fsS http://127.0.0.1:9090/api/v1/status/config | jq -r '.data.yaml'

# reload 成功値と最終成功時刻を同時に確認する
curl -fsS --get http://127.0.0.1:9090/api/v1/query \
  --data-urlencode 'query={__name__=~"prometheus_config_last_reload_successful|prometheus_config_last_reload_success_timestamp_seconds"}' | jq .

self-scrape と新しい取得が必要。1 と今回の時刻を確認する。失敗時は旧 file を戻し検証・reload 後、targets・rule も確認する。

実 path と主 process に合わせる。POST reload は lifecycle 有効時のみ。success と時刻を確認し、構文検査を全 runtime 検査としない。promtool test rules で閾値・for・回復を試す。

cardinality・保持・disk を先に調べる

容量の原因を特定する

# 実 data path・保持引数を読む
curl -fsS http://127.0.0.1:9090/api/v1/status/flags | jq '.data'

以下は storage.tsdb.path に合わせ、コンテナなら実 volume も確認する。

# head・label cardinality を読む
curl -fsS http://127.0.0.1:9090/api/v1/status/tsdb | jq '.data'

同 instance の履歴・負荷と比較し、単一閾値で判断しない。

# data filesystem の空きを確認する
df -hT /var/lib/prometheus

# WAL・compaction・破損・書込失敗を探す
journalctl -u prometheus.service --since "1 hour ago" --no-pager

有効化済み snapshot API で backup する

承認されアクセス制限された admin API と空き容量が前提。以下は削除ではなく snapshot 作成。

# 現 head を含む snapshot を作る
curl -fsS -X POST 'http://127.0.0.1:9090/api/v1/admin/tsdb/snapshot?skip_head=false' | jq .

data.name を記録し、data 下 snapshots/名前 を別保存先へ複写・検証する。同じ disk だけでは独立 backup にならず、後の書込は含まない。

互換版と独立 directory で復元し、実通知を無効にする。履歴 query・期間・系列を検証し、同じ保守時点の設定記録を保持する。

storage.tsdb.path と head series・churn・query cost・retention を確認する。百万 series を万能閾値にしない。size retention は全 directory の厳密上限でなく WAL/head 余裕も必要。まず増加源を直す。

snapshot・削除は admin API が前提。head を含める方針と別保存の設定・rule・認証を確認し隔離復元する。delete_series・tombstone・clean は別段階で全消去を修復策としない。通知は実 Alertmanager/Grafana 経路を調べる。

HTTP API · Querying basics · Metric practices · Storage · Rule testing

リンクプレビュー

新しいタブで開く