Part 5-3. Prometheusのトラブルシューティング集

導入部

Part 5-1・5-2 で性能チューニングと HA 構成を学びました。このセクションでは、本番環境で実際に遭遇する典型的な問題への対処方法を体系化します。

Prometheus の問題は多くの場合、メモリ不足、ディスク満杯、クエリ遅延、ターゲット接続失敗といった 5～7 パターンに集約されます。このセクションでは、各問題の症状確認、原因特定の診断フロー、実践的な対処方法を習得できます。加えて、本番環境で即座に使えるデバッグコマンド集とトラブルシューティングチェックリストを提供します。

よくあるエラー一覧表

本番環境で頻出する問題を症状・原因・対処の三軸で整理しました。

症状 / エラー	原因	影響範囲	対処方法（概要）
メモリ不足（OOMKill）	ターゲット数増加、クエリの複雑化	全メトリクス取得不可	メモリ上限引き上げ、チャンク数制限、WAL 設定調整
ディスク満杯	リテンション設定過大、スクレイプ量予測不足	新規データ書き込み停止	古いデータ削除、Emergency Compact 実行、リテンション見直し
クエリタイムアウト	複雑な PromQL、インデックス劣化	ダッシュボード表示遅延、アラート遅延	PromQL 最適化、インデックス再構築、クエリタイムアウト閾値調整
ターゲット接続失敗	ポート閉塞、ファイアウォール、認証エラー	該当ターゲットのみ監視不可	ポート確認、curl で疎通確認、firewall ルール確認
WAL（Write-Ahead Log）エラー	ディスク I/O エラー、ファイルシステム破損	スクレイプデータの永続化失敗	ディスク健全性チェック、WAL リセット、再起動
リテンション削除失敗	ディスク容量枯渇、削除処理の遅延	ディスク圧迫継続、新規データ取得停止	手動削除実行、容量追加、リテンション設定見直し

症状別診断フロー

Prometheus が正常に動作していないとき、まずログと基本的なメトリクスから原因を切り分けます。

メモリ不足トラブルの対処

症状の確認

Prometheus がメモリ不足に陥ると、ログに以下のような出力が見られます。

bash

# ジャーナルログ確認
journalctl -u prometheus -n 50

# 出力例
May 03 10:15:22 prod-server kernel: [12345.123] Memory cgroup out of memory: Killed process 5678 (prometheus) total-vm:2048MB, anon-rss:1980MB, file-rss:48MB

Linux では OOMKill（Out-Of-Memory Killer）が発動し、Prometheus が強制終了されます。

メモリ使用量の確認

bash

# リアルタイムメモリ監視
ps aux | grep prometheus

# 詳細メモリ情報（/proc/{pid}/status）
cat /proc/$(pidof prometheus)/status | grep Vm

# Prometheus メトリクスから確認
curl -s  | jq .

対処方法

一時的な対策：メモリ上限の引き上げ

bash

# systemd サービスの場合
# /etc/systemd/system/prometheus.service を編集
[Service]
MemoryMax=4G
MemoryHigh=3.5G

systemctl daemon-reload
systemctl restart prometheus

恒久的な対策（以下のチェックリストから実施）：

[ ] ターゲット数の最適化：不要なターゲットを削除、スクレイプ間隔延長（15s → 30s）
[ ] 高カーディナリティラベルの削除：リリース番号、アクセストークンなどユニーク値が多いラベルを除外
[ ] チャンク数制限の設定：--storage.tsdb.max-chunks-to-persist=500000 でメモリ上限を制御
[ ] WAL（Write-Ahead Log）の最適化：--storage.wal-compression=true でメモリ圧迫軽減
[ ] サーバースペック増強：最終手段として RAM 容量を 2～4GB 増加

ディスク満杯トラブルの対処

ディスク使用状況の確認

bash

# ディスク容量確認
df -h /var/lib/prometheus/

# 出力例
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       100G   98G   2G  98% /var/lib/prometheus

# Prometheus データディレクトリの詳細
du -sh /var/lib/prometheus/data
du -sh /var/lib/prometheus/wal

Prometheus は data/ ディレクトリに TSDB（時系列データベース）を、wal/ に Write-Ahead Log を保存します。

Emergency Compact（緊急圧縮）実行

ディスク満杯が迫っている場合、古いデータを強制的に圧縮できます。

bash

# Prometheus サービス停止
systemctl stop prometheus

# Emergency Compact 実行（promtool コマンド）
promtool tsdb compact /var/lib/prometheus/data

# サービス再起動
systemctl start prometheus

所要時間は TSDB サイズに応じて数分～数十分です。

古いデータの安全な削除

リテンションを早めるか、古いデータを手動削除します。

bash

# 現在のリテンション確認
ps aux | grep prometheus | grep retention.time

# 新しいリテンション値で再起動（30日 → 15日）
systemctl stop prometheus
prometheus --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.retention.time=15d \
  --storage.tsdb.retention.size=50GB &

# ディスク空き容量再確認（5～10分待機）
df -h /var/lib/prometheus/

クエリ遅延・タイムアウトの対処

原因の特定

bash

# Prometheus ログから遅いクエリを確認
journalctl -u prometheus -n 100 | grep -i "slow\|timeout"

# クエリ時間メトリクス確認
curl -s ' | jq .

PromQL の最適化例

複雑なクエリは分割・簡潔化します。

promql

# 遅いクエリ：複数ジョインで高コスト
sum(rate(http_requests_total[5m])) by (instance) 
  / on(instance) group_left 
sum(rate(http_errors_total[5m])) by (instance)

# 最適化：あらかじめ error_rate を計算しておく
sum(error_rate[5m]) by (instance)

インデックス再構築

メモリ内インデックスが劣化すると、クエリ性能が低下します。

bash

# インデックス再構築（再起動）
systemctl restart prometheus

# 再起動後、クエリ性能が改善したか確認
time curl -s ' > /dev/null

ターゲット接続エラーの対処

接続失敗の診断手順

bash

# 1. ターゲット一覧確認
curl -s  | jq '.data.activeTargets[] | {job: .labels.job_name, instance: .labels.instance, health: .health}'

# 2. curl で直接接続テスト
curl -v http://target-instance:9100/metrics

# 3. ポート開放確認
netstat -tlnp | grep 9100

# 4. ファイアウォール確認
sudo iptables -L -n | grep 9100

Prometheus.yml での接続設定例

yaml

scrape_configs:
  - job_name: 'node-exporter'
    static_configs:
      - targets: ['10.0.1.10:9100']
    scrape_interval: 15s
    scrape_timeout: 10s
    scheme: http
    # 再試行設定（3回失敗後にダウンと判定）
    # デフォルトで最大 3 回リトライ

ターゲットが DOWN と表示される場合、上記ログから具体的なエラーメッセージを確認し、ネットワーク・認証いずれの問題かを特定します。

デバッグコマンド集

本番環境で即座に使える診断コマンドをまとめました。

bash

# バージョン・コンパイル情報確認
prometheus --version

# 設定ファイル検証（構文エラー確認）
promtool check config /etc/prometheus/prometheus.yml

# ルール ファイル検証
promtool check rules /etc/prometheus/rules/alerts.yml

# ターゲット一覧＆ヘルスチェック
curl -s  | jq .

# Prometheus 自身のメトリクス確認
curl -s  | grep -E "^prometheus_tsdb|^process_"

# 最新 500 個のログ取得
journalctl -u prometheus -n 500 --no-pager

トラブルシューティングチェックリスト

本番環境で問題が発生したとき、以下の順序で確認します。

[ ] 1. Prometheus ログを最新 100 行確認した
       journalctl -u prometheus -n 100 | tail -20

[ ] 2. ディスク容量を確認した（90% 以上か確認）
       df -h /var/lib/prometheus/

[ ] 3. メモリ使用量を確認した（80% 以上か確認）
       free -h
       ps aux | grep prometheus

[ ] 4. Prometheus.yml 構文を検証した
       promtool check config prometheus.yml

[ ] 5. ターゲット接続状態を確認した
       curl -s 

[ ] 6. 特定ターゲットに curl で接続確認した
       curl -v http://target:port/metrics

[ ] 7. Prometheus を再起動して改善したか確認した
       systemctl restart prometheus

[ ] 8. 改善しない場合、別環境でメモリ 増設テストを実施した

リカバリ手順フロー図

次のステップへ

このセクションで、本番環境で遭遇する典型的なトラブルの診断・対処方法を習得しました。Part 6「統合・ベストプラクティス編」では、Prometheus を他の監視ツール（Grafana、Alertmanager）と統合し、エンタープライズレベルの監視基盤を構築するガイドをお送りします。

前のセクション: Part 5-2. Prometheusのハイアベイラビリティ・リテンション戦略

次のセクション: Part 6. 統合・ベストプラクティス編（来週公開予定）

Part 5-3. Prometheusのトラブルシューティング集 ​

導入部 ​

よくあるエラー一覧表 ​

症状別診断フロー ​

メモリ不足トラブルの対処 ​

症状の確認 ​

メモリ使用量の確認 ​

対処方法 ​

ディスク満杯トラブルの対処 ​

ディスク使用状況の確認 ​

Emergency Compact（緊急圧縮）実行 ​

古いデータの安全な削除 ​

クエリ遅延・タイムアウトの対処 ​

原因の特定 ​

PromQL の最適化例 ​

インデックス再構築 ​

ターゲット接続エラーの対処 ​

接続失敗の診断手順 ​

Prometheus.yml での接続設定例 ​

デバッグコマンド集 ​

トラブルシューティングチェックリスト ​

リカバリ手順フロー図 ​

次のステップへ ​

Part 5-3. Prometheusのトラブルシューティング集

導入部

よくあるエラー一覧表

症状別診断フロー

メモリ不足トラブルの対処

症状の確認

メモリ使用量の確認

対処方法

ディスク満杯トラブルの対処

ディスク使用状況の確認

Emergency Compact（緊急圧縮）実行

古いデータの安全な削除

クエリ遅延・タイムアウトの対処

原因の特定

PromQL の最適化例

インデックス再構築

ターゲット接続エラーの対処

接続失敗の診断手順

Prometheus.yml での接続設定例

デバッグコマンド集

トラブルシューティングチェックリスト

リカバリ手順フロー図

次のステップへ