Depuración de excepciones en aplicaciones .NET mediante Snapshot Debugger

  • Artículo

Con Snapshot Debugger, puede recopilar automáticamente una instantánea de depuración cuando se produce una excepción en la aplicación .NET activa. Las instantáneas de depuración recopiladas muestran el estado del código fuente y las variables en el momento en que se produjo la excepción.

Snapshot Debugger en Application Insights:

  • Supervisa los registros generados por el sistema desde la aplicación web.
  • Recopila instantáneas en las excepciones de inicio superior.
  • Proporciona información necesaria para diagnosticar problemas en entornos de producción.

Obtenga más información sobre los procesos Snapshot Debugger e Snapshot Uploader.

Aplicaciones y entornos admitidos

En esta sección se enumeran las aplicaciones y entornos que se admiten.

APLICACIONES

La recopilación de instantáneas está disponible para:

Entornos

Se admiten los siguientes entornos:

Nota

No se admiten las aplicaciones cliente (por ejemplo, WPF, Windows Forms o UWP).

Requisitos previos para usar Snapshot Debugger

Paquetes y configuraciones

Permisos

Funcionamiento de Snapshot Debugger

Snapshot Debugger se implementa como un procesador de telemetría de Application Insights. Al ejecutar la aplicación, el procesador de telemetría de Snapshot Debugger se agrega a la canalización de registros generados por el sistema de la aplicación.

Importante

Las instantáneas pueden contener datos personales u otra información confidencial en los valores de las variables y parámetros. Los datos de las instantáneas se almacenan en la misma región que el recurso de Application Insights.

Proceso del Snapshot Debugger

El proceso del Snapshot Debugger se inicia y termina con el método TrackException. Una instantánea de proceso es un clon suspendido del proceso en ejecución, de modo que los usuarios experimenten una interrupción mínima o nula.

  1. La aplicación inicia el TrackException.

  2. Snapshot Debugger supervisa las excepciones a medida que se inician al suscribirse al evento AppDomain.CurrentDomain.FirstChanceException.

  3. Se incrementa un contador para el identificador del problema.

    • Cuando el contador alcanza el valor ThresholdForSnapshotting, el identificador del problema se agrega a un plan de recolección.

    Nota:

    El ThresholdForSnapshotting valor mínimo predeterminado es 1. Con este valor, la aplicación debe desencadenar la misma excepción dos veces antes de crear una instantánea.

  4. El identificador de problema del evento de excepción se calcula y se compara con los identificadores de problema del plan de recopilación.

  5. Si hay una coincidencia entre los id. de los problemas, se crea una instantánea del proceso en ejecución.

    • Se asigna un identificador único a la instantánea y la excepción se marca con ese identificador.

    Nota:

    La velocidad de creación de instantáneas está limitada por la configuración de SnapshotsPerTenMinutesLimit. De manera predeterminada, el límite es una instantánea cada 10 minutos.

  6. Tras la devolución del controlador FirstChanceException, la excepción producida se procesa con normalidad.

  7. La excepción vuelve a alcanzar el método TrackException y se notifica a Application Insights, junto con el identificador de instantánea.

Nota:

Establezca IsEnabledInDeveloperMode en true si quiere generar instantáneas durante la depuración en Visual Studio.

Proceso del cargador de instantáneas

Aunque el proceso de Snapshot Debugger continúa ejecutándose y atendiendo el tráfico a los usuarios con poca interrupción, la instantánea se entrega al proceso del cargador de instantáneas. El cargador de instantáneas:

  1. Crea un minivolcado.

  2. Carga el minivolcado en Application Insights, junto con cualquier símbolo relevante (archivos .pdb).

Nota:

No se pueden cargar más de 50 instantáneas al día.

Si ha habilitado Snapshot Debugger, pero no ve las instantáneas, consulte la Guía de solución de problemas.

Limitaciones

En esta sección se describen las limitaciones de Snapshot Debugger.

  • Retención de datos

    Las instantáneas de depuración se guardan durante 15 días. Esta directiva de retención de datos predeterminadas se establece para cada aplicación. Si necesita aumentar este valor, puede solicitar un aumento abriendo una incidencia de soporte técnico en Azure Portal. Para cada instancia de Application Insights, se permite un número máximo de 50 instantáneas al día.

  • Publicación de símbolos

    Snapshot Debugger requiere archivos de símbolos en el servidor de producción para:

    • Descodificar variables
    • Proporcionar una experiencia de depuración en Visual Studio

    De forma predeterminada, Visual Studio 2017 versiones 15.2+ publica símbolos para compilaciones de lanzamiento cuando publica en 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:

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    Para Azure Compute y otros tipos, asegúrese de que los archivos de símbolos son:

    • En la misma carpeta de la aplicación principal .dll (normalmente, wwwroot/bin) o
    • Disponible en la ruta de acceso actual.

    Para más información sobre las diferentes opciones de símbolos disponibles, consulte la documentación de Visual Studio. Para obtener los mejores resultados, se recomienda usar Full, Portable o Embedded.

  • Compilaciones optimizadas

    En algunos casos, las variables locales no pueden visualizarse en las compilaciones de lanzamiento debido a las optimizaciones aplicadas por el compilador JIT.

    Sin embargo, en App Service, el Snapshot Debugger puede invalidar la optimización de los métodos de lanzamiento que forman parte de su plan de recopilación.

    Sugerencia

    Instale la extensión de sitio de Application Insights en su instancia de App Service para obtener soporte técnico para la invalidación de optimizaciones.

Pasos siguientes

Habilitar Snapshot Debugger de Application Insights para la aplicación:

Notas de la versión Microsoft.ApplicationInsights.SnapshotCollector

Esta sección contiene las notas de la versión para el paquete NuGet Microsoft.ApplicationInsights.SnapshotCollector para aplicaciones de .NET, que es utilizado por Snapshot Debugger de Application Insights.

Más información sobre Snapshot Debugger de Application Insights para aplicaciones .NET.

Para notificar informes de errores y comentarios, abra un problema en GitHub.

Nota:

El 31 de marzo de 2025 finalizará la compatibilidad con la ingesta de claves de instrumentación. La ingesta de claves de instrumentación seguirá funcionando, pero la característica ya no recibirá actualizaciones ni soporte técnico. Transición a las cadenas de conexión para aprovechar las nuevas funcionalidades.

1.4.6

Una versión puntual para abordar una regresión al usar aplicaciones de .NET 8.

Corrección de errores

  • No se realiza un seguimiento correcto de las excepciones producidas a partir de métodos generados dinámicamente (por ejemplo, árboles de expresión compilados) en .NET 8. Fijo.

1.4.5

Una versión puntual para solucionar un error notificado por el usuario.

Corrección de errores

  • Se ha corregido AccessViolationException al leer algunos archivos PDB.

Cambios

  • Se ha agregado un archivo ReadMe al paquete NuGet.
  • Se ha actualizado msdia140.dll.

1.4.4

Una versión puntual para solucionar errores notificados por el usuario.

Corrección de errores

Cambios

  • Mensajes de error del examen PDB reducidos de Error a Advertencia.
  • Se ha actualizado msdia140.dll.
  • Evite realizar una conexión de servicio si el depurador está deshabilitado a través de la configuración de la extensión de sitio.

1.4.3

Una versión puntual para solucionar errores notificados por el usuario.

Corrección de errores

1.4.2

Una versión puntual para solucionar un error notificado por el usuario.

Corrección de errores

Corregido ArgumentException: los delegados deben ser del mismo tipo.

1.4.1

Una versión puntual para revertir un cambio importante introducido en la versión 1.4.0.

Corrección de errores

Corregido Método no encontrado en WebJobs.

1.4.0

Se han abordado varias mejoras y se ha agregado compatibilidad con la autenticación de Microsoft Entra para la ingesta de Application Insights.

Cambios

  • Tamaño reducido del paquete de Snapshot Collector en un 60 % de 10,34 MB a 4,11 MB.
  • Netstandard2.0 se ha establecido como destino solo en Snapshot Collector.
  • Se ha actualizado la dependencia del SDK de Application Insights a la versión 2.15.0.
  • Se ha agregado de nuevo MinidumpWithThreadInfo al escribir volcados.
  • Se agrega CompatibilityVersion para mejorar la sincronización entre el agente de Snapshot Collector y Snapshot Uploader en los cambios importantes.
  • Se ha cambiado el algoritmo de nomenclatura SnapshotUploader LogFile para evitar demasiadas operaciones de E/S de archivos en App Service.
  • Se han agregado pid, role name y process start time a los metadatos de los blobs cargados.
  • Se usa System.Diagnostics.Process en Snapshot Collector y Snapshot Uploader.

Nuevas características

Se ha agregado la autenticación de Microsoft Entra a SnapshotCollector. Para más información sobre la autenticación de Microsoft Entra en Application Insights, consulte Autenticación de Microsoft Entra para Application Insights.

1.3.7.5

Una versión puntual para retroimportar una corrección de 1.4.0-pre.

Corrección de errores

Corregido ObjectDisposedException en el apagado.

1.3.7.4

Una versión puntual para solucionar un problema detectado en la prueba del escenario para adjuntar sin código de App Service.

Cambios

El objetivo netcoreapp3.0 depende ahora de Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (antes >= 2.1.2).

1.3.7.3

Versión de carácter puntual para abordar un par de problemas de gran impacto.

Corrección de errores

  • Se ha corregido la detección de PDB en la carpeta wwwroot/bin, que se interrumpió al cambiar el algoritmo de búsqueda de símbolos en la versión 1.3.6.
  • Corregida una ExtractWasCalledMultipleTimesException con ruido en la telemetría.

1.3.7

Cambios

El objetivo netcoreapp2.0 de SnapshotCollector depende de Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (de nuevo). Este cambio revierte el comportamiento a la manera en la que estaba antes de la versión 1.3.5. Hemos intentado actualizarlo en la versión 1.3.6, pero se han interrumpido algunos escenarios de App Service.

Nuevas características

Snapshot Collector lee y analiza la ConnectionString desde la variable de entorno APPLICATIONINSIGHTS_CONNECTION_STRING o desde TelemetryConfiguration. Principalmente, se usa para establecer el punto de conexión para conectarse al servicio de instantáneas. Para más información, consulte Cadenas de conexión.

Corrección de errores

Se ha cambiado al uso de HttpClient para todos los destinos excepto net45 porque WebRequest presentaba errores en algunos entornos debido a una incompatibilidad con SecurityProtocol (requiere TLS 1.2).

1.3.6

Cambios

  • SnapshotCollector depende ahora de Microsoft.ApplicationInsights>= 2.5.1 para todos los marcos de destino. Este requisito puede ser un cambio importante si la aplicación depende de una versión anterior del SDK de Microsoft.ApplicationInsights.
  • Se ha eliminado la compatibilidad con TLS 1.0 y 1.1 en el cargador de instantáneas.
  • El período de los exámenes de PDB ahora tiene un valor predeterminado de 24 horas en lugar de 15 minutos. Configurable a través de PdbRescanInterval en SnapshotCollectorConfiguration.
  • El examen de PDB busca solo en las carpetas de nivel superior, en lugar de una búsqueda recursiva. Este cambio puede ser un cambio importante si los símbolos están en subcarpetas de la carpeta de archivos binarios.

Nuevas características

  • Rotación del registro en SnapshotUploader para evitar que se llene la carpeta de registros con archivos antiguos.
  • Compatibilidad con la desoptimización (mediante ReJIT en adjuntos) para aplicaciones de .NET Core 3.0.
  • Se han agregado símbolos al paquete NuGet.
  • Establecer más metadatos al cargar minivolcados.
  • Se agregó una propiedad Initialized a SnapshotCollectorTelemetryProcessor. Es un CancellationToken, que se cancela cuando el Snapshot Collector se inicializa y se conecta al punto de conexión del servicio.
  • Ahora se pueden capturar instantáneas para excepciones en métodos generados dinámicamente. Un ejemplo son los árboles de expresión compilados generados por las consultas de Entity Framework.

Corrección de errores

  • Se produce la excepción AmbiguousMatchException en la carga de Snapshot Collector debido a Monitor de estado.
  • El método de extensión GetSnapshotCollector ahora busca en todos los TelemetrySinks.
  • No inicie el cargador de instantáneas en plataformas no compatibles.
  • Se controla InvalidOperationException al desoptimizar métodos dinámicos (por ejemplo, Entity Framework).

1.3.5

  • Se ha agregado compatibilidad con nubes soberanas (las versiones anteriores no funcionaban en nubes soberanas).
  • Agregar Snapshot Collector facilita el uso de AddSnapshotCollector(). Para obtener más información, consulte Habilitar Snapshot Debugger para aplicaciones .NET en Azure App Service.
  • Se utiliza la configuración de MD5 de FISMA para comprobar los bloques de blobs. Esta configuración evita el algoritmo criptográfico predeterminado MD5 de .NET, que no está disponible cuando el sistema operativo está establecido en el modo compatible con FIPS.
  • Se omiten los marcos de .NET Framework al desoptimizar las llamadas de función. Controle este comportamiento con la configuración DeoptimizeIgnoredModules.
  • Se ha agregado la opción de configuración DeoptimizeMethodCount, que permite la desoptimización de más de una llamada de función.

1.3.4

  • Claves de instrumentación estructuradas permitidas.
  • Mayor solidez de Snapshot Uploader. Se continua con el inicio incluso si no se pueden mover los registros anteriores del cargador.
  • Se han vuelto a habilitar los informes de telemetría adicionales cuando SnapshotUploader.exe se cierra inmediatamente (se deshabilitó en la versión 1.3.3).
  • Telemetría interna simplificada.
  • Característica experimental: planes de recopilación de puntos de instantánea. Agregar snapshotOnFirstOccurence. Para obtener más información, vea este artículo de GitHub.

1.3.3

Se ha corregido un error que provocaba que SnapshotUploader.exe dejara de responder y no cargara instantáneas de las aplicaciones de .NET Core.

1.3.2

  • Característica experimental: planes de recopilación de puntos de instantánea. Para obtener más información, vea este artículo de GitHub.
  • SnapshotUploader.exe se cierra cuando el entorno de ejecución descargue el AppDomain desde el que se carga SnapshotCollector, en lugar de esperar a que se cierre el proceso. Esta acción mejora la confiabilidad del recopilador cuando se hospeda en IIS.
  • Se ha agregado una configuración para permitir que varias instancias de SnapshotCollector que usan la misma clave de instrumentación compartan el mismo proceso de SnapshotUploader: ShareUploaderProcess (el valor predeterminado es true).
  • Se informan más datos de telemetría cuando SnapshotUploader.exe se cierra inmediatamente.
  • Se ha reducido el número de archivos auxiliares que necesita SnapshotUploader.exe para escribir en el disco.

1.3.1

  • Se ha eliminado la compatibilidad para recopilar instantáneas con la API RtlCloneUserProcess y solo se admite la API PssCaptureSnapshots.
  • Se ha aumentado de uno a tres el límite predeterminado del número de instantáneas que se pueden capturar en 10 minutos.
  • Se permite que SnapshotUploader.exe negocie TLS 1.1 y 1.2.
  • Se ha notificado más telemetría cuando SnapshotUploader registra una advertencia o un error.
  • Se dejan de tomar instantáneas cuando el servicio de back-end informa de que se ha alcanzado la cuota diaria (50 instantáneas al día).
  • Se ha agregado una comprobación adicional en SnapshotUploader.exe para no permitir que se ejecuten dos instancias al mismo tiempo.

1.3.0

Cambios

  • En el caso de las aplicaciones que tienen como destino .NET Framework, Snapshot Collector ahora depende de la versión 2.3.0 o superior de Microsoft.ApplicationInsights. Solía ser 2.2.0 o posterior. Creemos que este cambio no será un problema para la mayoría de las aplicaciones. Háganos saber si este cambio le impide utilizar la última versión de Snapshot Collector.
  • Se utilizan retrasos de retroceso exponencial en Snapshot Uploader al reintentar las cargas con errores.
  • Se utiliza ServerTelemetryChannel (si está disponible) para obtener informes de telemetría más confiables.
  • Se usa SdkInternalOperationsMonitor en la conexión inicial al servicio Snapshot Debugger para que el seguimiento de dependencias lo omita.
  • Se ha mejorado la telemetría en torno a la conexión inicial con Snapshot Debugger.
  • Informar más telemetría para:
    • Versión de App Service.
    • Instancias de proceso de Azure.
    • Contenedores.
    • Aplicación Azure Functions.

Corrección de errores

  • Cuando el intervalo de restablecimiento del contador de problemas se establece en 24 días, se interpretaba como 24 horas.
  • Se ha corregido un error que hacía que el cargador de instantáneas dejara de procesar nuevas instantáneas si se produjo una excepción al eliminar una instantánea.

1.2.3

Se ha corregido la firma de nombre seguro con los archivos binarios del cargador de instantáneas.

1.2.2

Cambios

  • Los archivos necesarios para SnapshotUploader(64).exe ahora se insertan como recursos en el archivo DLL principal. Esto significa que ya no se crea la carpeta SnapshotCollectorFiles, lo que simplifica la compilación y la implementación y reduce la aglomeración en el Explorador de soluciones. Tenga cuidado al realizar la actualización para revisar los cambios en el archivo .csproj. Ya no es necesario el archivo Microsoft.ApplicationInsights.SnapshotCollector.targets.
  • La telemetría se registra en el recurso de Application Insights incluso si ProvideAnonymousTelemetry está establecido en false. Este cambio es para que podamos implementar una característica de comprobación de estado en Azure Portal. ProvideAnonymousTelemetry afecta solo a la telemetría enviada a Microsoft para la mejora y soporte técnico del producto.
  • Cuando TempFolder o ShadowCopyFolder se redirigen a variables de entorno, mantenga inactivo el recopilador hasta que se establezcan esas variables de entorno.
  • En el caso de las aplicaciones que se conectan a Internet mediante un servidor proxy, Snapshot Collector ahora detecta automáticamente la configuración del proxy y la pasa a SnapshotUploader.exe.
  • Se reduce la prioridad del proceso SnapshotUploader (siempre que sea posible). La prioridad se puede invalidar a través de la opción IsLowPrioirtySnapshotUploader.
  • Se ha agregado el método de extensión GetSnapshotCollector en TelemetryConfiguration para escenarios en los que se desea configurar Snapshot Collector mediante programación.
  • Se establece la versión del SDK de Application Insights (en lugar de la versión de la aplicación) en la telemetría orientada al cliente.
  • Se envía el primer evento de latido después de dos minutos.

Corrección de errores

  • Se ha corregido NullReferenceException cuando las excepciones tienen diccionarios de datos nulos o inmutables.
  • En el cargador, se vuelve a intentar la coincidencia de PDB varias veces si se obtiene una infracción de uso compartido.
  • Se han corregido los datos de telemetría duplicados cuando más de un subproceso llama a la canalización de telemetría en el inicio.

1.2.1

Cambios

  • Los archivos de comentarios de documentos XML se incluyen ahora en el paquete NuGet.
  • Se ha agregado el método de extensión ExcludeFromSnapshotting en System.Exception para escenarios en los que sabe que tiene una excepción ruidosa y desea evitar la creación de instantáneas para ella.
  • Se ha añadido una propiedad de configuración IsEnabledWhenProfiling que de forma predeterminada es true. Se trata de un cambio respecto a las versiones anteriores, en las que la creación de instantáneas estaba deshabilitada temporalmente si Application Insights Profiler estaba realizando una recopilación detallada. El comportamiento anterior se puede recuperar si se establece esta propiedad en false.

Corrección de errores

  • Se firma SnapshotUploader64.exe correctamente.
  • Se protege frente a una inicialización doble del procesador de telemetría.
  • Se evita el doble registro de datos de telemetría en aplicaciones con varias canalizaciones.
  • Se ha corregido un error con la fecha de expiración de un plan de recopilación, lo que podría impedir las instantáneas después de 24 horas.

1.2.0

El cambio más importante en esta versión (de ahí el traslado a un nuevo número de versión secundaria) es una reescritura de la canalización de creación y control de instantáneas. En versiones anteriores, esta funcionalidad se implementaba en código nativo (ProductionBreakpoints.dll* y SnapshotHolder.exe*). La nueva implementación es todo código administrado con P/Invoke.

Esta primera versión que usa la nueva canalización no se ha alejado del comportamiento original. La nueva implementación permite un mejor informe de errores y nos prepara para futuras mejoras.

Otros cambios en esta versión

  • Se ha cambiado el nombre de MinidumpUploader.exe a SnapshotUploader.exe (o SnapshotUploader64.exe).
  • Se ha agregado telemetría de temporización a las solicitudes para desoptimizar o volver a optimizar.
  • Se ha agregado compresión gzip para las cargas de minivolcados.
  • Se ha corregido un problema en el que los archivos PDB estaban bloqueados, lo que impide la actualización del sitio.
  • Se registra el nombre de la carpeta original (SnapshotCollectorFiles) en la creación de instantáneas.
  • Se han ajustado los límites de memoria para los procesos de 64 bits para evitar que se reinicie el sitio debido a OOM.
  • Se ha corregido un problema en el que las instantáneas se recopilaban incluso después de la deshabilitación.
  • Se registran los eventos de latido en el recurso de IA del cliente.
  • Se ha mejorado la velocidad de las instantáneas mediante la eliminación del elemento "Source" del identificador del problema.

1.1.2

Cambios

  • Se ha aumentado los datos de telemetría sobre el uso.
  • Se detecta y se informa sobre la versión de .NET y el sistema operativo.
  • Detecte y notifique más entornos de Azure (Azure Cloud Services, Azure Service Fabric).
  • Se registra y se informa sobre las métricas de excepción (el número de excepciones de primera oportunidad y el número de llamadas a TrackException) en la telemetría de los latidos.

Corrección de errores

  • Se ha corregido el control de SqlException en el que no se produce la excepción interna (Win32Exception).
  • Se han recortado los espacios finales de las carpetas de símbolos, lo que provocaba un análisis incorrecto de los argumentos de la línea de comandos para MinidumpUploader.
  • Se impide el reintento infinito de conexiones erróneas con el punto de conexión del agente de Snapshot Debugger.

1.1.0

Cambios

  • Se ha agregado la protección de la memoria del host. Esta característica reduce el impacto en la memoria del equipo host.
  • Se ha mejorado la experiencia de visualización de instantáneas en Azure Portal.