スナップショット デバッガーを使用して .NET アプリケーションの例外をデバッグする

  • [アーティクル]

スナップショット デバッガーを使用すると、実行中の .NET アプリケーションで例外が発生したときにデバッグ スナップショットを自動的に収集できます。 収集されたデバッグ スナップショットには、例外がスローされたときのソース コードと変数の状態が表示されます。

Application Insights のスナップショット デバッガーでは、以下を行います。

  • Web アプリからシステムによって生成されたログを監視します。
  • スローされる上位の例外のスナップショットを収集します。
  • 運用環境の問題を診断するために必要な情報を提供します。

スナップショット デバッガーとスナップショット アップローダー プロセスの詳細を確認してください。

サポートされているアプリケーションと環境

このセクションでは、サポートされているアプリケーションと環境を示します。

アプリケーション

スナップショット コレクションは次のアプリケーションで使用できます。

  • .NET Framework 4.6.2 以降のバージョン。
  • Windows 上の .NET 6.0 以降。

環境

次の環境がサポートされています。

Note

クライアント アプリケーション (たとえば、WPF、Windows フォーム、または UWP) はサポートされません。

スナップショット デバッガーを使うための前提条件

パッケージと構成

アクセス許可

スナップショット デバッガーのしくみ

スナップショット デバッガーは、Application Insights テレメトリ プロセッサとして実装されています。 アプリケーションが実行されると、スナップショット デバッガー テレメトリ プロセッサがアプリケーションのシステムで生成されたログ パイプラインに追加されます。

重要

スナップショットには、変数やパラメーターの値に個人データなどの機密情報が含まれている場合があります。 スナップショット データは、自分の Application Insights リソースと同じリージョンに格納されます。

スナップショット デバッガー プロセス

スナップショット デバッガー プロセスの開始と終了には TrackException メソッドを使います。 プロセス スナップショットは実行中のプロセスの一時停止されたクローンであるため、ユーザー側の中断はほとんど発生しません。

  1. アプリケーションから TrackException がスローされます。

  2. スナップショット デバッガーは、AppDomain.CurrentDomain.FirstChanceException イベントをサブスクライブすることで、スローされた例外を監視します。

  3. その問題 ID のカウンターが増分されます。

    • カウンターが ThresholdForSnapshotting 値に達すると、問題 ID が収集計画に追加されます。

    Note

    ThresholdForSnapshotting の既定の最小値は 1 です。 この値の場合、スナップショットが作成される前に、アプリは同じ例外を "2 回" トリガーする必要があります。

  4. 例外イベントの問題 ID が計算され、収集計画の問題 ID と比較されます。

  5. 一致する問題 ID があれば、実行中のプロセスのスナップショットが作成されます。

    • スナップショットには一意の識別子が割り当てられ、例外にはその識別子を使用してスタンプされます。

    Note

    スナップショットの作成速度は SnapshotsPerTenMinutesLimit 設定によって制限されます。 既定では、10 分ごとに 1 つのスナップショットが上限です。

  6. FirstChanceException ハンドラーが戻った後、スローされた例外は通常どおり処理されます。

  7. 例外は再び TrackException メソッドに到達し、スナップショット識別子と共に Application Insights に報告されます。

Note

Visual Studio でデバッグ中にスナップショットを生成する場合は、IsEnabledInDeveloperMode を true に設定します。

スナップショット アップローダー プロセス

スナップショット デバッガー プロセスが実行を継続し、ほとんど中断することなくユーザーにトラフィックを提供する間に、スナップショットはスナップショット アップローダー プロセスに渡されます。 スナップショット アップローダー:

  1. ミニダンプを作成します。

  2. 関連するシンボル (.pdb) ファイルと共にミニダンプを Application Insights にアップロードします。

Note

1 日あたり 50 個を超えるスナップショットをアップロードすることはできません。

スナップショット デバッガーを有効にしたのにスナップショットが表示されない場合は、「トラブルシューティング ガイド」を参照してください。

制限事項

このセクションでは、スナップショット デバッガーの制限事項について説明します。

  • データ保持

    デバッグ スナップショットは 15 日間格納されます。 デフォルトのデータ保持ポリシーは、アプリケーションごとに設定されます。 この値を増やす必要がある場合は、Azure portal でサポート ケースを開くことによって増加を要求できます。 Application Insights のインスタンスごとに、1 日あたり最大 50 個のスナップショットが許可されます。

  • シンボルを発行する

    スナップショット デバッガーでは、運用サーバー上のシンボル ファイルが次の処理を行う必要があります。

    • 変数をデコードする
    • Visual Studio でデバッグ エクスペリエンスを提供する

    Visual Studio 2017 のバージョン 15.2 以降では、App Service に公開する際に、既定でリリース ビルドのシンボルを公開します。

    以前のバージョンでは、シンボルがリリース モードで公開されるように、発行プロファイルの .pubxml ファイルに次の行を追加する必要があります。

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    Azure Compute および他のタイプでは、シンボル ファイルが次のいずれかであることを確認してください。

    • メイン アプリケーション .dll の同じフォルダー (通常は wwwroot/bin) にあること、または
    • 現在のパスで使用できること。

    使用できるさまざまなシンボル オプションについて詳しくは、Visual Studio のドキュメントをご覧ください。 最良の結果を得るために、Full、Portable、または Embedded を使用することをお勧めします。

  • 最適化されたビルド

    場合によっては、JIT コンパイラによって適用される最適化のために、リリース ビルドでローカル変数を表示できないことがあります。

    ただし、App Service では、スナップショット デバッガーが収集計画の一部であるスロー方法を非最適化する可能性があります。

    ヒント

    Application Insights サイト拡張機能を App Service のインスタンスにインストールして、非最適化のサポートを得ます。

次のステップ

次のアプリケーションに対して Application Insights スナップショット デバッガーを有効にします。

Microsoft.ApplicationInsights.SnapshotCollector のリリース ノート

このセクションでは、Application Insights スナップショット デバッガーで使用される、.NET アプリケーション向け Microsoft.ApplicationInsights.SnapshotCollector NuGet パッケージのリリース ノートを記載します。

.NET アプリケーション向け Application Insights スナップショット デバッガーの詳細については、こちらを参照してください。

バグ レポートとフィードバックについては、GitHub でイシューをオープンしてください。

Note

インストルメンテーション キーのインジェストのサポートは、2025 年 3 月 31 日に終了します。 インストルメンテーション キーのインジェストは引き続き機能しますが、この機能の更新プログラムやサポートは提供されなくなります。 接続文字列に移行することで、新機能をご利用いただけます。

1.4.6

.NET 8 アプリケーションを使用する際の回帰に対処するためのポイント リリース。

バグ修正

  • .NET 8 で動的に生成されたメソッド (たとえば、コンパイルされた式ツリーなど) からスローされた例外が正しく追跡されなません。 固定。

1.4.5

ユーザーから報告されたバグに対処するためのポイント リリース。

バグ修正

  • 一部の PDB を読み取る際の AccessViolationException を修正しました。

変更点

  • ReadMe を NuGet パッケージに追加しました。
  • msdia140.dll を更新しました。

1.4.4

ユーザーから報告されたバグに対処するためのポイントリリース。

バグの修正

[変更点]

  • PDB スキャンのエラー メッセージの重大度をエラーから警告に下げました。
  • msdia140.dll を更新しました。
  • サイト拡張機能の設定でデバッガーが無効になっている場合、サービス接続が行われません。

1.4.3

ユーザーから報告されたバグに対処するためのポイントリリース。

バグの修正

1.4.2

ユーザーから報告されたバグに対処するためのポイント リリース。

バグの修正

ArgumentException: デリゲートは同じ型である必要があるという問題を修正しました。

1.4.1

1\.4.0 で導入された破壊的変更を元に戻すためのポイント リリース。

バグの修正

WebJobs でメソッドが見つからないという問題を修正しました。

1.4.0

複数の機能強化に対処し、Application Insights インジェスト用の Microsoft Entra 認証のサポートを追加しました。

変更点

  • Snapshot Collector パッケージのサイズを 10.34 MB から 4.11 MB に 60% 縮小しました。
  • Snapshot Collector では netstandard2.0 のみをターゲットにしました。
  • Application Insights SDK の依存関係を 2.15.0 に上げました。
  • ダンプを書き込むときの MinidumpWithThreadInfo を再度追加しました。
  • 破壊的変更時の Snapshot Collector エージェントと Snapshot Uploader 間の同期を向上させるために、CompatibilityVersion を追加しました。
  • App Service のファイル I/O が過剰にならないように、SnapshotUploader LogFile の名前付けアルゴリズムを変更しました。
  • アップロードされる BLOB メタデータにpid、role name、およびprocess start timeを追加しました。
  • Snapshot Collector と Snapshot Uploader で System.Diagnostics.Process を使用しました。

新機能

Microsoft Entra 認証を SnapshotCollector に追加しました。 Application Insights での Microsoft Entra 認証の詳細については、Application Insights に対する Microsoft Entra 認証に関するページを参照してください。

