Depurar instantáneas cuando se producen excepciones en aplicaciones de .NETDebug snapshots on exceptions in .NET apps

Cuando se produce una excepción, puede recopilar automáticamente una instantánea de depuración desde la aplicación web activa.When an exception occurs, you can automatically collect a debug snapshot from your live web application. La instantánea muestra el estado del código fuente y las variables en el momento en que se produjo la excepción.The snapshot shows the state of source code and variables at the moment the exception was thrown. El depurador de instantáneas (versión preliminar) de Azure Application Insights supervisa la telemetría de excepciones de su aplicación web.The Snapshot Debugger (preview) in Azure Application Insights monitors exception telemetry from your web app. Recopila instantáneas de las excepciones más importantes con el fin de que tenga la información necesaria para diagnosticar problemas en producción.It collects snapshots on your top-throwing exceptions so that you have the information you need to diagnose issues in production. Incluya el paquete NuGet del recopilador de instantáneas en la aplicación y, opcionalmente, configure los parámetros de recopilación en ApplicationInsights.config. Las instantáneas aparecen en excepciones en el portal de 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.

Puede ver las instantáneas de depuración en el portal para examinar la pila de llamadas e inspeccionar las variables en cada marco de pila de llamadas.You can view debug snapshots in the portal to see the call stack and inspect variables at each call stack frame. Para obtener una experiencia de depuración más eficaz con el código fuente, abra las instantáneas con Visual Studio 2019 Enterprise.To get a more powerful debugging experience with source code, open snapshots with Visual Studio 2019 Enterprise. En Visual Studio también puede establecer puntos de acoplamiento para tomar instantáneas de forma interactiva sin tener que esperar una excepción.In Visual Studio, you can also set Snappoints to interactively take snapshots without waiting for an exception.

Las instantáneas de depuración se guardan durante siete días.Debug snapshots are stored for seven days. Esta directiva de retención se establece para cada aplicación.This retention policy is set on a per-application basis. Si necesita aumentar este valor, puede solicitar un aumento abriendo una incidencia de soporte técnico en Azure Portal.If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

Habilitación de Snapshot Debugger de Application Insights para la aplicaciónEnable Application Insights Snapshot Debugger for your application

La recopilación de instantáneas está disponible para:Snapshot collection is available for:

  • Aplicaciones de .NET Framework y ASP.NET que ejecuten .NET Framework 4.5 o posterior..NET Framework and ASP.NET applications running .NET Framework 4.5 or later.
  • Aplicaciones de .NET Core 2.0 y ASP.NET Core 2.0 que se ejecuten en Windows..NET Core 2.0 and ASP.NET Core 2.0 applications running on Windows.

Se admiten los siguientes entornos:The following environments are supported:

Nota

No se admiten las aplicaciones cliente (por ejemplo, WPF, Windows Forms o UWP).Client applications (for example, WPF, Windows Forms or UWP) are not supported.

Si ha habilitado Snapshot Debugger, pero no ve las instantáneas, consulte nuestra Guía de solución de problemas.If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.

Concesión de permisosGrant permissions

El acceso a las instantáneas está protegido por el control de acceso basado en rol (RBAC).Access to snapshots is protected by role-based access control (RBAC). Para poder inspeccionar una instantánea, el propietario de la suscripción debe agregarle primero al rol necesario.To inspect a snapshot, you must first be added to the necessary role by a subscription owner.

Nota

Los propietarios y los colaboradores no tienen automáticamente este rol.Owners and contributors do not automatically have this role. Si desean ver las instantáneas, se deben agregar a sí mismos al rol.If they want to view snapshots, they must add themselves to the role.

Los propietarios de la suscripción deben asignar el rol Application Insights Snapshot Debugger a los usuarios que van a inspeccionar las instantáneas.Subscription owners should assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. Los propietarios de suscripción pueden asignar este rol a usuarios individuales o grupos en el recurso de Application Insights de destino o en su grupo de recursos o suscripción.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. Vaya al recurso de Application Insights en Azure Portal.Navigate to the Application Insights resource in the Azure portal.
  2. Haga clic en Control de acceso (IAM) .Click Access control (IAM).
  3. Haga clic en el botón +Add role assignment (+ Agregar asignación de roles) botón.Click the +Add role assignment button.
  4. Seleccione Application Insights Snapshot Debugger en la lista desplegable Roles.Select Application Insights Snapshot Debugger from the Roles drop-down list.
  5. Busque el usuario que quiere agregar y escriba un nombre.Search for and enter a name for the user to add.
  6. Haga clic en el botón Guardar para agregar el usuario al rol.Click the Save button to add the user to the role.

Importante

