debug-ops

デバッグ操作

言語固有のツールと一般的なシナリオ別プレイブックを活用した、体系的なデバッグ手法です。

バグ分類の判断ツリー

Bug Report / Symptom
│
├─ Crash
│  ├─ Segfault / Access Violation
│  │  └─ Check: null pointer, buffer overflow, use-after-free, stack overflow
│  ├─ Panic / Fatal Error
│  │  └─ Check: assertion failure, unrecoverable state, out-of-memory
│  └─ Unhandled Exception
│     └─ Check: missing error handler, unexpected input type, network failure
│
├─ Hang
│  ├─ Deadlock
│  │  └─ Check: lock ordering, mutex contention, channel blocking
│  ├─ Infinite Loop
│  │  └─ Check: loop termination condition, counter overflow, recursive call
│  └─ Blocked I/O
│     └─ Check: network timeout, DNS resolution, disk full, file lock
│
├─ Wrong Output
│  ├─ Logic Error
│  │  └─ Check: operator precedence, boundary conditions, boolean logic
│  ├─ Data Corruption
│  │  └─ Check: concurrent mutation, encoding mismatch, truncation
│  └─ Off-by-One
│     └─ Check: loop bounds, array indexing, fence-post errors
│
├─ Performance
│  ├─ Slow Queries
│  │  └─ Check: missing index, N+1 queries, full table scan, lock wait
│  ├─ Memory Bloat
│  │  └─ Check: cache without eviction, leaked references, large allocations
│  └─ CPU Spikes
│     └─ Check: hot loops, regex backtracking, excessive GC, busy-wait
│
└─ Intermittent
   ├─ Race Condition
   │  └─ Check: shared mutable state, read-modify-write, check-then-act
   ├─ Timing-Dependent
   │  └─ Check: timeout values, clock skew, event ordering assumptions
   └─ Environment-Specific
      └─ Check: OS differences, locale, timezone, file system case sensitivity

体系的なデバッグワークフロー

症状の特定から予防までの6ステップのプロセスです。

ステップ 1：再現する

バグが存在することを確認し、確実に再現できる手順を作成します。再現できないバグは、自信を持って修正できません。正確な入力、環境、操作手順を記録します。

ステップ 2：切り分ける

問題の範囲を可能な限り狭めます。二分探索（git bisect、コードを半分ずつコメントアウトする方法）、スタブ、機能フラグ、環境の分離を使って、無関係なコードを除外します。

ステップ 3：原因を特定する

直近の引き金だけでなく、根本原因を見つけます。5 Whys の手法を使い、実行をトレースし、重要な箇所の状態を調べます。症状と根本的な欠陥を区別します。

ステップ 4：修正する

根本原因に対処する、最小限かつ適切な変更を適用します。手当たり次第のデバッグ（一度に複数の変更を加えること）は避けます。修正が機能することだけでなく、なぜ機能するのかを理解します。

ステップ 5：検証する

修正によって元の問題が解決し、リグレッションが発生していないことを確認します。元の再現手順を再実行します。テストスイート全体を実行します。修正に関連するエッジケースもテストします。

ステップ 6：予防する

リグレッションテストを追加します。必要に応じてドキュメントや運用手順書を更新します。同じ種類のバグが別の場所にも存在しないか検討します。調査結果をチームと共有します。

再現チェックリスト

[ ] Minimal reproduction steps documented (numbered, unambiguous)
[ ] Environment captured (OS, runtime version, dependencies, config)
[ ] Exact inputs recorded (request payload, CLI args, file contents)
[ ] Timing sensitivity assessed (does it fail only under load? after delay?)
[ ] Single-threaded reproduction attempted (eliminates concurrency noise)
[ ] Reproduction automated as script or test case
[ ] Confirmed reproduction is deterministic (fails N/N attempts)
[ ] Identified whether reproduction requires specific data/state

切り分け手法のクイックリファレンス

手法	方法	最適な用途
二分探索（git）	git bisect start BAD GOOD を実行し、続けて git bisect run ./test.sh を実行します	バグを導入したコミットの特定
二分探索（コード）	コードの半分をコメントアウトしてテストし、これを繰り返します	不慣れなコード内で問題箇所を絞り込む
スタブ／モック	依存関係を、正常な動作が確認された偽物に置き換えます	外部サービスから切り離す
機能フラグ	機能を1つずつ無効にします	問題の原因となる機能の特定
環境の分離	Docker コンテナー、新しい VM、クリーンインストールを使います	環境の汚染を排除する
ネットワークの傍受	mitmproxy、Charles Proxy、モックサーバーを使います	クライアント側とサーバー側の問題を切り分ける
入力の縮小	バグが発生しなくなるまで入力フィールドやデータを取り除きます	最小限の引き金を特定する
依存関係の固定	すべての依存関係を固定し、1つずつ更新します	問題を引き起こす依存関係の更新を特定する

根本原因分析テンプレート

5 Whys の例

Problem: API returns 500 error on user login

1. Why? → The database query throws a timeout exception
2. Why? → The users table scan takes >30 seconds
3. Why? → There is no index on the email column
4. Why? → The migration that adds the index was never run in production
5. Why? → The deployment script skips migrations when the --fast flag is used

Root cause: Deployment script's --fast flag bypasses migrations
Fix: Remove --fast flag behavior that skips migrations, add migration check to health endpoint
Prevention: CI check that verifies all migrations are applied after deployment

フォールトツリーの基本

                    [System Failure]
                    /              \
            [Hardware]          [Software]
            /       \           /        \
       [Disk]    [Memory]  [Config]   [Code Bug]
                              |          |
                         [Missing    [Race in
                          env var]    worker pool]

上部（観測された障害）から下部の葉（根本原因）に向かって分析します。各分岐は AND／OR ゲートです。AND はすべての子条件が真である必要があることを意味し、OR はいずれか1つの子条件を満たせば十分であることを意味します。

言語別デバッガーのクイックリファレンス

言語	ツール	起動コマンド	主なコマンド
Node.js	Chrome DevTools	node --inspect-brk app.js	chrome://inspect を開き、Sources でブレークポイントを設定します
Node.js	ndb	npx ndb app.js	ブラックボックス化機能を備えた拡張 DevTools
Python	pdb	python -m pdb script.py	n 次へ、s ステップ実行、c 続行、p expr を出力、bt バックトレース
Python	debugpy	python -m debugpy --listen 5678 --wait-for-client script.py	VS Code の「Attach」起動構成
Python	breakpoint()	コードに breakpoint() を挿入します	その行で pdb が起動します（Python 3.7 以降）
Go	Delve	dlv debug ./cmd/server	b main.go:42 ブレーク、c 続行、n 次へ、p var を出力
Go	Delve（テスト）	dlv test ./pkg/...	テスト関数を直接デバッグします
Go	Delve（アタッチ）	dlv attach PID	実行中のプロセスをデバッグします
Rust	rust-gdb	rust-gdb target/debug/myapp	b main、r、n、p variable、bt
Rust	rust-lldb	rust-lldb target/debug/myapp	b s main、r、n、p variable、bt
Rust	CodeLLDB	VS Code 拡張機能	GUI でのブレークポイント設定、変数の検査
ブラウザー	DevTools	F12 または Ctrl+Shift+I	Elements、Console、Network、Sources、Performance、Memory

デバッグ用の簡単なスニペット

// Node.js: drop into debugger at this point
debugger;

// Node.js: conditional breakpoint
if (user.id === 'problem-user') debugger;

# Python: drop into debugger at this point
breakpoint()

# Python: conditional breakpoint
if user_id == 'problem-user':
    breakpoint()

// Go: print goroutine stacks (send SIGQUIT or SIGABRT)
// kill -QUIT <pid>
// Or in code:
import "runtime/debug"
debug.PrintStack()

// Rust: enable full backtraces
// RUST_BACKTRACE=1 cargo run
// RUST_BACKTRACE=full cargo run

ログベースのデバッグパターン

戦略的なログ記録

エラーが発生する箇所だけでなく、判断を行う箇所にもログを配置します。

[ENTRY] function_name(args_summary)     -- entering the function
[STATE] key_variable=value              -- state at critical decision point
[BRANCH] taking path X because Y       -- which branch and why
[EXIT] function_name -> result_summary  -- leaving the function
[ERROR] operation failed: detail        -- error with context

相関 ID

サービス間で単一のリクエストを追跡します。

# Generate at entry point, propagate through all calls
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

# Search across all service logs
rg "550e8400-e29b-41d4-a716-446655440000" /var/log/services/

タイムラインの再構築

# Merge and sort logs from multiple sources by timestamp
sort -t' ' -k1,2 service-a.log service-b.log service-c.log > timeline.log

# Find gaps in activity (potential hang/block)
awk '{print $1, $2}' timeline.log | uniq -c | sort -rn | head -20

構造化ログのクエリ

# jq queries on JSON logs
# Find all errors for a specific user
jq 'select(.level == "error" and .user_id == "u123")' app.log

# Get timing distribution for slow requests
jq 'select(.duration_ms > 1000) | .duration_ms' app.log | sort -n

# Count errors by type
jq -r 'select(.level == "error") | .error_type' app.log | sort | uniq -c | sort -rn

よくある落とし穴

落とし穴	問題点	対処法
根本原因ではなく症状を修正する	バグが別の形で再発します	5 Whys を使って深掘りします
安全策なしで本番環境をデバッグする	データ損失や長時間の停止につながるおそれがあります	読み取り専用クエリ、フィーチャーフラグ、カナリアデプロイを使用します
ハイゼンバグ（観察すると消えるバグ）	ログやブレークポイントの追加でタイミングが変化します	strace、サンプリングプロファイラー、rr などの非侵襲的なツールを使用します
思い込みによる偏り（「X のはずがない」）	信頼しているものが原因である可能性を見落とします	「明らか」なものも含め、すべての仮定を明示的に検証します
再現ケースがない	修正を検証できず、リグレッションも防げません	信頼できる再現方法の確立に、あらかじめ時間をかけます
print／ログによるデバッグに頼りすぎる	反復が遅くなり、コードが汚れ、並行性のバグを見逃します	適切なデバッガー、プロファイラー、またはトレーシングツールを使用します
最近の変更を確認しない	答えは直近の数件のコミットにあることがよくあります	git log --oneline -20、git diff HEAD~5
警告メッセージを無視する	警告は後に続くエラーを予告していることがよくあります	デバッグ中は警告をエラーとして扱います
間違ったバージョン／ブランチをデバッグする	すでに修正済みのコードや別のコードに時間を浪費します	git branch、git log -1、ランタイムバージョンを確認します
スタックトレースを最後まで読まない	根本原因は先頭ではなく途中にあることがよくあります	下から上へ読み、まずトレース内の自分のコードを探します
複数の変更を同時に行う	どの変更が修正（または悪化）につながったのか判断できません	テストサイクルごとに変更は 1 つにします
変更前の状態を記録しない	動作していた基準状態と比較できません	デバッグ前に設定、依存関係、データのスナップショットを取得します

参考ファイル

ファイル	内容	行数
references/systematic-methods.md	科学的手法、二分探索、デルタデバッグ、差分デバッグ、タイムトラベルデバッグ、チームでのデバッグ	約 600
references/tool-specific.md	ブラウザー DevTools、Node.js、Python、Go、Rust、データベース、ネットワーク、Docker のデバッグツール	約 650
references/common-scenarios.md	メモリーリーク、デッドロック、競合状態、パフォーマンスのリグレッション、API のデバッグ、デプロイの問題	約 550

関連項目

• testing-ops -- バグの再発を防ぐテストを作成します
• security-ops -- セキュリティに特化したデバッグ（認証の失敗、インジェクション、CSRF）
• monitoring-ops -- 本番環境の可観測性、アラート、ダッシュボード
• code-stats -- コードの複雑さを測定し、バグが発生しやすい箇所を特定します
• docker-ops -- コンテナーのデバッグ（終了コード、distroless、ビルド）； kubernetes-ops -- Pod のデバッグ
• git-ops -- Git bisect のワークフローと履歴の調査