1.3.7.5

1\.4.0-pre から修正プログラムをバックポートするポイント リリース。

バグの修正

シャットダウン時の ObjectDisposedException を修正しました。

1.3.7.4

App Service のコードなしアタッチ シナリオのテストで検出された問題に対処するポイント リリース。

[変更点]

netcoreapp3.0 ターゲットが、Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (以前は >= 2.1.2) に依存するようになりました。

1.3.7.3

影響の大きい 2 つの問題を解決するためのポイント リリース。

バグの修正

  • wwroot/bin フォルダーでの PDB 検出が修正されました。これは、1.3.6 でシンボル検索アルゴリズムを変更したときに破損しました。
  • テレメトリで頻繁に発生する ExtractWasCalledMultipleTimesException が修正されました。

1.3.7

[変更点]

SnapshotCollector の netcoreapp2.0 ターゲットは、Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 に (再度) 依存します。 この変更により、1.3.5 以前の動作に戻ります。 1.3.6 でアップグレードしようとしましたが、一部の App Service シナリオが破損しました。

新機能

Snapshot Collector が、APPLICATIONINSIGHTS_CONNECTION_STRING 環境変数または TelemetryConfiguration からConnectionString を読み取り、解析するようになりました。 これは主に、スナップショット サービスに接続する際にエンドポイントを設定するために使用されます。 詳細については、接続文字列に関するドキュメントを参照してください。

バグの修正

互換性のない SecurityProtocol (TLS 1.2 が必要) が原因で、一部の環境で WebRequest が失敗していたため、net45 を除くすべてのターゲットに対して HttpClient を使用するように切り替えました。

1.3.6

[変更点]

  • SnapshotCollector が、すべてのターゲット フレームワークに対して Microsoft.ApplicationInsights>= 2.5.1 に依存するようになりました。 アプリケーションが以前のバージョンの Microsoft.ApplicationInsights SDK に依存している場合、この要件は破壊的変更になる可能性があります。
  • Snapshot Uploader で TLS 1.0 と 1.1 のサポートが除去されました。
  • PDB スキャンの既定期間が、15 分ではなく 24 時間になりました。 SnapshotCollectorConfiguration の PdbRescanInterval を使用して構成できます。
  • PDB スキャンで、再帰的ではなく、最上位レベルのフォルダーのみ検索されるようになりました。 シンボルがバイナリ フォルダーのサブフォルダーにある場合、この変更は破壊的変更になる可能性があります。

新機能

  • logs フォルダーが古いファイルで一杯にならないようにするための SnapshotUploader でのログ ローテーション。
  • .NET Core 3.0 アプリケーションの (アタッチでの ReJIT による) 非最適化のサポート。
  • NuGet パッケージにシンボルを追加しました。
  • ミニダンプをアップロードするときに、メタデータを追加で設定します。
  • SnapshotCollectorTelemetryProcessor に Initialized プロパティを追加しました。 これは CancellationToken であり、Snapshot Collector が初期化され、サービスエンド ポイントに接続するとキャンセルされます。
  • 動的に生成されたメソッドでの例外に対してスナップショットをキャプチャできるようになりました。 例として、Entity Framework のクエリによって生成されるコンパイル済みの式ツリーなどがあります。

バグの修正

  • Status Monitor を原因とする Snapshot Collector 読み込み時の AmbiguousMatchException。
  • GetSnapshotCollector 拡張メソッドで、すべての TelemetrySinks が検索されるようになりました。
  • サポートされていないプラットフォームで Snapshot Uploader を開始しない。
  • 動的メソッドの非最適化時に InvalidOperationException を処理 (たとえば、Entity Framework)。

1.3.5

  • ソブリン クラウドのサポートが追加されました (以前のバージョンはソブリン クラウドでは動作しません)。
  • AddSnapshotCollector() を使用することで、Snapshot Collector を簡単に追加できるようになりました。 詳細については、「Azure App Service で .NET アプリでスナップショット デバッガーを有効にする」を参照してください。
  • BLOB ブロックの確認に FISMA MD5 設定を使用。 この設定により、既定の .NET MD5 暗号アルゴリズム (OS が FIPS 準拠モードに設定されている場合には使用できない) が回避されます。
  • 関数呼び出しを非最適化するときに .NET Framework フレームを無視。 DeoptimizeIgnoredModules の構成設定を使用して、この動作を制御します。
  • 複数の関数呼び出しを非最適化できる DeoptimizeMethodCount 構成設定を追加しました。

1.3.4

  • 構造化されたインストルメンテーション キーを許可しました。
  • Snapshot Uploader の堅牢性が向上しました。 古いアップローダー ログを移動できない場合でも、スタートアップが続行されます。
  • SnapshotUploader.exe が即座に終了したときの追加のテレメトリの報告を再有効化しました (1.3.3 では無効化されていました)。
  • 内部テレメトリを簡素化しました。
  • 試験的な機能: スナップポイント コレクション プラン。snapshotOnFirstOccurence を追加します。 詳しくは、こちらの GitHub の記事をご覧ください。

1.3.3

SnapshotUploader.exe が応答を停止し、.NET Core アプリのスナップショットがアップロードされないという問題の原因になっていたバグを修正しました。

1.3.2

  • 試験的な機能: スナップポイント コレクション プラン。 詳しくは、こちらの GitHub の記事をご覧ください。
  • SnapshotCollector の読み込み元の AppDomain がランタイムによってアンロードされると、処理が終了するのを待たずに、SnapshotUploader.exe が終了します。 このアクションにより、IIS でホストされている場合のコレクターの信頼性が向上します。
  • 同じインストルメンテーション キーを使用している複数の SnapshotCollector インスタンスが同じ SnapshotUploader プロセス: ShareUploaderProcess を共有できるように構成を追加しました (既定で true)。
  • SnapshotUploader.exe が即座に終了したときに、追加のテレメトリを報告するようにしました。
  • SnapshotUploader.exe がディスクへの書き込みを行うときに必要となるサポート ファイルの数を削減しました。

1.3.1

  • RtlCloneUserProcess API を使用してスナップショットを収集するためのサポートを削除し、PssCaptureSnapshots API のみをサポートするようにしました。
  • 10 分間でキャプチャできるスナップショットの既定の制限数を 1 から 3 に増加しました。
  • SnapshotUploader.exe で TLS 1.1 および1.2 のネゴシエートが可能です。
  • SnapshotUploader が警告またはエラーをログに記録したときに追加のテレメトリを報告するようにしました。
  • バックエンド サービスが 1 日あたりのクォータに達したことを報告したときに、スナップショットの作成を停止します (1 日あたり 50 のスナップショット)。
  • 2 つのインスタンスが同時に実行されないようにするために、SnapshotUploader.exe にチェックを追加しました。

1.3.0

[変更点]

  • .NET Framework をターゲットとするアプリケーションで、Snapshot Collector が Microsoft.ApplicationInsights バージョン 2.3.0 以降に依存するようになりました。 以前は 2.2.0 以降が使用されていました。 この変更は、ほとんどのアプリケーションでは問題にならないと考えられます。 この変更が最新の Snapshot Collector の使用の妨げになる場合は、お知らせください。
  • 失敗したアップロードを再試行するときに、Snapshot Uploader で指数バックオフ遅延を使用。
  • テレメトリでのレポート作成の信頼性を高めるために、ServerTelemetryChannel を使用します (使用可能な場合)。
  • 依存関係の追跡で無視されるように、スナップショット デバッガー サービスへの初期接続時に SdkInternalOperationsMonitor を使用します。
  • スナップショット デバッガーへの初期接続に関するテレメトリを改善しました。
  • 次の詳細なテレメトリを報告します。
    • App Service バージョン。
    • Azure コンピューティング インスタンス。
    • コンテナー。
    • Azure Functions アプリ。

バグの修正

  • 問題カウンターのリセット間隔が 24 日に設定されている場合に、24 時間と解釈される。
  • スナップショットの破棄中に例外が発生した場合に、Snapshot Uploader が新しいスナップショットの処理を停止するというバグを修正。

1.2.3

Snapshot Uploader バイナリでの厳密な名前の署名を修正しました。

1.2.2

[変更点]

  • SnapshotUploader(64).exe に必要なファイルが、メイン DLL にリソースとして埋め込まれるようになりました。 これにより、SnapshotCollectorFiles フォルダーが作成されなくなり、ビルドとデプロイが簡略化され、ソリューション エクスプローラーでの煩雑さが軽減されます。 アップグレード時には、.csproj ファイルの変更を入念に確認してください。 Microsoft.ApplicationInsights.SnapshotCollector.targets ファイルは不要になりました。
  • ProvideAnonymousTelemetry が false に設定されている場合でも、テレメトリが Application Insights リソースに記録されます。 この変更は、Azure portal に正常性チェック機能を実装できるようにするための措置です。 ProvideAnonymousTelemetry は、製品のサポートと改善のためにマイクロソフトに送信されるテレメトリにのみ影響します。
  • TempFolder または ShadowCopyFolder が環境変数にリダイレクトされるとき、これらの環境変数が設定されるまでコレクターをアイドル状態のまま維持します。
  • プロキシ サーバー経由でインターネットに接続するアプリケーションで、Snapshot Collector はプロキシ設定を自動検出し、SnapshotUploader.exe に渡します。
  • SnapshotUploader プロセスの優先順位を下げます (可能な場合)。 この優先順位は IsLowPrioirtySnapshotUploader オプションを使用してオーバーライドできます。
  • プログラムを使用して Snapshot Collector を構成するシナリオのために、GetSnapshotCollector 拡張メソッドを TelemetryConfiguration に追加しました。
  • 顧客向けのテレメトリで (アプリケーションのバージョンではなく) Application Insights SDK のバージョンを設定。
  • 2 分後に最初のハートビート イベントを送信。

バグの修正

  • 例外に null 値または不変のデータ ディクショナリが含まれている場合の NullReferenceException を修正しました。
  • アップローダーで、共有違反が発生した場合に、PDB の照合を数回再試行。
  • スタートアップ時に複数のスレッドがテレメトリ パイプラインに呼び出されたときの重複するテレメトリを修正。

1.2.1

[変更点]

  • XML ドキュメント コメント ファイルが NuGet パッケージに含まれるようになりました。
  • 頻繁に発生する例外があることがわかっていて、それに対してスナップショットが作成されないようにする場合のために、ExcludeFromSnapshotting 拡張メソッドを System.Exception に追加しました。
  • 既定で true に設定される IsEnabledWhenProfiling 構成プロパティを追加しました。 これは、Application Insights Profiler が詳細なコレクションを実行した場合に、スナップショットの作成が一時的に無効化された以前のバージョンからの変更点です。 以前の動作を復元するには、このプロパティを false に設定します。

バグの修正

  • SnapshotUploader64.exe に適切に署名します。
  • テレメトリ プロセッサの二重の初期化を防止。
  • 複数のパイプラインがあるアプリで、テレメトリの二重のログ記録を防止。
  • 収集計画の期限切れ日時に関するバグ (24 時間後にスナップショットが妨げられる場合がある) を修正しました。

1.2.0

このバージョンでの最大の変更 (したがって、新しいマイナー バージョン番号に移行) は、スナップショットの作成および処理パイプラインの更新です。 以前のバージョンでは、この機能は、ネイティブ コード (ProductionBreakpoints.dll* および SnapshotHolder.exe*) で実装されていました。 新しい実装は、すべて P/Invoke を使用したマネージド コードです。

新しいパイプラインを使用したこの最初のバージョンでは、動作は元の動作から大幅には変わっていません。 新しい実装では、より適切なエラー報告ができるようになり、今後の改善のための用意ができました。

このバージョンのその他の変更

  • MinidumpUploader.exe の名前が SnapshotUploader.exe (または SnapshotUploader64.exe) に変更されました。
  • DeOptimize/ReOptimize 要求にタイミング テレメトリを追加。
  • ミニダンプ アップロードのための gzip 圧縮を追加。
  • PDB がロックされ、サイトのアップグレードが妨げられる問題を修正。
  • シャドウ コピー時に元のフォルダー名 (SnapshotCollectorFiles) をログに記録します。
  • OOM が原因のサイトの再起動を防止するために、64 ビット プロセスのメモリ制限を調整しました。
  • 無効化後もスナップショットが収集される問題を修正しました。
  • 顧客の AI リソースにハートビート イベントを記録。
  • 問題 ID から "ソース" を削除することで、スナップショットの速度を向上しました。

1.1.2

[変更点]

  • 使用状況テレメトリを拡張しました。
  • .NET バージョンと OS を検出して報告します。
  • より多くの Azure 環境 (Azure Cloud Services、Azure Service Fabric) を検出して報告します。
  • ハートビート テレメトリでの例外メトリック (初回例外の数と TrackException 呼び出しの数) を記録して報告します。

バグの修正

  • 内部例外 (Win32Exception) がスローされない SqlException の処理を修正します。
  • シンボル フォルダーの末尾スペースのトリミング。これが原因で、MinidumpUploader へのコマンドライン引数が正しく解析されませんでした。
  • スナップショット デバッガー エージェントのエンドポイントへの接続失敗時に無限に再試行されるのを防止しました。

1.1.0

[変更点]

  • ホスト メモリの保護を追加。 この機能により、ホスト コンピューターのメモリへの影響が軽減されます。
  • Azure portal スナップショットの表示エクスペリエンスを改善しました。