Las instantáneas pueden contener información personal y otra información confidencial en valores de variables y parámetros.Snapshots can potentially contain personal and other sensitive information in variable and parameter values.

Visualización de instantáneas en el portalView Snapshots in the Portal

Una vez que se haya producido una excepción en la aplicación y se haya creado una instantánea, debería tener instantáneas para visualizar.After an exception has occurred in your application and a snapshot has been created, you should have snapshots to view. Pueden transcurrir entre cinco y diez minutos desde que se produce una excepción hasta que una instantánea está lista y puede visualizarse desde el portal.It can take 5 to 10 minutes from an exception occurring to a snapshot ready and viewable from the portal. Para visualizar las instantáneas, en el panel Error, seleccione el botón Operaciones al ver la pestaña Operaciones, o bien seleccione el botón Excepciones al ver la pestaña Excepciones: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:

Página de errores

Seleccione una operación o una excepción en el panel derecho para abrir el panel Detalles de la transacción completa y, luego, seleccione el evento de excepción.Select an operation or exception in the right pane to open the End-to-End Transaction Details pane, then select the exception event. Si una instantánea está disponible para una excepción determinada, se mostrará el botón Abrir instantánea de depuración en el panel derecho con detalles de la excepción.If a snapshot is available for the given exception, an Open Debug Snapshot button appears on the right pane with details for the exception.

Botón Abrir instantánea de depuración de la excepción

En la vista de depuración instantánea, verá una pila de llamadas y un panel de variables.In the Debug Snapshot view, you see a call stack and a variables pane. Al seleccionar marcos de la pila de llamadas en el panel de la pila de llamadas, podrá ver las variables locales y los parámetros para esa llamada de función en el panel de variables.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.

Visualización de la instantánea de depuración en el portal

Las instantáneas pueden incluir información confidencial y, de manera predeterminada, no están visibles.Snapshots might include sensitive information, and by default they aren't viewable. Para ver las instantáneas, debe tener asignado el rol Application Insights Snapshot Debugger.To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

Visualización de instantáneas en Visual Studio 2017 Enterprise o versiones posterioresView Snapshots in Visual Studio 2017 Enterprise or above

  1. Haga clic en el botón Descargar la instantánea para descargar un archivo .diagsession, que puede abrirse en Visual Studio Enterprise.Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

  2. Para abrir el archivo .diagsession, debe tener instalado el componente Snapshot Debugger de Visual Studio.To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. El componente Snapshot Debugger es un componente obligatorio de la carga de trabajo de ASP.NET en Visual Studio y se puede seleccionar de la lista de componentes individuales en el instalador de 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. Si usa una versión de Visual Studio anterior a Visual Studio 2017, versión 15.5, deberá instalar la extensión desde 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. Después de abrir el archivo de instantánea, aparece la página de depuración de minivolcado de Visual Studio.After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. Haga clic en Depurar código administrado para empezar a depurar la instantánea.Click Debug Managed Code to start debugging the snapshot. La instantánea se abre en la línea de código donde se produjo la excepción para que pueda depurar el estado actual del proceso.The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

    Visualización de la instantánea de depuración en Visual Studio

La instantánea descargada incluye los archivos de símbolos que se encontraron en el servidor de aplicaciones web.The downloaded snapshot includes any symbol files that were found on your web application server. Estos archivos de símbolos son necesarios para asociar los datos de instantáneas con el código fuente.These symbol files are required to associate snapshot data with source code. Para las aplicaciones de App Service, asegúrese de habilitar la implementación de símbolos cuando publique las aplicaciones web.For App Service apps, make sure to enable symbol deployment when you publish your web apps.

Funcionamiento de las instantáneasHow snapshots work

Snapshot Collector se implementa como un procesador de telemetría de Application Insights.The Snapshot Collector is implemented as an Application Insights Telemetry Processor. Al ejecutar la aplicación, el procesador de telemetría de Snapshot Collector se agrega a la canalización de telemetría de la aplicación.When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. Cada vez que la aplicación llama a TrackException, Snapshot Collector calcula un identificador del problema del tipo de excepción producida y el método de lanzamiento.Each time your application calls TrackException, the Snapshot Collector computes a Problem ID from the type of exception being thrown and the throwing method. Cada vez que la aplicación llama a TrackException, se incrementa un contador para el identificador del problema adecuado.Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. Cuando el contador alcanza el valor ThresholdForSnapshotting, el identificador del problema se agrega a un plan de recolección.When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

Snapshot Collector también supervisa las excepciones a medida que se producen si se suscribe al evento AppDomain.CurrentDomain.FirstChanceException.The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. Cuando ese evento se desencadena, el identificador del problema de la excepción se calcula y se compara con los identificadores del problema del plan de recolección.When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. Si se encuentra una coincidencia, se crea una instantánea del proceso en ejecución.If there's a match, then a snapshot of the running process is created. Se asigna un identificador único a la instantánea y la excepción se marca con ese identificador.The snapshot is assigned a unique identifier and the exception is stamped with that identifier. Tras la devolución del controlador de FirstChanceException, la excepción producida se procesa con normalidad.After the FirstChanceException handler returns, the thrown exception is processed as normal. Finalmente, la excepción alcanza el método TrackException de nuevo que, junto con el identificador de instantáneas, se notifica a Application Insights.Eventually, the exception reaches the TrackException method again where it, along with the snapshot identifier, is reported to Application Insights.

El proceso principal sigue ejecutándose y ofrece tráfico a los usuarios con poca interrupción.The main process continues to run and serve traffic to users with little interruption. Mientras tanto, la instantánea se entrega al proceso del cargador de instantáneas.Meanwhile, the snapshot is handed off to the Snapshot Uploader process. El cargador de instantáneas crea un minivolcado y lo carga en Application Insights junto con los archivos de símbolos (.pdb) pertinentes.The Snapshot Uploader creates a minidump and uploads it to Application Insights along with any relevant symbol (.pdb) files.

Sugerencia

  • Una instantánea de proceso es un clon suspendido del proceso en ejecución.A process snapshot is a suspended clone of the running process.
  • La creación de la instantánea tarda aproximadamente de 10 a 20 milisegundos.Creating the snapshot takes about 10 to 20 milliseconds.
  • El valor predeterminado de ThresholdForSnapshotting es 1.The default value for ThresholdForSnapshotting is 1. También es el valor mínimo.This is also the minimum value. Por lo tanto, la aplicación debe desencadenar la misma excepción dos veces antes de crear una instantánea.Therefore, your app has to trigger the same exception twice before a snapshot is created.
  • Establezca IsEnabledInDeveloperMode en true si quiere generar instantáneas durante la depuración en Visual Studio.Set IsEnabledInDeveloperMode to true if you want to generate snapshots while debugging in Visual Studio.
  • La velocidad de creación de instantáneas está limitada por la configuración de SnapshotsPerTenMinutesLimit.The snapshot creation rate is limited by the SnapshotsPerTenMinutesLimit setting. De manera predeterminada, el límite es una instantánea cada diez minutos.By default, the limit is one snapshot every ten minutes.
  • No se pueden cargar más de 50 instantáneas al día.No more than 50 snapshots per day may be uploaded.

LimitacionesLimitations

El período de retención de datos predeterminado es de 15 días.The default data retention period is 15 days. Para cada instancia de Application Insights, se permite un número máximo de 50 instantáneas por día.For each Application Insights instance, a maximum number of 50 snapshots is allowed per day.

Publicación de símbolosPublish symbols

El Depurador de instantáneas requiere que los archivos de símbolos estén presentes en el servidor de producción para descodificar variables y proporcionar una experiencia de depuración en Visual Studio.The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. La versión 15.2 (o superior) de Visual Studio 2017 publica símbolos de compilaciones de versión de forma predeterminada al publicar en App Service.Version 15.2 (or above) of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. En las versiones anteriores, tiene que agregar la siguiente línea al archivo .pubxml de su perfil de publicación para que los símbolos se publiquen en modo de versión: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>

Para Azure Compute y otros tipos, asegúrese de que los archivos de símbolos están en la misma carpeta del archivo .dll principal de la aplicación (normalmente, wwwroot/bin), o que están disponibles en la ruta de acceso actual.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.

Nota

Para más información acerca de las diferentes opciones de símbolos disponibles, consulte la , documentación de Visual Studio.For more information on the different symbol options that are available consult the Visual Studio documentation. Para obtener los mejores resultados posible, se recomienda usar "Full", "Portable" o "Embedded".For best results, we recommend using “Full”, “Portable” or “Embedded”.

Compilaciones optimizadasOptimized builds

En algunos casos, las variables locales no se pueden ver en las compilaciones de versión debido a las optimizaciones que aplica el compilador JIT.In some cases, local variables can't be viewed in release builds because of optimizations that are applied by the JIT compiler. Sin embargo, en Azure App Services, Snapshot Collector puede invalidar la optimización de los métodos de lanzamiento que forman parte del plan de recolección.However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

Sugerencia

Instale la extensión de sitio de Application Insights en su App Service para obtener soporte técnico para la invalidación de optimizaciones.Install the Application Insights Site Extension in your App Service to get deoptimization support.

Pasos siguientesNext steps

Habilitación de Snapshot Debugger de Application Insights para la aplicación:Enable Application Insights Snapshot Debugger for your application:

Más allá de Snapshot Debugger de Application Insights:Beyond Application Insights Snapshot Debugger: