.NET アプリでの例外でのデバッグ スナップショットDebug snapshots on exceptions in .NET apps

例外が発生したとき、実行中の Web アプリケーションからデバッグ スナップショットを自動的に収集できます。When an exception occurs, you can automatically collect a debug snapshot from your live web application. スナップショットには、例外がスローされたときのソース コードと変数の状態が表示されます。The snapshot shows the state of source code and variables at the moment the exception was thrown. Azure Application Insights のスナップショット デバッガー (プレビュー) により、Web アプリの例外テレメトリが監視されます。The Snapshot Debugger (preview) in Azure Application Insights monitors exception telemetry from your web app. 運用環境の問題の診断に必要な情報を入手できるように、スローされる上位の例外に関するスナップショットが収集されます。It collects snapshots on your top-throwing exceptions so that you have the information you need to diagnose issues in production. スナップショット コレクター NuGet パッケージをアプリケーションに含め、必要に応じて、ApplicationInsights.config にコレクション パラメーターを構成します。スナップショットが、Application Insights ポータルの例外に表示されます。Include the Snapshot collector NuGet package in your application, and optionally configure collection parameters in ApplicationInsights.config. Snapshots appear on exceptions in the Application Insights portal.

ポータルで [Debug Snapshots (デバッグ スナップショット)] を表示して、コール スタックを表示し、各呼び出しスタック フレームで変数を確認できます。You can view debug snapshots in the portal to see the call stack and inspect variables at each call stack frame. ソース コードによるデバッグ エクスペリエンスをさらに向上させるには、Visual Studio 2019 Enterprise でスナップショットを開きます。To get a more powerful debugging experience with source code, open snapshots with Visual Studio 2019 Enterprise. Visual Studio では、例外を待たずにスナップポイントを設定し、対話形式でスナップショットを取得できます。In Visual Studio, you can also set Snappoints to interactively take snapshots without waiting for an exception.

デバッグ スナップショットは 7 日間格納されます。Debug snapshots are stored for seven days. この保持ポリシーは、アプリケーションごとに設定されます。This retention policy is set on a per-application basis. この値を増やす必要がある場合は、Azure portal でサポート ケースを開くことによって増加を要求できます。If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

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

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

  • .NET Framework 4.5 以降を実行している .NET Framework アプリケーションと ASP.NET アプリケーション。.NET Framework and ASP.NET applications running .NET Framework 4.5 or later.
  • Windows 上で動作している .NET core 2.0 アプリケーションと ASP.NET Core 2.0 アプリケーション。.NET Core 2.0 and ASP.NET Core 2.0 applications running on Windows.

次の環境がサポートされています。The following environments are supported:

注意

クライアント アプリケーション (たとえば、WPF、Windows フォーム、または UWP) はサポートされません。Client applications (for example, WPF, Windows Forms or UWP) are not supported.

スナップショット デバッガーを有効にしたのにスナップショットが表示されない場合は、「トラブルシューティング ガイド」を参照してください。If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.

アクセス許可を付与するGrant permissions

スナップショットへのアクセスは、ロールベースのアクセス制御 (RBAC) によって保護されます。Access to snapshots is protected by role-based access control (RBAC). スナップショットを検査するユーザーは、最初にサブスクリプション所有者によって必要なロールに追加される必要があります。To inspect a snapshot, you must first be added to the necessary role by a subscription owner.

注意

所有者と共同作成者には、このロールは自動的に割り当てられません。Owners and contributors do not automatically have this role. 所有者や共同作成者がスナップショットを見る場合は、自分自身をロールに追加する必要があります。If they want to view snapshots, they must add themselves to the role.

サブスクリプション所有者は、スナップショットを検査する予定のユーザーに Application Insights Snapshot Debugger のロールを割り当てる必要があります。Subscription owners should assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. このロールは、Application Insights のターゲット リソース、リソース グループ、またはサブスクリプションに関するサブスクリプション所有者が、個々のユーザーまたはグループに割り当てることができます。This role can be assigned to individual users or groups by subscription owners for the target Application Insights resource or its resource group or subscription.

  1. Azure Portal で Application Insights のリソースを参照します。Navigate to the Application Insights resource in the Azure portal.
  2. [アクセス制御 (IAM)] をクリックします。Click Access control (IAM).
  3. [+ ロールの割り当ての追加] ボタンをクリックします。Click the +Add role assignment button.
  4. [ロール] ボックスの一覧の [Application Insights スナップショット デバッガー] を選択します。Select Application Insights Snapshot Debugger from the Roles drop-down list.
  5. 追加するユーザーの名前を探して入力します。Search for and enter a name for the user to add.
  6. [保存] ボタンをクリックして、ユーザーをロールに追加します。Click the Save button to add the user to the role.

重要

スナップショットは、変数とパラメーターの値に個人情報などの機密情報を含んでいる可能性があります。Snapshots can potentially contain personal and other sensitive information in variable and parameter values.

Portal でスナップショットを表示するView Snapshots in the Portal

アプリケーションで例外が発生してスナップショットが作成されたら、スナップショットを表示することができます。After an exception has occurred in your application and a snapshot has been created, you should have snapshots to view. 例外が発生してから、スナップショットの準備ができて Portal から表示できるまでには、5 分から 10 分かかります。It can take 5 to 10 minutes from an exception occurring to a snapshot ready and viewable from the portal. スナップショットを表示するには、 [失敗] ウィンドウで、 [操作] タブを表示しているときは [操作] ボタンを選択し、 [例外] タブを表示しているときには [例外] ボタンを選択します。To view snapshots, in the Failure pane, select the Operations button when viewing the Operations tab, or select the Exceptions button when viewing the Exceptions tab:

[失敗] ページ

右側のウィンドウで操作または例外を選択して、 [エンドツーエンド トランザクション詳細] ウィンドウを開き、次に例外イベントを選択します。Select an operation or exception in the right pane to open the End-to-End Transaction Details pane, then select the exception event. 特定の例外のスナップショットが使用可能な場合、例外の詳細と共に右側のウィンドウに [デバッグ スナップショットを開く] ボタンが表示されます。If a snapshot is available for the given exception, an Open Debug Snapshot button appears on the right pane with details for the exception.

例外の [Debug Snapshot (デバッグ スナップショット)] ボタンを開く

デバッグ スナップショット ビューには、コール スタックと変数ウィンドウが表示されます。In the Debug Snapshot view, you see a call stack and a variables pane. コール スタック ウィンドウでコール スタックのフレームを選択すると、変数ウィンドウでその関数呼び出しのローカル変数とパラメーターを表示できます。When you select frames of the call stack in the call stack pane, you can view local variables and parameters for that function call in the variables pane.

ポータルでのデバッグ スナップショットの表示

スナップショットには機密情報が含まれている可能性があるため、既定では非表示になっています。Snapshots might include sensitive information, and by default they aren't viewable. スナップショットを表示するには、Application Insights Snapshot Debugger のロールを割り当てられている必要があります。To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

Visual Studio 2017 Enterprise 以上でスナップショットを表示するView Snapshots in Visual Studio 2017 Enterprise or above

  1. [Download Snapshot](スナップショットのダウンロード) をクリックして .diagsession ファイルをダウンロードします。このファイルは Visual Studio Enterprise で開くことができます。Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

  2. .diagsession ファイルを開くには、スナップショット デバッガーの Visual Studio コンポーネントがインストールされている必要があります。To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. スナップショット デバッガー コンポーネントは、Visual Studio の ASP.net ワークロードに必要なコンポーネントです。これは、Visual Studio インストーラーの個々のコンポーネント リストから選択することができます。The Snapshot Debugger component is a required component of the ASP.net workload in Visual Studio and can be selected from the Individual Component list in the Visual Studio installer. Visual Studio 2017 バージョン 15.5 より前のバージョンの Visual Studio を使用している場合、拡張機能は Visual Studio Marketplace からインストールする必要があります。If you are using a version of Visual Studio prior to Visual Studio 2017 version 15.5, you will need to install the extension from the Visual Studio Marketplace.

  3. スナップショット ファイルを開くと、Visual Studio の[ミニダンプ デバッグ] ページが表示されます。After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. [Debug Managed Code](マネージド コードをデバッグする) をクリックして、スナップショットのデバッグを開始します。Click Debug Managed Code to start debugging the snapshot. 例外がスローされたコード行がスナップショットに表示され、プロセスの現在の状態をデバッグできます。The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

    Visual Studio でのデバッグ スナップショットの表示

ダウンロードしたスナップショットには、Web アプリケーション サーバーで検出されたすべてのシンボル ファイルが含まれます。The downloaded snapshot includes any symbol files that were found on your web application server. これらのシンボル ファイルは、スナップショット データをソース コードと関連付けるために必要です。These symbol files are required to associate snapshot data with source code. App Service アプリの場合は、Web アプリを公開するときにシンボル デプロイを有効にしてください。For App Service apps, make sure to enable symbol deployment when you publish your web apps.

スナップショットのしくみHow snapshots work

Snapshot Collector は、Application Insights Telemetry Processor として実装されています。The Snapshot Collector is implemented as an Application Insights Telemetry Processor. アプリケーションが実行されると、Snapshot Collector Telemetry Processor がアプリケーションのテレメトリ パイプラインに追加されます。When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. アプリケーションが TrackException を呼び出すたびに、Snapshot Collector はスローされる例外の種類とスロー方法から問題 ID を計算します。Each time your application calls TrackException, the Snapshot Collector computes a Problem ID from the type of exception being thrown and the throwing method. アプリケーションが TrackException を呼び出すたびに、該当する問題 ID のカウンターが増分されます。Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. カウンターが ThresholdForSnapshotting 値に達すると、問題 ID が収集計画に追加されます。When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

