debugging-techniques

デバッグ手法

目的

Python、Go、Rust、Node.jsを対象に、ローカル、リモート、コンテナー、本番環境での体系的なデバッグワークフローを提供します。対話型デバッガー、エフェメラルコンテナーを使ったコンテナーデバッグ、相関 ID と分散トレーシングを使った本番環境に安全な手法を扱います。

このスキルを使う場面

次の場合に、このスキルを利用します。

• Python、Go、Rust、Node.jsのコードにブレークポイントを設定する
• 実行中のコンテナーや Kubernetes ポッドをデバッグする
• リモートデバッグ接続を設定する
• 本番環境の問題を安全にデバッグする
• ゴルーチン、スレッド、非同期タスクを調査する
• コアダンプやスタックトレースを分析する
• 状況に適したデバッグツールを選択する

言語別クイックリファレンス

Python のデバッグ

組み込み：pdb

# Python 3.7+
def buggy_function(x, y):
    breakpoint()  # Stops execution here
    return x / y

# Older Python
import pdb
pdb.set_trace()

基本的な pdb コマンド：

• list (l) - 現在の行の前後のコードを表示
• next (n) - 現在の行を実行し、関数の中には入らずに進む
• step (s) - 現在の行を実行し、関数の中に入る
• continue (c) - 次のブレークポイントまで続行
• print var (p) - 変数の値を表示
• where (w) - スタックトレースを表示
• quit (q) - デバッガーを終了

拡張ツール：

• ipdb - タブ補完と構文ハイライトに対応した拡張版 pdb（pip install ipdb）
• pudb - ターミナル GUI デバッガー（pip install pudb）
• debugpy - VS Code との統合（Python 拡張機能に含まれています）

テストのデバッグ：

pytest --pdb  # Drop into debugger on test failure

Python のデバッグパターンの詳細は、references/python-debugging.md を参照してください。

Go のデバッグ

Delve - Go 公式デバッガー

インストール：

go install github.com/go-delve/delve/cmd/dlv@latest

基本的な使い方：

dlv debug main.go              # Debug main package
dlv test github.com/me/pkg     # Debug test suite
dlv attach <pid>               # Attach to running process
dlv debug -- --config prod.yaml  # Pass arguments

基本的なコマンド：

• break main.main (b) - 関数にブレークポイントを設定
• break file.go:10 (b) - 行にブレークポイントを設定
• continue (c) - 実行を続行
• next (n) - ステップオーバー
• step (s) - ステップイン
• print x (p) - 変数を表示
• goroutine (gr) - 現在のゴルーチンを表示
• goroutines (grs) - すべてのゴルーチンを一覧表示
• goroutines -t - ゴルーチンのスタックトレースを表示
• stack (bt) - スタックトレースを表示

ゴルーチンのデバッグ：

(dlv) goroutines                 # List all goroutines
(dlv) goroutines -t              # Show stacktraces
(dlv) goroutines -with user      # Filter user goroutines
(dlv) goroutine 5                # Switch to goroutine 5

Go のデバッグパターンの詳細は、references/go-debugging.md を参照してください。

Rust のデバッグ

LLDB - Rust のデフォルトデバッガー

コンパイル：

cargo build  # Debug build includes symbols by default

使い方：

rust-lldb target/debug/myapp   # LLDB wrapper for Rust
rust-gdb target/debug/myapp    # GDB wrapper (alternative)

基本的な LLDB コマンド：

• breakpoint set -f main.rs -l 10 - 行にブレークポイントを設定
• breakpoint set -n main - 関数にブレークポイントを設定
• run (r) - プログラムを開始
• continue (c) - 実行を続行
• next (n) - ステップオーバー
• step (s) - ステップイン
• print variable (p) - 変数を表示
• frame variable (fr v) - ローカル変数を表示
• backtrace (bt) - スタックトレースを表示
• thread list - すべてのスレッドを一覧表示

VS Code との統合：

• CodeLLDB 拡張機能（vadimcn.vscode-lldb）をインストール
• Rust プロジェクト用に launch.json を設定

Rust のデバッグパターンの詳細は、references/rust-debugging.md を参照してください。

Node.js のデバッグ

組み込み：node --inspect

基本的な使い方：

node --inspect-brk app.js       # Start and pause immediately
node --inspect app.js           # Start and run
node --inspect=0.0.0.0:9229 app.js  # Specify host/port

Chrome DevTools：

1. chrome://inspect を開く
2. 「Node 用の専用 DevTools を開く」をクリック
3. ブレークポイントを設定し、変数を調査する

VS Code との統合： launch.json を設定します。

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js"
}

Docker のデバッグ：

EXPOSE 9229
CMD ["node", "--inspect=0.0.0.0:9229", "app.js"]

Node.js のデバッグパターンの詳細は、references/nodejs-debugging.md を参照してください。

コンテナーと Kubernetes のデバッグ

エフェメラルコンテナーを使った kubectl debug

使用する場面：

• コンテナーがクラッシュした場合（kubectl exec は使用できません）
• distroless や最小構成のイメージを使用している場合（シェルやツールがありません）
• イメージを再ビルドせずにデバッグツールが必要な場合
• ネットワークの問題をデバッグする場合

基本的な使い方：

# Add ephemeral debugging container
kubectl debug -it <pod-name> --image=nicolaka/netshoot

# Share process namespace (see other container processes)
kubectl debug -it <pod-name> --image=busybox --share-processes

# Target specific container
kubectl debug -it <pod-name> --image=busybox --target=app

推奨デバッグイメージ：

• nicolaka/netshoot（約380MB）- ネットワークのデバッグ用（curl、dig、tcpdump、netstat）
• busybox（約1MB）- 最小限のシェルとユーティリティ
• alpine（約5MB）- パッケージマネージャーを備えた軽量イメージ
• ubuntu（約70MB）- 完全な環境

Node のデバッグ：

kubectl debug node/<node-name> -it --image=ubuntu

Docker コンテナーのデバッグ：

docker exec -it <container-id> sh

# If no shell available
docker run -it --pid=container:<container-id> \
           --net=container:<container-id> \
           busybox sh

コンテナーのデバッグパターンの詳細は、references/container-debugging.md を参照してください。

本番環境のデバッグ

本番環境でのデバッグの原則

基本ルール：

1. パフォーマンスへの影響を最小限にする - オーバーヘッドを測定し、範囲を限定します
2. ブロッキング操作を行わない - 影響のない手法を使用します
3. セキュリティに配慮する - シークレットや個人情報をログに記録しないようにします
4. 元に戻せるようにする - 迅速にロールバックできるようにします（フィーチャーフラグ、Git）
5. 可観測性を確保する - 構造化ログ、相関 ID、トレーシングを使用します

本番環境で安全に使える手法

1. 構造化ログ

import logging
import json

logger = logging.getLogger(__name__)
logger.info(json.dumps({
    "event": "user_login_failed",
    "user_id": user_id,
    "error": str(e),
    "correlation_id": request_id
}))

2. 相関 ID（リクエストトレーシング）

func handleRequest(w http.ResponseWriter, r *http.Request) {
    correlationID := r.Header.Get("X-Correlation-ID")
    if correlationID == "" {
        correlationID = generateUUID()
    }
    ctx := context.WithValue(r.Context(), "correlationID", correlationID)
    log.Printf("[%s] Processing request", correlationID)
}

3. 分散トレーシング（OpenTelemetry）

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def process_order(order_id):
    with tracer.start_as_current_span("process_order") as span:
        span.set_attribute("order.id", order_id)
        span.add_event("Order validated")

4. エラートラッキングプラットフォーム

• Sentry - コンテキスト付きの例外トラッキング
• New Relic - エラートラッキング機能付き APM
• Datadog - ログ、メトリクス、トレース
• Rollbar - エラーモニタリング

本番環境でのデバッグワークフロー：

1. 検知 - エラートラッキングのアラート、ログの急増、メトリクスの異常
2. 特定 - 相関 ID を見つけ、ログを検索し、分散トレースを確認します
3. 再現 - 本番データをサニタイズしてステージング環境で再現を試みます
4. 修正 - フィーチャーフラグを作成し、まずカナリアにデプロイします
5. 検証 - エラー率を確認し、ログを見直し、トレースを監視します

本番環境でのデバッグパターンの詳細については、references/production-debugging.md を参照してください。

判断フレームワーク

言語ごとに適したデバッガー

言語	主なツール	インストール	最適な用途
Python	pdb	組み込み	シンプルなスクリプト、サーバー環境
	ipdb	pip install ipdb	使いやすさの向上、IPython ユーザー
	debugpy	VS Code extension	IDE 統合、リモートデバッグ
Go	delve	go install github.com/go-delve/delve/cmd/dlv@latest	Go のあらゆるデバッグ、ゴルーチン
Rust	rust-lldb	システムパッケージ	Mac、Linux、MSVC Windows
	rust-gdb	システムパッケージ	Linux、GDB を優先する場合
Node.js	node --inspect	組み込み	Node.js のあらゆるデバッグ、Chrome DevTools

シナリオごとに適した手法

シナリオ	推奨される手法	ツール
ローカル開発	対話型デバッガー	pdb, delve, lldb, node --inspect
テスト内のバグ	テスト固有のデバッグ	pytest --pdb, dlv test, cargo test
リモートサーバー	SSH トンネル + リモート接続	VS Code Remote, debugpy
コンテナ（ローカル）	docker exec -it	sh/bash + デバッガー
Kubernetes ポッド	エフェメラルコンテナ	kubectl debug --image=nicolaka/netshoot
Distroless イメージ	エフェメラルコンテナ（必須）	busybox/alpine を使った kubectl debug
本番環境の問題	ログ分析 + エラートラッキング	構造化ログ、Sentry、相関 ID
ゴルーチンのデッドロック	ゴルーチンの調査	delve goroutines -t
クラッシュしたプロセス	コアダンプ分析	gdb core, lldb -c core
分散システムの障害	分散トレーシング	OpenTelemetry, Jaeger, 相関 ID
データ競合	レース検出器 + デバッガー	go run -race, cargo test

本番環境でのデバッグ安全チェックリスト

本番環境でデバッグを行う前に：

• パフォーマンスに影響しますか？（オーバーヘッドを測定します）
• ユーザーの操作をブロックしますか？（影響のない手法を使用します）
• シークレットが漏えいする可能性はありますか？（変数のダンプを避けます）
• ロールバック計画はありますか？（Git ブランチ、フィーチャーフラグ）
• まずログを確認しましたか？（影響がより少ない方法です）
• 相関 ID はありますか？（リクエストをトレースします）
• エラートラッキングは有効になっていますか？（Sentry、New Relic）
• ステージング環境で再現できますか？（より安全な環境）

よくあるデバッグワークフロー

ワークフロー 1：ローカル開発でのバグ

1. コードにブレークポイントを設定します（言語固有の方法を使用）
2. デバッガーを起動します（dlv debug、rust-lldb、node --inspect-brk）
3. ブレークポイントまで実行します（run、continue）
4. 変数を確認します（print、frame variable）
5. コードをステップ実行します（next、step、finish）
6. 問題を特定して修正します

ワークフロー 2：テスト失敗のデバッグ

Python：

pytest --pdb  # Drops into pdb on failure

Go：

dlv test github.com/user/project/pkg
(dlv) break TestMyFunction
(dlv) continue

Rust：

cargo test --no-run
rust-lldb target/debug/deps/myapp-<hash>
(lldb) breakpoint set -n test_name
(lldb) run test_name

ワークフロー 3：Kubernetes ポッドのデバッグ

シナリオ：Distroless イメージのポッドでネットワークの問題が発生

# Step 1: Check pod status
kubectl get pod my-app-pod -o wide

# Step 2: Check logs first
kubectl logs my-app-pod

# Step 3: Add ephemeral container if logs insufficient
kubectl debug -it my-app-pod --image=nicolaka/netshoot

# Step 4: Inside debug container, investigate
curl localhost:8080
netstat -tuln
nslookup api.example.com

ワークフロー 4：本番環境のエラー調査

シナリオ：API が 500 エラーを返す

# Step 1: Check error tracking (Sentry)
# - Find error details, stack trace
# - Copy correlation ID from error report

# Step 2: Search logs for correlation ID
# In log aggregation tool (ELK, Splunk):
# correlation_id:"abc-123-def"

# Step 3: View distributed trace
# In tracing tool (Jaeger, Datadog):
# Search by correlation ID, review span timeline

# Step 4: Reproduce in staging
# Use production data (sanitized) if needed
# Add additional logging if needed

# Step 5: Fix and deploy
# Create feature flag for gradual rollout
# Deploy to canary environment first
# Monitor error rates closely

追加リソース

言語固有の詳細については、以下を参照してください。

• references/python-debugging.md - pdb、ipdb、pudb、debugpy の詳細ガイド
• references/go-debugging.md - Delve CLI、goroutine のデバッグ、条件付きブレークポイント
• references/rust-debugging.md - LLDB と GDB の比較、所有権のデバッグ、マクロのデバッグ
• references/nodejs-debugging.md - node --inspect、Chrome DevTools、Docker のデバッグ

環境固有のパターンについては、以下を参照してください。

• references/container-debugging.md - kubectl debug、一時コンテナ、ノードのデバッグ
• references/production-debugging.md - 構造化ログ、相関 ID、OpenTelemetry、エラートラッキング

判断のサポートについては、以下を参照してください。

• references/decision-trees.md - 拡張版デバッグ判断フレームワーク

実践的な例については、以下を参照してください。

• examples/ - 各言語のステップごとのデバッグセッション

関連スキル

認証パターンについては、auth-security スキルを参照してください。 パフォーマンスプロファイリング（デバッグを補完するもの）については、performance-engineering スキルを参照してください。 Kubernetes の操作（kubectl debug が含まれます）については、kubernetes-operations スキルを参照してください。 テストのデバッグ戦略については、testing-strategies スキルを参照してください。 可観測性のセットアップ（ロギング、トレース）については、observability スキルを参照してください。