dotnet-debugging

dotnet-debugging

概要

WinDbg MCP ツール（Windows）、dotnet-dump、および SOS を使用する lldb（Linux/macOS）による、Windows および Linux/macOS のデバッグです。ネイティブ、マネージド（.NET/CLR）、混在モードを問わず、あらゆるアプリケーションに適用できます。Docker および Kubernetes のコンテナー診断パターンも含まれます。構造化されたコマンドパックとレポートテンプレートを通じて、クラッシュダンプ、アプリケーションのハング、高 CPU 使用率、メモリプレッシャーの調査方法を案内します。

プラットフォーム： Windows（WinDbg MCP、cdb）、Linux/macOS（dotnet-dump、SOS を使用する lldb、createdump、dotnet-monitor）。

ルーティングテーブル

トピック	キーワード	説明	関連ファイル
MCP の設定	MCP サーバー、WinDbg、設定	MCP サーバーの設定	references/mcp-setup.md
MCP アクセス	MCP アクセス、ツール ID、ディスパッチ	MCP のアクセスパターン	references/access-mcp.md
一般的なパターン	デバッグパターン、SOS、CLR	一般的なデバッグパターン	references/common-patterns.md
ダンプのワークフロー	ダンプファイル、.dmp、クラッシュダンプ	ダンプファイルの分析ワークフロー	references/dump-workflow.md
ライブアタッチ	ライブプロセス、cdb、アタッチ	ライブプロセスのアタッチガイド	references/live-attach.md
シンボル	シンボルサーバー、.symfix、PDB	シンボルの設定	references/symbols.md
整合性チェック	検証、環境、ベースライン	整合性チェックの手順	references/sanity-check.md
シナリオパック	コマンドパック、トリアージ、ワークフロー	シナリオ別コマンドパック	references/scenario-command-packs.md
キャプチャ手順書	キャプチャ、procdump、トリガー	キャプチャ手順書	references/capture-playbooks.md
レポートテンプレート	診断レポート、証拠	診断レポートのテンプレート	references/report-template.md
クラッシュトリアージ	クラッシュ、例外、アクセス違反	クラッシュトリアージ	references/task-crash.md
ハングトリアージ	ハング、デッドロック、フリーズ	ハングトリアージ	references/task-hang.md
高 CPU 使用率のトリアージ	高 CPU 使用率、暴走スレッド、スピン	高 CPU 使用率のトリアージ	references/task-high-cpu.md
メモリトリアージ	メモリリーク、ヒープ、LOH	メモリリークのトリアージ	references/task-memory.md
カーネルデバッグ	カーネル、BSOD、バグチェック	カーネルデバッグ	references/task-kernel.md
未知の問題のトリアージ	未知の問題、一般的なトリアージ	未知の問題のトリアージ	references/task-unknown.md
Linux のデバッグ	dotnet-dump、lldb、createdump、コンテナー	Linux/macOS のデバッグ、dotnet-dump、lldb SOS、コンテナー	references/linux-debugging.md

対象範囲

• Windows、Linux、macOS でのクラッシュダンプ分析（.dmp ファイル）
• ライブプロセスへのアタッチ（Windows では cdb、Linux/macOS では lldb）
• ハングとデッドロックの診断（スレッド分析、ロック検出、待機チェーン）
• 高 CPU 使用率のトリアージ（暴走スレッドの特定）
• メモリプレッシャーとメモリリークの調査（マネージドヒープ、ネイティブヒープ）
• カーネルダンプのトリアージ（BSOD／バグチェック分析、Windows）
• コンテナー診断（Docker/Kubernetes での dotnet-dump、サイドカーパターン）
• 本番環境の診断（dotnet-monitor REST API、トリガーベースの収集）
• すべてのプラットフォームにおける SOS コマンド（WinDbg、dotnet-dump、lldb）
• スタックの証拠を含む構造化された診断レポート

dotnet-tooling との境界

両方のスキルで重複するツール（dotnet-dump、dotnet-counters、dotnet-trace）を使用しますが、目的は異なります。

シナリオ	このスキルを使用（デバッグ）	dotnet-tooling を使用
クラッシュダンプ（.dmp）の調査	はい	いいえ
「アプリがクラッシュ／ハング／OOM した原因は？」	はい	いいえ
実行中のプロセスへのデバッガーのアタッチ	はい	いいえ
「アプリのパフォーマンスをプロファイルする方法は？」	いいえ	はい（プロファイリング）
「GC の負荷を軽減する方法は？」	いいえ	はい（gc-memory）
後で分析するためのダンプの収集	はい	いいえ
dotnet-counters によるメトリクスの監視	いいえ	はい（プロファイリング）
dotnet-dump によるダンプの分析	はい	いいえ
動作を理解するためのアセンブリの逆コンパイル	いいえ	はい（ilspy-decompile）

目安：何かが壊れている（クラッシュ、ハング、デッドロック、OOM）場合は、こちらに振り分けてください。何かが遅い、または最適化が必要な場合は、dotnet-tooling に振り分けてください。

対象外

• パフォーマンスプロファイリング（最適化のための dotnet-counters、dotnet-trace）-> dotnet-tooling
• GC の調整とマネージドメモリの最適化 -> dotnet-tooling
• アセンブリの逆コンパイル（ILSpy） -> dotnet-tooling
• パフォーマンスのベンチマークとリグレッションの検出 -> dotnet-testing
• アプリケーションレベルのロギングと可観測性 -> dotnet-devops
• 単体テスト／統合テストのデバッグ -> dotnet-testing

MCP ツールの契約

これらのツール ID は、WinDbg MCP サーバーがエクスポートする名前（単一アンダースコアの mcp_...）であり、一部のホストで使用される mcp__... ディスパッチプレフィックスではありません。

操作	目的
mcp_mcp-windbg_open_windbg_remote	実行中のデバッグサーバーに接続
mcp_mcp-windbg_open_windbg_dump	保存済みのダンプファイルを開く
mcp_mcp-windbg_run_windbg_cmd	デバッガーコマンドを実行
mcp_mcp-windbg_close_windbg_remote	実行中のセッションから切断
mcp_mcp-windbg_close_windbg_dump	ダンプセッションを閉じる

診断ワークフロー

事前確認：シンボル

有意義なスタックを取得するため、分析の前にシンボルを設定します。

1. Microsoft シンボルサーバーを設定します：.symfix（srv* を Microsoft のパブリックシンボルに設定）
2. アプリケーションのシンボルを追加します：.sympath+ C:\path\to\your\pdbs
3. モジュールを再読み込みします：.reload /f
4. 確認します：lm（モジュール一覧。「deferred」と「loaded」の状態を確認）

正しいシンボルがない場合、スタックには関数名ではなく生のアドレスが表示されます。

クラッシュダンプの分析

1. ダンプを開きます：ダンプファイルのパスを指定して mcp_mcp-windbg_open_windbg_dump を実行
2. マネージドコード用に SOS を読み込みます：.loadby sos clr（Framework）または .loadby sos coreclr（.NET Core）
3. 例外のコンテキストを取得します：!pe（例外を表示）、!analyze -v（自動分析）
4. スレッドを調べます：~*e !clrstack（すべてのマネージドスタック）、!threads（スレッド一覧）
5. マネージドヒープを確認します：!dumpheap -stat（ヒープの概要）、!gcroot <addr>（オブジェクトのルート）

ハング／デッドロックの診断

1. アタッチするかダンプを開き、SOS を読み込みます
2. すべてのスレッドを一覧表示します：!threads。!syncblk（同期ブロックテーブル）で待機中のスレッドを特定します
3. デッドロックを検出します：!dlk（SOS によるデッドロック検出）
4. スレッドスタックを調べます：特定のスレッド N に対して ~Ns !clrstack
5. 待機理由を確認します：COM/RPC チェーンには !waitchain、MDA 診断には !mda

高 CPU 使用率の初期調査

1. 実行中のプロセスにアタッチするか、10～30 秒間隔で複数のダンプを収集します
2. !runaway を使って、最も多くの CPU 時間を消費しているスレッドを特定します
3. 負荷の高いスレッドのスタックを調べます：~Ns kb（ネイティブスタック）、~Ns !clrstack（マネージドスタック）
4. タイトなループ、ブロックされたファイナライザースレッド、または過剰な GC がないか確認します

メモリ負荷の調査

1. ダンプを開き、SOS を読み込みます
2. マネージドヒープを確認します：!dumpheap -stat（型の統計情報）、!dumpheap -type <TypeName>（型で絞り込み）
3. リークしたオブジェクトを見つけます：!gcroot <address>（GC ルートをたどり、ピン留めされた参照または静的参照を特定）
4. ネイティブヒープを確認します：!heap -s（ヒープの概要）、!heap -l（リーク検出）
5. LOH の断片化を確認します：!eeheap -gc（GC ヒープセグメント）

レポートテンプレート

## Diagnostic Report

**Symptom:** [crash/hang/high-cpu/memory-leak]
**Process:** [name, PID, bitness]
**Dump type:** [full/mini/live-attach]

### Evidence
- Exception: [type and message, or N/A]
- Faulting thread: [ID, managed/native, stack summary]
- Key stacks: [condensed callstack with module!function]

### Root Cause
[Concise analysis backed by stack/heap evidence]

### Recommendations
[Numbered action items]

ガードレール

• 呼び出し先側の証拠なしに、確実であると断言しないでください
• ロック／待機の証拠がない限り、デッドロックと呼ばないでください
• ユーザーのプライバシーを守ってください。レポートに環境ブロック内のシークレットを含めないでください

相互参照：.NET SDK 診断ツール（references/profiling.md）と GC／メモリのチューニング（references/gc-memory.md）については、dotnet-tooling を参照してください。

参考資料

• WinDbg MCP -- WinDbg 統合用の MCP サーバー
• WinDbg のドキュメント -- Microsoft のデバッガーに関するドキュメント