AppDomain.CurrentDomain.FirstChanceException イベントにサブスクライブすることで例外がスローされるので、Snapshot Collector は例外も監視します。The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. そのイベントが発生すると、例外の問題 ID が計算され、収集計画の問題 ID と比較されます。When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. 一致する ID があれば、実行中のプロセスのスナップショットが作成されます。If there's a match, then a snapshot of the running process is created. スナップショットには一意の識別子が割り当てられ、例外にはその識別子を使用してスタンプされます。The snapshot is assigned a unique identifier and the exception is stamped with that identifier. FirstChanceException ハンドラーが戻った後、スローされた例外は通常どおり処理されます。After the FirstChanceException handler returns, the thrown exception is processed as normal. 最終的に、例外は TrackException メソッドに再び到達し、スナップショット識別子と共に Application Insights に報告されます。Eventually, the exception reaches the TrackException method again where it, along with the snapshot identifier, is reported to Application Insights.

メイン プロセスは引き続き実行され、ユーザーへのトラフィックが処理されます。中断をほとんど発生しません。The main process continues to run and serve traffic to users with little interruption. その間、スナップショットは Snapshot Uploader プロセスに渡されます。Meanwhile, the snapshot is handed off to the Snapshot Uploader process. Snapshot Uploader からミニダンプが作成され、関連するシンボル (.pdb) ファイルと共に Application Insights にアップロードされます。The Snapshot Uploader creates a minidump and uploads it to Application Insights along with any relevant symbol (.pdb) files.

ヒント

  • プロセスのスナップショットは、実行中のプロセスの一時停止された複製です。A process snapshot is a suspended clone of the running process.
  • スナップショットの作成には約 10 から 20 ミリ秒かかります。Creating the snapshot takes about 10 to 20 milliseconds.
  • ThresholdForSnapshotting の既定値は 1 です。The default value for ThresholdForSnapshotting is 1. これは最小値でもあります。This is also the minimum value. そのため、スナップショットが作成される前に、アプリは同じ例外を 2 回トリガーする必要があります。Therefore, your app has to trigger the same exception twice before a snapshot is created.
  • Visual Studio でデバッグ中にスナップショットを生成する場合は、IsEnabledInDeveloperMode を true に設定します。Set IsEnabledInDeveloperMode to true if you want to generate snapshots while debugging in Visual Studio.
  • スナップショットの作成速度は SnapshotsPerTenMinutesLimit 設定によって制限されます。The snapshot creation rate is limited by the SnapshotsPerTenMinutesLimit setting. 既定では、10 分ごとに 1 つのスナップショットが上限です。By default, the limit is one snapshot every ten minutes.
  • 1 日あたり 50 枚を超えるスナップショットをアップロードすることはできません。No more than 50 snapshots per day may be uploaded.

制限事項Limitations

既定のデータ保有期間は 15 日間です。The default data retention period is 15 days. Application Insights のインスタンスごとに、1 日あたり最大 50 個のスナップショットが許可されます。For each Application Insights instance, a maximum number of 50 snapshots is allowed per day.

シンボルの公開Publish symbols

スナップショット デバッガーでは、Visual Studio で変数をデコードし、デバッグ エクスペリエンスを提供するために、運用サーバーにシンボル ファイルが必要です。The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. Visual Studio 2017 のバージョン 15.2 (またはそれ以上) では、App Service に公開する際に、既定でリリース ビルドのシンボルを公開します。Version 15.2 (or above) of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. 以前のバージョンでは、シンボルがリリース モードで公開されるように、発行プロファイルの .pubxml ファイルに次の行を追加する必要があります。In prior versions, you need to add the following line to your publish profile .pubxml file so that symbols are published in release mode:

    <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

Azure Compute や他の種類の場合、シンボル ファイルがメイン アプリケーション .dll (通常は wwwroot/bin) の同じフォルダーにあるか、現在のパスで使用できることを確認してください。For Azure Compute and other types, make sure that the symbol files are in the same folder of the main application .dll (typically, wwwroot/bin) or are available on the current path.

注意

使用できるさまざまなシンボル オプションについて詳しくは、Visual Studio のドキュメントをご覧ください。For more information on the different symbol options that are available consult the Visual Studio documentation. 最良の結果を得るために、"Full"、"ポータブル"、または "埋め込み" を使用することをお勧めします。For best results, we recommend using “Full”, “Portable” or “Embedded”.

最適化されたビルドOptimized builds

場合によっては、JIT コンパイラによって適用される最適化のために、リリース ビルドでローカル変数を表示できないことがあります。In some cases, local variables can't be viewed in release builds because of optimizations that are applied by the JIT compiler. ただし、Azure App Services では、Snapshot Collector は収集計画の一部であるスロー方法を非最適化する可能性があります。However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

ヒント

Application Insights サイト拡張機能を App Service にインストールして、非最適化のサポートを得ます。Install the Application Insights Site Extension in your App Service to get deoptimization support.

次の手順Next steps

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

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