.NET アプリでの例外でのデバッグ スナップショット

例外が発生したとき、実行中の Web アプリケーションからデバッグ スナップショットを自動的に収集できます。 デバッグ スナップショットには、例外がスローされたときのソース コードと変数の状態が表示されます。 Azure Application Insights のスナップショット デバッガーでは、以下を行います。

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

スナップショット コレクター NuGet パッケージをアプリケーションに含め、ApplicationInsights.config にコレクション パラメーターを構成します。

スナップショットが、Azure portal の [Application Insights] ペインの [例外] に表示されます。

ポータルで [Debug Snapshots (デバッグ スナップショット)] を表示して、コール スタックを表示し、各呼び出しスタック フレームで変数を確認できます。 ソース コードによるデバッグ エクスペリエンスをさらに向上させるには、Visual Studio Enterprise でスナップショットを開きます。 また、例外を待たずにスナップポイントを設定し、対話形式でスナップショットを取得できます。

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

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

  • .NET Framework LTS 以降を実行している .NET Framework と ASP.NET のアプリケーション。
  • Windows 上の .NET Core LTS を実行している .NET Core と ASP.NET Core のアプリケーション。
  • Windows 上の .NET LTS アプリケーション。

LTS より前のバージョンの .NET Core はサポート対象外であるため、使用しないことをお勧めします。

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

Note

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

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

[アクセス許可の付与]

スナップショットへのアクセスは、Azure ロールベースのアクセス制御 (Azure RBAC) によって保護されます。 スナップショットを検査するユーザーは、最初にサブスクリプション所有者によって必要なロールに追加される必要があります。

Note

所有者と共同作成者には、このロールは自動的に割り当てられません。 所有者や共同作成者がスナップショットを見る場合は、自分自身をロールに追加する必要があります。

サブスクリプション所有者は、スナップショットを検査する予定のユーザーに Application Insights スナップショット デバッガーのロールを割り当てる必要があります。 このロールは、Application Insights のターゲット リソース、リソース グループ、またはサブスクリプションに関するサブスクリプション所有者が、個々のユーザーまたはグループに割り当てることができます。

デバッガー ロールを Application Insights スナップショットに割り当てます。

詳細な手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。

重要

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

Portal でスナップショットを表示する

アプリケーションで例外が発生してスナップショットが作成されたら、5 から 10 分以内に Azure portal でスナップショットを表示することができます。 スナップショットを表示するには、[エラー] ウィンドウで次のいずれかを実行します。

  • [操作] タブを表示するときに [操作] ボタンを選択します。または、
  • [例外] タブを表示するときに [例外] ボタンを選択します。

Azure portal の [エラー] ページを示すスクリーンショット。

右側のウィンドウで操作または例外を選択して、 [エンドツーエンド トランザクション詳細] ウィンドウを開き、次に例外イベントを選択します。 特定の例外のスナップショットが使用可能な場合、例外の詳細と共に右側のウィンドウに [デバッグ スナップショットを開く] ボタンが表示されます。

例外の [デバッグ スナップショットを開く] ボタンを示すスクリーンショット。

デバッグ スナップショット ビューには、コール スタックと変数ウィンドウが表示されます。 コール スタック ウィンドウでコール スタックのフレームを選択すると、変数ウィンドウでその関数呼び出しのローカル変数とパラメーターを表示できます。

Azure portal で [デバッグ スナップショットを開く] が強調表示されているスクリーンショット。

スナップショットには機密情報が含まれる可能性があります。 既定では、Application Insights Snapshot Debugger ロールが割り当てられている場合にのみスナップショットを表示できます。

Visual Studio 2017 Enterprise 以上でスナップショットを表示する

  1. [Download Snapshot](スナップショットのダウンロード) をクリックして .diagsession ファイルをダウンロードします。このファイルは Visual Studio Enterprise で開くことができます。

  2. .diagsession ファイルを開くには、スナップショット デバッガーの Visual Studio コンポーネントがインストールされている必要があります。 スナップショット デバッガー コンポーネントは、Visual Studio の ASP.NET ワークロードに必要なコンポーネントです。これは、Visual Studio インストーラーの個々のコンポーネント リストから選択することができます。 Visual Studio 2017 バージョン 15.5 より前のバージョンの Visual Studio を使用している場合、拡張機能は Visual Studio Marketplace からインストールする必要があります。

  3. スナップショット ファイルを開くと、Visual Studio の[ミニダンプ デバッグ] ページが表示されます。 [Debug Managed Code](マネージド コードをデバッグする) をクリックして、スナップショットのデバッグを開始します。 例外がスローされたコード行がスナップショットに表示され、プロセスの現在の状態をデバッグできます。

    Visual Studio でのデバッグ スナップショットを示すスクリーンショット。

ダウンロードしたスナップショットには、Web アプリケーション サーバーで検出されたすべてのシンボル ファイルが含まれます。 これらのシンボル ファイルは、スナップショット データをソース コードと関連付けるために必要です。 App Service アプリの場合は、Web アプリを公開するときにシンボル デプロイを有効にしてください。

スナップショットのしくみ

Snapshot Collector は、Application Insights Telemetry Processor として実装されています。 アプリケーションが実行されると、Snapshot Collector Telemetry Processor がアプリケーションのシステムで生成されたログ パイプラインに追加されます。 アプリケーションが TrackException を呼び出すたびに、Snapshot Collector はスローされる例外の種類とスロー方法から問題 ID を計算します。 アプリケーションが TrackException を呼び出すたびに、該当する問題 ID のカウンターが増分されます。 カウンターが ThresholdForSnapshotting 値に達すると、問題 ID が収集計画に追加されます。

AppDomain.CurrentDomain.FirstChanceException イベントにサブスクライブすることで例外がスローされるので、Snapshot Collector は例外も監視します。 そのイベントが発生すると、例外の問題 ID が計算され、収集計画の問題 ID と比較されます。 一致する ID があれば、実行中のプロセスのスナップショットが作成されます。 スナップショットには一意の識別子が割り当てられ、例外にはその識別子を使用してスタンプされます。 FirstChanceException ハンドラーが戻った後、スローされた例外は通常どおり処理されます。 最終的に、例外は TrackException メソッドに再び到達し、スナップショット識別子と共に Application Insights に報告されます。

メイン プロセスは引き続き実行され、ユーザーへのトラフィックが処理されます。中断をほとんど発生しません。 その間、スナップショットは Snapshot Uploader プロセスに渡されます。 Snapshot Uploader からミニダンプが作成され、関連するシンボル (.pdb) ファイルと共に Application Insights にアップロードされます。

ヒント

  • プロセスのスナップショットは、実行中のプロセスの一時停止された複製です。
  • スナップショットの作成には約 10 から 20 ミリ秒かかります。
  • ThresholdForSnapshotting の既定値は 1 です。 これは最小値でもあります。 そのため、スナップショットが作成される前に、アプリは同じ例外を 2 回トリガーする必要があります。
  • Visual Studio でデバッグ中にスナップショットを生成する場合は、IsEnabledInDeveloperMode を true に設定します。
  • スナップショットの作成速度は SnapshotsPerTenMinutesLimit 設定によって制限されます。 既定では、10 分ごとに 1 つのスナップショットが上限です。
  • 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"、"ポータブル"、または "埋め込み" を使用することをお勧めします。

最適化されたビルド

場合によっては、JIT コンパイラによって適用される最適化のために、リリース ビルドでローカル変数を表示できないことがあります。 ただし、Azure App Services では、Snapshot Collector は収集計画の一部であるスロー方法を非最適化する可能性があります。

ヒント

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

次のステップ

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

Application Insights スナップショット デバッガーを有効にした後: