Prometheus 運用マニュアル

Prometheus は、時系列データベース + モニタリング・アラートエンジンです。主要な概念: target (収集対象), metric (指標), label (次元), rule (記録ルール + アラートルール), TSDB (時系列ストレージ)。

Target

# API で target のステータスをクエリ
curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {labels, health, lastError}'
# health: "up" = 正常, "down" = 収集失敗
# lastError: 最後の失敗原因 (タイムアウト/接続拒否/フォーマットエラー)

# up 指標が 0 の instance を検索 (到達不能)
curl -s 'http://localhost:9090/api/v1/query?query=up==0' | jq '.data.result[] | .metric.instance'

# Web UI: http://localhost:9090/targets
# → 各 target の labels, 最終収集時刻, 収集所要時間, エラーを確認可能

設定とホットリロード

# 設定構文をチェック
promtool check config /etc/prometheus/prometheus.yml
promtool check rules /etc/prometheus/rules/*.yml

# ホットリロード (再起動不要、データ損失なし、rules と targets のみを再読み込み)
kill -HUP $(pidof prometheus)
# または: curl -X POST http://localhost:9090/-/reload

典型的な prometheus.yml の構造:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - /etc/prometheus/rules/*.yml

scrape_configs:
  - job_name: node
    static_configs:
      - targets: ['localhost:9100', '192.168.1.7:9100']
        labels: { env: 'prod' }

TSDB 管理

# データディレクトリ (2時間ごとに block ディレクトリが生成される)
du -sh /var/lib/prometheus/data
ls /var/lib/prometheus/data/           # 01xxxx-02xxxx 形式の block ディレクトリが表示される

# TSDB のステータス (series 数、メモリ使用量、block 数)
curl -s http://localhost:9090/api/v1/status/tsdb | jq '.data'
# headStats.numSeries: 現在アクティブな series 数 (> 1M なら注意が必要)
# headStats.chunkCount: メモリ内の chunk 数

# 古いデータの削除 (--web.enable-admin-api 起動パラメータが必要、デフォルトは無効)
curl -X POST -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]={job="old-job"}'
# マーク削除後、clean_tombstones を実行する必要がある
curl -X POST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones

# スナップショット (完全なデータバックアップ)
curl -X POST http://localhost:9090/api/v1/admin/tsdb/snapshot
# → /var/lib/prometheus/data/snapshots/<timestamp>/
# スナップショットは別の Prometheus にコピーしてそのまま使用可能

クエリデバッグ

# インスタントクエリ
curl -s 'http://localhost:9090/api/v1/query?query=rate(node_cpu_seconds_total[5m])' | jq

# レンジクエリ (step = サンプリング間隔)
curl -s 'http://localhost:9090/api/v1/query_range?query=up&start=...&end=...&step=60s' | jq

# すべての label values を一覧表示
curl -s http://localhost:9090/api/v1/label/__name__/values | jq '.data[:20]'
curl -s http://localhost:9090/api/v1/label/job/values | jq

トラブルシューティング

# Target がダウンしている場合
curl http://<target>:<port>/metrics              # exporter がデータを公開しているか確認
# → タイムアウト → ファイアウォール/systemd/ポートバインドの問題
# → 200 だが空 → exporter は実行中だがデータがない

# メモリ使用量が多い場合
# → 高基数の label (例: request_id, user_id) により、一意の値ごとに新しい series が作成される
# → 確認: curl http://localhost:9090/api/v1/status/tsdb | jq '.data.headStats.numSeries'
# → 100 万を超えた場合 → label の次元を減らすか、recording rules で事前集約することを検討

# クエリが遅い/タイムアウトする場合
# → クエリの範囲と step を確認: 範囲が広く step が小さいほど → データポイント数が増える
# → 頻繁に使用するクエリは recording rules で事前に計算すること