Отладочные моментальные снимки для исключений в приложениях .NETDebug snapshots on exceptions in .NET apps

При возникновении исключения, можно автоматически собирать отладочный моментальный снимок из работающего веб-приложения.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 отслеживает телеметрию исключений, поступающую из веб-приложения.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.

Вы можете просмотреть отладочные моментальные снимки на портале, чтобы изучить стек вызовов и проверить значения переменных в каждом кадре стека вызовов.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.

Отладочные моментальные снимки хранятся в течение 15 дней.Debug snapshots are stored for 15 days. Такая политика хранения задается для каждого приложения отдельно.This retention policy is set on a per-application basis. Если нужно изменить этот параметр, вы можете запросить изменения, открыв окно Службы Поддержки на портале Microsoft Azure.If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

Включение Snapshot Debugger Application Insights для приложенияEnable Application Insights Snapshot Debugger for your application

Коллекция моментальных снимков доступна для:Snapshot collection is available for:

  • .NET Framework и приложений ASP.NET выполняющихся с помощью .NET Framework 4.5 или более поздней версии..NET Framework and ASP.NET applications running .NET Framework 4.5 or later.
  • .NET Core 2.0 и приложений ASP.NET Core 2.0 под управлением Windows..NET Core 2.0 and ASP.NET Core 2.0 applications running on Windows.

Поддерживаются следующие среды:The following environments are supported:

Примечание

Клиентские приложения (например, WPF, Windows Forms или UWP) не поддерживаются.Client applications (for example, WPF, Windows Forms or UWP) are not supported.

Если вы включили Snapshot Debugger но не видите моментальные снимки, ознакомьтесь с нашим руководством по устранению неполадок.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. Перейдите к ресурсу Application Insights на портале Azure.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.

Просмотр моментальных снимков на портале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. Создание моментального снимка и его просмотр на портале может занять от 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.

Кнопка "Open Debug Snapshot" (Открыть отладочный моментальный снимок) для исключения

В представлении "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. Нажмите кнопку скачать моментальный снимок , чтобы скачать файл .diagsession, который можно открыть с помощью Visual Studio Enterprise.Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

  2. Чтобы открыть файл .diagsession, необходимо установить компонент Snapshot Debugger Visual Studio.To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. Компонент Snapshot Debugger является обязательным компонентом рабочей нагрузки ASP.net в Visual Studio и может быть выбран из списка отдельных компонентов в установщике 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 до Visual Studio 2017 версии 15,5, необходимо установить расширение из 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

Загруженный моментальный снимок содержит все файлы символов, найденные на сервере веб-приложения.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. Для приложений службы приложений не забудьте включить развертывание символов при публикации веб-приложения.For App Service apps, make sure to enable symbol deployment when you publish your web apps.

Как работают моментальные снимкиHow snapshots work

Сборщик моментальных снимков реализуется в виде обработчика телеметрии Application Insights.The Snapshot Collector is implemented as an Application Insights Telemetry Processor. При запуске приложения обработчик телеметрии как компонент сборщика моментальных снимков добавляется в конвейер телеметрии вашего приложения.When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. Каждый раз, когда приложение вызывает TrackException, сборщик моментальных снимков вычисляет идентификатор проблемы из типа вызываемого исключения и метод создания исключения.Each time your application calls TrackException, the Snapshot Collector computes a Problem ID from the type of exception being thrown and the throwing method. При этом значение счетчика увеличивается для соответствующего идентификатора проблемы.Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. Когда счетчик достигает значения ThresholdForSnapshotting, идентификатор проблемы добавляется в план сбора.When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

Сборщик Snapshot Collector также отслеживает исключения во время их создания, используя подписку на событие AppDomain.CurrentDomain.FirstChanceException.The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. При возникновении этого события идентификатор проблемы исключения вычисляется и сравнивается с идентификаторами в плане сбора.When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. Если обнаружено соответствие, создается моментальный снимок выполняющегося процесса.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. Тем временем моментальный снимок передается в процесс передачи моментальных снимков.Meanwhile, the snapshot is handed off to the Snapshot Uploader process. Отправитель моментальных снимков создает минидамп и передает его в Application Insights вместе с соответствующими PDB-файлами символов.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. Таким образом, прежде чем будет создан моментальный снимок, приложение должно вызвать то же исключение дважды.Therefore, your app has to trigger the same exception twice before a snapshot is created.
  • Задайте для IsEnabledInDeveloperMode значение true, если требуется создавать моментальные снимки во время отладки в Visual Studio.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. По умолчанию установлено ограничение — один моментальный снимок каждые десять минут.By default, the limit is one snapshot every ten minutes.
  • Можно отправлять не более 50 моментальных снимков в день.No more than 50 snapshots per day may be uploaded.

ОграниченияLimitations

Срок хранения данных по умолчанию составляет 15 дней.The default data retention period is 15 days. Для каждого экземпляра Application Insights максимально допустимое количество моментальных снимков 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. Выпуск 15.2 (или выше) приложения Visual Studio 2017 по умолчанию публикует символы для сборок выпуска при публикации в службе приложений.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 и других типов служб файлы символов должны находиться в одной папке с 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», «Portable» или «Embedded».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 сборщик моментальных снимков может деоптимизировать методы создания исключений, которые являются частью плана сбора.However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

Совет

Установите расширение сайта Application Insights в службе приложений для получения поддержки деоптимизации.Install the Application Insights Site Extension in your App Service to get deoptimization support.

Дальнейшие действияNext steps

Включите Snapshot Debugger Application Insights для приложения:Enable Application Insights Snapshot Debugger for your application:

Кроме Application Insights Snapshot Debugger:Beyond Application Insights Snapshot Debugger: