Buttercup のデバッグ

使用時期

• crs namespace の Pod が CrashLoopBackOff、OOMKilled、または再起動中
• 複数のサービスが同時に再起動する (カスケード障害)
• Redis が応答しないか AOF 警告が表示される
• キューが増加しているが、タスクが進行していない
• ノードが DiskPressure、MemoryPressure、または PID プレッシャーを示している
• Build-bot が Docker デーモン (DinD) に到達できない
• Scheduler がスタックしてタスク状態が進まない
• ヘルスチェックプローブが予期せず失敗する
• デプロイされた Helm 値が実際の Pod 設定と一致しない

使用しない場合

• Buttercup のデプロイまたはアップグレード (Helm とデプロイメント ガイドを使用)
• crs Kubernetes namespace 外の問題のデバッグ
• 障害症状を伴わないパフォーマンス チューニング

Namespace とサービス

すべての Pod は crs namespace で実行されます。主要サービス:

レイヤー	サービス
インフラ	redis, dind, litellm, registry-cache
オーケストレーション	scheduler, task-server, task-downloader, scratch-cleaner
Fuzzing	build-bot, fuzzer-bot, coverage-bot, tracer-bot, merger-bot
分析	patcher, seed-gen, program-model, pov-reproducer
インターフェース	competition-api, ui

トリアージワークフロー

常にトリアージから始めます。最初にこれら3つのコマンドを実行してください:

# 1. Pod ステータス - 再起動、CrashLoopBackOff、OOMKilled を確認
kubectl get pods -n crs -o wide

# 2. イベント - 何が起こったかのタイムライン
kubectl get events -n crs --sort-by='.lastTimestamp'

# 3. 警告のみ - ノイズをフィルタリング
kubectl get events -n crs --field-selector type=Warning --sort-by='.lastTimestamp'

その後、絞り込みます:

# 特定の Pod がなぜ再起動したのか? Last State Reason を確認 (OOMKilled, Error, Completed)
kubectl describe pod -n crs <pod-name> | grep -A8 'Last State:'

# 実際のリソース制限と意図された制限を確認
kubectl get pod -n crs <pod-name> -o jsonpath='{.spec.containers[0].resources}'

# クラッシュしたコンテナのログ (--previous = 停止したコンテナ)
kubectl logs -n crs <pod-name> --previous --tail=200

# 現在のログ
kubectl logs -n crs <pod-name> --tail=200

過去の問題と進行中の問題

再起動回数が多いからといって、問題が進行中であるとは限りません。再起動は Pod の存続期間全体にわたって蓄積されます。常に区別してください:

• --tail はログバッファの末尾を表示します。古いメッセージが含まれる可能性があります。--since=300s を使用して、問題が今アクティブに発生していることを確認します。
• ログ出力に --timestamps を使用すると、サービス全体でイベントを相互に関連付けるのに役立ちます。
• describe pod で Last State タイムスタンプをチェックして、最後の実際のクラッシュがいつ発生したかを確認します。

カスケード検出

多くの Pod が同じ時間帯に再起動する場合、個々の Pod を調査する前に、共有依存関係エラーをチェックしてください。最も一般的なカスケード: Redis がダウン -> すべてのサービスが ConnectionError/ConnectionRefusedError を取得 -> 大量再起動。複数の --previous ログで同じエラーを探してください。すべてが redis.exceptions.ConnectionError と言っている場合は、個別のサービスではなく、Redis をデバッグしてください。

ログ分析

# サービスのすべてのレプリカを同時に表示
kubectl logs -n crs -l app=fuzzer-bot --tail=100 --prefix

# ライブストリーミング
kubectl logs -n crs -l app.kubernetes.io/name=redis -f

# すべてのログをディスクに収集 (既存スクリプト)
bash deployment/collect-logs.sh

リソース圧力

# Pod ごとの CPU/メモリ
kubectl top pods -n crs

# ノードレベル
kubectl top nodes

# ノード条件 (ディスク圧力、メモリ圧力、PID プレッシャー)
kubectl describe node <node> | grep -A5 Conditions

# Pod 内のディスク使用量
kubectl exec -n crs <pod> -- df -h

# ディスク使用量を消費しているもの
kubectl exec -n crs <pod> -- sh -c 'du -sh /corpus/* 2>/dev/null'
kubectl exec -n crs <pod> -- sh -c 'du -sh /scratch/* 2>/dev/null'

Redis デバッグ

Redis はバックボーンです。Redis がダウンすると、すべてがカスケード障害になります。

# Redis Pod ステータス
kubectl get pods -n crs -l app.kubernetes.io/name=redis

# Redis ログ (AOF 警告、OOM、接続問題)
kubectl logs -n crs -l app.kubernetes.io/name=redis --tail=200

# Redis CLI に接続
kubectl exec -n crs <redis-pod> -- redis-cli

# redis-cli 内: キー診断
INFO memory          # used_memory_human, maxmemory
INFO persistence     # aof_enabled, aof_last_bgrewrite_status, aof_delayed_fsync
INFO clients         # connected_clients, blocked_clients
INFO stats           # total_connections_received, rejected_connections
CLIENT LIST          # 接続している人を確認
DBSIZE               # 総キー数

# AOF 設定
CONFIG GET appendonly     # AOF は有効ですか?
CONFIG GET appendfsync   # fsync ポリシー: everysec, always, または no

# /data はどこにマウントされているか? (ディスク vs tmpfs は AOF パフォーマンスに影響)

kubectl exec -n crs <redis-pod> -- mount | grep /data
kubectl exec -n crs <redis-pod> -- du -sh /data/

キュー検査

Buttercup は Redis ストリームをコンシューマグループで使用します。キュー名:

キュー	ストリームキー
Build	fuzzer_build_queue
Build Output	fuzzer_build_output_queue
Crash	fuzzer_crash_queue
Confirmed Vulns	confirmed_vulnerabilities_queue
Download Tasks	orchestrator_download_tasks_queue
Ready Tasks	tasks_ready_queue
Patches	patches_queue
Index	index_queue
Index Output	index_output_queue
Traced Vulns	traced_vulnerabilities_queue
POV Requests	pov_reproducer_requests_queue
POV Responses	pov_reproducer_responses_queue
Delete Task	orchestrator_delete_task_queue

# ストリーム長を確認 (保留中のメッセージ)
kubectl exec -n crs <redis-pod> -- redis-cli XLEN fuzzer_build_queue

# コンシューマグループのラグを確認
kubectl exec -n crs <redis-pod> -- redis-cli XINFO GROUPS fuzzer_build_queue

# コンシューマごとの保留中のメッセージを確認
kubectl exec -n crs <redis-pod> -- redis-cli XPENDING fuzzer_build_queue build_bot_consumers - + 10

# タスクレジストリサイズ
kubectl exec -n crs <redis-pod> -- redis-cli HLEN tasks_registry

# タスク状態のカウント
kubectl exec -n crs <redis-pod> -- redis-cli SCARD cancelled_tasks
kubectl exec -n crs <redis-pod> -- redis-cli SCARD succeeded_tasks
kubectl exec -n crs <redis-pod> -- redis-cli SCARD errored_tasks

コンシューマグループ: build_bot_consumers, orchestrator_group, patcher_group, index_group, tracer_bot_group。

ヘルスチェック

Pod は /tmp/health_check_alive にタイムスタンプを書き込みます。liveness プローブはファイルの新しさをチェックします。

# ヘルスチェックファイルの新しさを確認
kubectl exec -n crs <pod> -- stat /tmp/health_check_alive
kubectl exec -n crs <pod> -- cat /tmp/health_check_alive

Pod が再起動ループしている場合、メインプロセスがブロックされている (例: Redis を待機中、I/O でスタック) ため、ヘルスチェックファイルが古くなっている可能性があります。

テレメトリ (OpenTelemetry / Signoz)

すべてのサービスは OpenTelemetry を介してトレースとメトリクスをエクスポートします。Signoz がデプロイされている (global.signoz.deployed: true)場合は、その UI を使用してサービス全体の分散トレーシングを行います。

# OTEL が設定されているか確認
kubectl exec -n crs <pod> -- env | grep OTEL

# Signoz Pod が実行中かどうかを確認 (デプロイされている場合)
kubectl get pods -n platform -l app.kubernetes.io/name=signoz

トレースは、タスク処理が遅い場合の診断、パイプラインのどのサービスがボトルネックであるかの識別、および scheduler -> build-bot -> fuzzer-bot チェーン全体でのイベントの相互関連付けに特に有用です。

ボリュームとストレージ

# PVC ステータス
kubectl get pvc -n crs

# corpus tmpfs がマウントされているか、そのサイズ、バッキングタイプを確認
kubectl exec -n crs <pod> -- mount | grep corpus_tmpfs
kubectl exec -n crs <pod> -- df -h /corpus_tmpfs 2>/dev/null

# CORPUS_TMPFS_PATH が設定されているか確認
kubectl exec -n crs <pod> -- env | grep CORPUS

# 完全なディスクレイアウト - 実ディスク vs tmpfs に何があるか
kubectl exec -n crs <pod> -- df -h

CORPUS_TMPFS_PATH は global.volumes.corpusTmpfs.enabled: true の場合に設定されます。これは fuzzer-bot、coverage-bot、seed-gen、および merger-bot に影響します。

デプロイメント設定の検証

動作が期待と一致しない場合、Helm 値が実際に有効になったことを確認します:

# Pod の実際のリソース制限を確認
kubectl get pod -n crs <pod-name> -o jsonpath='{.spec.containers[0].resources}'

# Pod の実際のボリューム定義を確認
kubectl get pod -n crs <pod-name> -o jsonpath='{.spec.volumes}'

Helm 値テンプレートのタイプミス (例: キー名が間違っている) は、静かにチャートのデフォルトにフォールバックします。デプロイされたリソースが値テンプレートと一致しない場合は、キー名の不一致をチェックしてください。

サービス固有のデバッグ

詳細なサービスごとの症状、根本原因、および修正については、references/failure-patterns.md を参照してください。

クイックリファレンス:

• DinD: kubectl logs -n crs -l app=dind --tail=100 -- docker デーモンクラッシュ、ストレージドライバーエラーを探す
• Build-bot: ビルドキューの深さ、DinD 接続性、コンパイル中の OOM をチェック
• Fuzzer-bot: コーパスディスク使用量、CPU スロットリング、クラッシュキューのバックログ
• Patcher: LiteLLM 接続性、LLM タイムアウト、パッチキューの深さ
• Scheduler: 中央脳 -- kubectl logs -n crs -l app=scheduler --tail=-1 --prefix | grep "WAIT_PATCH_PASS\|ERROR\|SUBMIT"

診断スクリプト

自動トリアージスナップショットを実行します:

bash {baseDir}/scripts/diagnose.sh

すべての Pod から最近のログもダンプするには --full を渡します:

bash {baseDir}/scripts/diagnose.sh --full

これにより、Pod ステータス、イベント、リソース使用量、Redis ヘルス、およびキュー深さが 1 回で収集されます。